SDK vs API

When to use the SDK vs the 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

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"
    }
  }'

JavaScript

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

<?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.