Skip to main content

​
Overview

Every Chainrails transaction follows three simple steps from setup to completion:

​
Request a Quote

Define the parameters for the transaction (the intent) — amount, source chain, source token, destination chain, recipient, and refund address. This tells Chainrails what the user wants to send and where it’s going.

​
Generate an Intent Address

Once the quote is confirmed, Chainrails creates a unique intent address for that transaction. Think of this as a one-time deposit address that tracks and processes the transfer logic automatically.

​
Fund the Intent

The user then funds this intent address directly from their wallet. Once funded, Chainrails takes care of the rest — executing the cross-chain transfer, routing liquidity, and confirming settlement. The SDK abstracts most of these steps, so you can integrate this entire flow in just a few lines of code. In this Quickstart, we’ll walk you through how to get up and running in minutes.

​
Get started in three steps

1

Installation

Begin by installing the Chainrails React SDK.
npm install @chainrails/react @chainrails/sdk
2

Set up a Session Endpoint

Create a backend endpoint that generates secure session tokens. This protects your API key and prevents abuse.
Here’s a curated Github template to help you get started quickly: Chainrails Demo Server
import { Chainrails, crapi } from "@chainrails/sdk";

app.get("/create-session", async (req, res) => {
  const api_key = process.env.CHAINRAILS_API_KEY;
  const amount = "100";
  const recipient = "0x...";
  const destinationChain = "BASE";
  const token = "USDC";

  Chainrails.config({
    api_key,
  });

  const session = await crapi.auth.getSessionToken({
    amount: amount,
    recipient: recipient,
    destinationChain: destinationChain,
    token: token,
  });

  res.send(session);
});
Where:
  • recipient: Your wallet address to receive payments/deposits.
  • amount: The amount to be paid/deposited. Leave empty or set to 0 to allow user input.
  • destinationChain: The blockchain network to receive payments to.
  • token: The token/currency you want to receive.
  • amount: The amount to be paid/deposited. Leave empty or set to 0 to allow user input.
3

Initialize the Payment Modal

Import and initialize the Chainrails payment modal in your application.
import { chains, tokens, PaymentModal, usePaymentSession } from "@chainrails/react"

function App() {
  const cr = usePaymentSession({
    session_url: "https://your-server.com/create-session",
    onSuccess: () => {
      console.log("Payment Successful")
    },
  })

  return (
    <div>
      <button onClick={cr.open}>Pay with Crypto</button>
      <PaymentModal {...cr} />
    </div>
  )
}
Parameters:
  • session_url: Your server endpoint for creating payment sessions.
  • excludeChains (optional): Array of chains to exclude from payment options.
For more detailed instructions, refer to the Payment Modal Documentation.

​
What happens next?

When users click the payment button:
  1. The SDK fetches a secure session token from your backend
  2. Users see the payment modal with their wallet connection options
  3. They can pay from any supported chain/token (Chainrails handles bridging)
  4. Your onSuccess callback fires when the transaction completes
  5. Funds arrive in your recipient address on your chosen chain

View Github Code

Explore a complete example of the Payment Modal integration in our GitHub repository.