SDK vs API

Chainrails offers both client SDKs and a RESTful API, each designed for different needs and levels of abstraction.

The SDK

Chainrails SDKs provide the fastest way to integrate payments in TypeScript/JavaScript applications. They wrap our APIs and handle authentication, retries, UI flows, and session-based payment experiences for you. We recommend using the SDK for:

Web applications and dApps that requires a pre-built modal
React Native mobile applications that also don’t mind a pre-built modal
Quick prototyping
JavaScript/TypeScript projects
Reducing boilerplate (no need to manually handle HTTP or auth)

The SDK surface includes:

@chainrails/sdk for core API access
@chainrails/react for React web integrations
@chainrails/react-native for React Native integrations

Sample integration

Installation

npm install @chainrails/react @chainrails/sdk

For React Native apps:

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

Usage First, create a server endpoint for session creation:

// Example with Express.js
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: process.env.CHAINRAILS_API_KEY
  });

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

  res.send(session);
});

Then use the SDK on the client:

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}> Open Modal </button>
      <PaymentModal {...cr} />
    </div>
  );
}

For more details on the SDK, check out our SDK Reference and Quickstart guides.

The API

The Chainrails API gives you direct access to the underlying infrastructure — perfect if you want full control over how requests, authentication, and responses are handled. You’ll interact with our endpoints directly using your preferred language or HTTP client. We recommend using the API for:

Server-side integrations
Advanced use cases requiring fine-grained control
Teams working in non-JavaScript environments

Sample request to create a cross-chain intent

cURL
JavaScript
PHP

curl -X POST "https://api.chainrails.io/api/v1/intents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "sender": "0xdA3ECb2E5362295E2b802669dD47127A61d9Ce54",
    "amount": "1000000",
    "amountSymbol": "USDC",
    "tokenIn": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "source_chain": "BASE_TESTNET",
    "destination_chain": "ARBITRUM_TESTNET",
    "recipient": "0xb79541Be080a59fdcE6C0b43219ba56c725eC65e",
    "refund_address": "0xb79541Be080a59fdcE6C0b43219ba56c725eC65e",
    "metadata": {
      "description": "Cross-chain USDC transfer",
      "priority": "normal"
    }
  }'

const fetch = require("node-fetch");

const url = "https://api.chainrails.io/api/v1/intents";
const apiKey = "YOUR_API_KEY";

const payload = {
sender: "0xdA3ECb2E5362295E2b802669dD47127A61d9Ce54",
amount: "1000000",
amountSymbol: "USDC",
tokenIn: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
source_chain: "BASE_TESTNET",
destination_chain: "ARBITRUM_TESTNET",
recipient: "0xb79541Be080a59fdcE6C0b43219ba56c725eC65e",
refund_address: "0xb79541Be080a59fdcE6C0b43219ba56c725eC65e",
metadata: {
description: "Cross-chain USDC transfer",
priority: "normal",
},
};

async function createIntent() {
const res = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${apiKey}`,
},
body: JSON.stringify(payload),
});

const data = await res.json();
console.log("Response:", data);
}

createIntent().catch(console.error);

<?php

$url = "https://api.chainrails.io/api/v1/intents";
$apiKey = "YOUR_API_KEY";

$data = [
  "sender" => "0xdA3ECb2E5362295E2b802669dD47127A61d9Ce54",
  "amount" => 1000000,
  "amountSymbol" => "USDC",
  "tokenIn" => "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
  "source_chain" => "BASE_TESTNET",
  "destination_chain" => "ARBITRUM_TESTNET",
  "recipient" => "0xb79541Be080a59fdcE6C0b43219ba56c725eC65e",
  "refund_address" => "0xb79541Be080a59fdcE6C0b43219ba56c725eC65e",
  "metadata" => [
    "description" => "Cross-chain USDC transfer",
    "priority" => "normal"
  ]
];

$ch = curl_init($url);

curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Authorization: Bearer $apiKey"
  ],
  CURLOPT_POSTFIELDS => json_encode($data),
]);

$response = curl_exec($ch);

if (curl_errno($ch)) {
  echo 'Error: ' . curl_error($ch);
} else {
  echo "Response: " . $response;
}

curl_close($ch);
?>

For more details on the API, check out our API Reference.

Introduction

Concepts

Developer Guides

Essentials

The SDK

Sample integration

The API

Sample request to create a cross-chain intent

​The SDK

​Sample integration

​The API

​Sample request to create a cross-chain intent

The SDK

Sample integration

The API

Sample request to create a cross-chain intent