SDK vs API

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

The SDK

The Chainrails SDK is a lightweight JavaScript/TypeScript library that wraps our APIs and handles authentication, retries, and refunds automatically for you. It’s the easiest way to get started in minutes. We recommend using the SDK for:

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

Sample integration

Installation

npm install @chainrails/react

Usage

import { chains, tokens, PaymentModal, usePaymentModal, Chainrails } from "@chainrails/react";

Chainrails.config({ api_key: <ENTER_API_KEY> })

function App() {
  const cr = usePaymentModal({
    to: "0x4F41BCf288E718A36c1e6919c2Dfc2E07d51c675",
    chain: chains.BASE,
    token: tokens.USDC,
    onCancel: () => {
      console.log("Payment Cancelled")
    },
    onSuccess: () => {
      console.log("Payment Successful")
    }
  })

  return (
    <div>
      <button onClick={cr.open} className="border my-4 py-2 px-4 cursor-pointer">
        Open Modal
      </button>

      {/* Pass 'amount' here to set a fixed amount.
        If you remove the amount prop, the user can input their own.
      */}
      <PaymentModal {...cr} amount={1}/>
    </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 building mobile apps or within 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",
    "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",
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,
  "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

How it works

Developer Guides

Essentials

Changelog & Roadmap

The SDK

Sample integration

The API

Sample request to create a cross-chain intent

Introduction

How it works

Developer Guides

Essentials

Changelog & Roadmap

​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