Quickstart

Overview

Chainrails gives you a single payment modal that supports both:

Crypto deposits from supported chains and tokens
Fiat deposits from 70+ countries

This quickstart is focused on getting the modal live in minutes. You will install the SDK, create a secure session endpoint, and open the modal from your app.

Get started in three steps

This quickstart uses the React web SDK. If you’re building for React Native, use @chainrails/react-native with the same backend session endpoint pattern described below.

Installation

Install the UI SDK for your app and the core SDK for your backend session endpoint.

React Web
React Native

npm install @chainrails/react @chainrails/sdk

npm install @chainrails/react-native @chainrails/sdk

Set up a Session Endpoint

Create a backend endpoint that generates secure session tokens. This keeps your API key private and lets you control payment defaults.

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_MAINNET";
  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: Wallet address that receives settled funds.
amount: Target amount. Leave empty or set to 0 to let users enter an amount in the modal.
destinationChain: Chain where funds should settle.
token: Asset to receive on settlement.

These defaults work for both crypto and fiat deposit journeys in the modal.

Initialize the Payment Modal

Initialize the modal in your app and trigger it from a button.

import { PaymentModal, usePaymentSession } from "@chainrails/react";

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

  return (
    <div>
      <button onClick={cr.open}>Pay with Crypto or Fiat</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 deeper configuration options, see the Payment Modal documentation.

What happens next?

When a user opens the modal:

The SDK fetches a secure session token from your backend
The modal presents available payment methods
Users can complete a crypto deposit from supported chains/tokens or a fiat deposit through supported ramp providers
Your onSuccess callback fires when the transaction completes
Funds settle to your configured recipient and destination chain

Additional Notes

Live API keys cannot be used with test networks. In test environments you can use supported mainnets and testnets, but live API keys must use mainnet networks only.
Testnets do not have indexing support. In modal flows, users must click I have made payment after funding on testnets. In API-driven flows, use POST /api/v1/intents/{intent_address}/trigger-processing to process the intent manually.

View Github Code

Explore a complete Payment Modal example in our Github repository.

Introduction

Concepts

Developer Guides

Essentials

Overview

Get started in three steps

What happens next?

Additional Notes

View Github Code

​Overview

​Get started in three steps

​What happens next?

​Additional Notes

View Github Code

Overview

Get started in three steps

What happens next?

Additional Notes