Complete Ramping Guide

This guide walks through a complete Chainrails ramp integration: discovering supported corridors, requesting quotes, completing KYC when required, creating an order, presenting payment instructions or a hosted widget, and monitoring the order until completion.

Overview

Chainrails aggregates fiat ramp providers behind one API. A user can on-ramp fiat into USDC on a supported destination chain, or off-ramp supported tokens from a source chain into local fiat. There are two execution flows:

Flow	How to identify it	KYC owner	User experience
Headless/direct	The selected quote’s payment channel has `transferType: "direct"`	Chainrails	You collect the required fields, complete Chainrails KYC, and show payment or deposit instructions in your interface.
Widget/redirect	The selected quote’s payment channel has `transferType: "widget"`	Ramp provider	Create the order, redirect the user to `widgetUrl`, and let the provider collect KYC and payment details.

For headless providers, Chainrails has been built to minimize KYC friction. You only need to KYC once per user to access multiple liquidity providers, and you can submit only the fields that are missing or insufficient for each selected provider.

Before you begin

You need:

a Chainrails account;
a test or live API key from the Chainrails dashboard;
completed Chainrails KYB to access live fiat endpoints;

All examples use:

Base URL: https://api.chainrails.io
Authorization: Bearer YOUR_API_KEY

Keep API keys on your server. Do not expose them in browser or mobile application code.

End-to-end flow

The integration sequence is:

Retrieve supported countries for the requested direction and amount.
Request quotes using the selected country and currency.
Select a quote and inspect its transferType and fieldsRequired.
For a headless quote, complete the Chainrails KYC loop.
Create the ramp order using the selected provider.
Show transferInstructions for a headless order or open widgetUrl for a hosted order.
Poll the order until it reaches a terminal status.

1. Retrieve supported countries

Use the countries endpoint to build your country and currency selector:

GET /api/v1/ramp/countries

Recommended query parameters:

Parameter	Required	Description
`type`	Recommended	`on-ramp` or `off-ramp`. Off-ramp returns only countries with direct off-ramp support.
`amount`	Recommended	Intended crypto amount in USD/USDC terms. Filters out currencies whose configured minimum exceeds the amount.
`currency`	No	ISO 4217 currency filter such as `NGN` or `XOF`.

cURL
JavaScript
PHP

curl --request GET \
  --url "https://api.chainrails.io/api/v1/ramp/countries?type=on-ramp&amount=25" \
  --header "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  "https://api.chainrails.io/api/v1/ramp/countries?type=on-ramp&amount=25",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
);
const countries = await response.json();

<?php
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/countries?type=on-ramp&amount=25");
curl_setopt_array($curl, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY"],
]);
$countries = json_decode(curl_exec($curl), true);
curl_close($curl);

Example response:

[
  {
    "countryCode": "NG",
    "name": "Nigeria",
    "currency": {
      "code": "NGN",
      "name": "Nigerian Naira",
      "symbol": "₦",
      "minAmount": 1,
      "providers": ["YELLOW_CARD", "FONBNK", "ONRAMP_MONEY"]
    }
  }
]

Use the countries endpoint instead of deriving a country from a currency. Multiple countries can share a currency, while provider availability and KYC requirements can differ by country. You can also inspect currencies directly:

cURL
JavaScript
PHP

curl --request GET \
  --url "https://api.chainrails.io/api/v1/ramp/currencies?type=on-ramp" \
  --header "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  "https://api.chainrails.io/api/v1/ramp/currencies?type=on-ramp",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
);
const currencies = await response.json();

<?php
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/currencies?type=on-ramp");
curl_setopt_array($curl, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY"],
]);
$currencies = json_decode(curl_exec($curl), true);
curl_close($curl);

2. Request quotes

GET /api/v1/ramp/quotes

On-ramp quote

cURL
JavaScript
PHP

curl --request GET \
  --url "https://api.chainrails.io/api/v1/ramp/quotes?type=on-ramp&fiatCurrency=NGN&cryptoAmount=25&destinationChain=BASE_MAINNET&countryCode=NG&[email protected]" \
  --header "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  type: "on-ramp", fiatCurrency: "NGN", cryptoAmount: "25",
  destinationChain: "BASE_MAINNET", countryCode: "NG",
  userEmail: "[email protected]",
});
const response = await fetch(`https://api.chainrails.io/api/v1/ramp/quotes?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const quotes = await response.json();

<?php
$query = http_build_query([
  "type" => "on-ramp", "fiatCurrency" => "NGN", "cryptoAmount" => 25,
  "destinationChain" => "BASE_MAINNET", "countryCode" => "NG",
  "userEmail" => "[email protected]",
]);
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/quotes?$query");
curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY"]]);
$quotes = json_decode(curl_exec($curl), true);
curl_close($curl);

Off-ramp quote

cURL
JavaScript
PHP

curl --request GET \
  --url "https://api.chainrails.io/api/v1/ramp/quotes?type=off-ramp&fiatCurrency=NGN&cryptoAmount=25&sourceChain=BASE_MAINNET&amountSymbol=USDC&countryCode=NG&[email protected]" \
  --header "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  type: "off-ramp", fiatCurrency: "NGN", cryptoAmount: "25",
  sourceChain: "BASE_MAINNET", amountSymbol: "USDC", countryCode: "NG",
  userEmail: "[email protected]",
});
const response = await fetch(`https://api.chainrails.io/api/v1/ramp/quotes?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const quotes = await response.json();

<?php
$query = http_build_query([
  "type" => "off-ramp", "fiatCurrency" => "NGN", "cryptoAmount" => 25,
  "sourceChain" => "BASE_MAINNET", "amountSymbol" => "USDC",
  "countryCode" => "NG", "userEmail" => "[email protected]",
]);
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/quotes?$query");
curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY"]]);
$quotes = json_decode(curl_exec($curl), true);
curl_close($curl);

Quote parameters:

Parameter	On-ramp	Off-ramp	Description
`type`	Required	Required	`on-ramp` or `off-ramp`.
`fiatCurrency`	Required	Required	ISO 4217 fiat currency.
`cryptoAmount`	Required	Required	Amount the user receives for on-ramp or sells for off-ramp.
`destinationChain`	Required	—	Final chain for on-ramped USDC.
`sourceChain`	—	Required	Chain where the off-ramp asset is held.
`amountSymbol`	—	Optional	Token represented by `cryptoAmount`; defaults to `USDC`.
`countryCode`	Recommended	Recommended	Transaction corridor country. Required for shared currencies such as XOF, EUR.
`userEmail`	Recommended	Recommended	Allows recommendations to filter for provider with least KYC friction for the user profile.
`directOnly`	Optional	Optional	Set to `true` to exclude widget/redirect quotes.

An abbreviated quote response looks like this:

{
  "recommended": {
    "provider": "YELLOW_CARD",
    "fiatCurrency": "NGN",
    "fiatAmount": 35000,
    "cryptoCurrency": "USDC",
    "cryptoAmount": 25,
    "totalFeesUsd": 0.25,
    "paymentChannels": [
      {
        "channel": "bank_transfer",
        "transferType": "direct",
        "directTransferDetails": {
          "fieldsRequired": [
            {
              "key": "accountNumber",
              "label": "Bank account number",
              "type": "string",
              "required": false
            }
          ]
        }
      }
    ]
  },
  "quotes": [
    {
      "provider": "YELLOW_CARD",
      "fiatCurrency": "NGN",
      "fiatAmount": 35000,
      "cryptoCurrency": "USDC",
      "cryptoAmount": 25,
      "totalFeesUsd": 0.25,
      "paymentChannels": [
        {
          "channel": "bank_transfer",
          "transferType": "direct",
          "directTransferDetails": {
            "fieldsRequired": [
              {
                "key": "accountNumber",
                "label": "Bank account number",
                "type": "string",
                "required": false
              }
            ]
          }
        }
      ]
    }
  ],
  "providersQueried": 3
}

The real response includes the full quote list. The chosen recommended quote creates a balance between price, remaining KYC friction, pending or blocked KYC state, and direct-flow availability.

3. Determine whether KYC is required

Inspect the selected quote’s payment channel:

{
  "transferType": "direct"
}

For a direct/headless quote, check Chainrails KYC before creating the order. For the underlying profile model, assurance levels, and verification states, see Know Your Customer (KYC).

{
  "transferType": "widget"
}

For a widget quote, skip the Chainrails KYC endpoints. Create the order and redirect the user to the returned widgetUrl; the provider owns the verification flow.

Inspect provider requirements

This endpoint describes the applicable policy without inspecting a user:

GET /api/v1/ramp/kyc/requirements

cURL
JavaScript
PHP

curl --request GET \
  --url "https://api.chainrails.io/api/v1/ramp/kyc/requirements?provider=YELLOW_CARD&countryCode=NG&fiatCurrency=NGN" \
  --header "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({ provider: "YELLOW_CARD", countryCode: "NG", fiatCurrency: "NGN" });
const response = await fetch(`https://api.chainrails.io/api/v1/ramp/kyc/requirements?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const requirements = await response.json();

<?php
$query = http_build_query(["provider" => "YELLOW_CARD", "countryCode" => "NG", "fiatCurrency" => "NGN"]);
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/kyc/requirements?$query");
curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY"]]);
$requirements = json_decode(curl_exec($curl), true);
curl_close($curl);

Example response:

{
  "provider": "YELLOW_CARD",
  "requiredFields": [
    { "key": "email", "assurance": "provided" },
    { "key": "first_name", "assurance": "verified" },
    { "key": "last_name", "assurance": "verified" },
    { "key": "phone", "assurance": "provided" },
    { "key": "country", "assurance": "provided" },
    { "key": "address", "assurance": "provided" },
    { "key": "date_of_birth", "assurance": "verified" },
    { "key": "nin", "assurance": "verified" },
    { "key": "bvn", "assurance": "verified" }
  ],
  "requiredCapabilities": [],
  "validationMethods": ["text", "external"],
  "textDocuments": ["bvn", "nin"],
  "maxTransactionAmountUsd": null
}

assurance: "provided" means Chainrails needs a stored value. assurance: "verified" means the field must be validated by an accepted verification source.

Get the user’s KYC state

GET /api/v1/ramp/kyc

cURL
JavaScript
PHP

curl --request GET \
  --url "https://api.chainrails.io/api/v1/ramp/kyc?provider=YELLOW_CARD&countryCode=NG&fiatCurrency=NGN&[email protected]&cryptoAmount=25" \
  --header "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  provider: "YELLOW_CARD", countryCode: "NG", fiatCurrency: "NGN",
  userEmail: "[email protected]", cryptoAmount: "25",
});
const response = await fetch(`https://api.chainrails.io/api/v1/ramp/kyc?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const state = await response.json();

<?php
$query = http_build_query(["provider" => "YELLOW_CARD", "countryCode" => "NG", "fiatCurrency" => "NGN", "userEmail" => "[email protected]", "cryptoAmount" => 25]);
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/kyc?$query");
curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY"]]);
$state = json_decode(curl_exec($curl), true);
curl_close($curl);

The state response separates requirements into actionable groups:

Property	Meaning
`missingRequirements`	No value or verification exists yet.
`insufficientRequirements`	A value exists, but its assurance is lower than the policy requires.
`pendingRequirements`	Verification is still processing.
`rejectedRequirements`	The latest verification was rejected. Correct the relevant input before retrying.
`blockedRequirements`	Manual review is required. Normal submission cannot resolve the state.
`satisfiedRequirements`	Field requirements already fulfilled.
`requiredCapabilities`	Verification capabilities still required.
`satisfiedCapabilities`	Completed capabilities, such as `external_verification`.

Continue directly to order creation when:

{
  "canProceed": true,
  "blocked": false
}

When blocked is true, show a message asking the user to contact support. Do not repeatedly resubmit the same identity data.

4. Complete headless KYC

KYC submission uses one endpoint for profile creation, field storage, text-document checks, and hosted external verification:

POST /api/v1/ramp/kyc

Only userEmail, provider, countryCode, and fiatCurrency are required. Include any user information you already have/can obtain in fields (derived from checking provider’s requirements); the engine determines what can be stored, validated, or sent to an external verification flow.

countryCode is the transaction corridor country. fields.country is the user’s current country of residence. They are intentionally separate and do not always need to match.

Text verification flow

The text verification flow provides the least friction. Currently available for just Nigeria, but will be expanded to more countries in the future. Submit the available profile fields and required text documents:

cURL
JavaScript
PHP

curl --request POST \
  --url "https://api.chainrails.io/api/v1/ramp/kyc" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "userEmail": "[email protected]",
    "provider": "YELLOW_CARD",
    "countryCode": "NG",
    "fiatCurrency": "NGN",
    "cryptoAmount": 25,
    "fields": {
      "first_name": "Ada",
      "last_name": "Okafor",
      "phone": "+2348012345678",
      "date_of_birth": "1994-06-15",
      "country": "NG",
      "address": "12 Example Street, Lagos",
      "BVN": "12345678901",
      "NIN": "98765432109"
    }
  }'

const payload = {
  userEmail: "[email protected]", provider: "YELLOW_CARD", countryCode: "NG",
  fiatCurrency: "NGN", cryptoAmount: 25,
  fields: {
    first_name: "Ada", last_name: "Okafor", phone: "+2348012345678",
    date_of_birth: "1994-06-15", country: "NG", address: "12 Example Street, Lagos",
    BVN: "12345678901", NIN: "98765432109",
  },
};
const response = await fetch("https://api.chainrails.io/api/v1/ramp/kyc", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
const result = await response.json();

<?php
$payload = [
  "userEmail" => "[email protected]", "provider" => "YELLOW_CARD",
  "countryCode" => "NG", "fiatCurrency" => "NGN", "cryptoAmount" => 25,
  "fields" => ["first_name" => "Ada", "last_name" => "Okafor", "phone" => "+2348012345678", "date_of_birth" => "1994-06-15", "country" => "NG", "address" => "12 Example Street, Lagos", "BVN" => "12345678901", "NIN" => "98765432109"],
];
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/kyc");
curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode($payload)]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

Use uppercase BVN and NIN in the public submission payload. Both values must contain exactly 11 digits. Chainrails validates the documents and compares the returned identity against the submitted names and DOB. Phone and address are mutable fields and do not need an exact registry match.

External document and biometric verification

Outside Nigeria, Chainrails requires the external_verification capability. You can start with only the fields you already have:

cURL
JavaScript
PHP

curl --request POST \
  --url "https://api.chainrails.io/api/v1/ramp/kyc" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "userEmail": "[email protected]",
    "provider": "YELLOW_CARD",
    "countryCode": "KE",
    "fiatCurrency": "KES",
    "cryptoAmount": 25,
    "callbackUrl": "https://app.example.com/kyc/complete",
    "fields": {
      "country": "KE",
      "address": "1 Example Road, Nairobi"
    }
  }'

const payload = {
  userEmail: "[email protected]", provider: "YELLOW_CARD", countryCode: "KE",
  fiatCurrency: "KES", cryptoAmount: 25,
  callbackUrl: "https://app.example.com/kyc/complete",
  fields: { country: "KE", address: "1 Example Road, Nairobi" },
};
const response = await fetch("https://api.chainrails.io/api/v1/ramp/kyc", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
const result = await response.json();

<?php
$payload = [
  "userEmail" => "[email protected]", "provider" => "YELLOW_CARD",
  "countryCode" => "KE", "fiatCurrency" => "KES", "cryptoAmount" => 25,
  "callbackUrl" => "https://app.example.com/kyc/complete",
  "fields" => ["country" => "KE", "address" => "1 Example Road, Nairobi"],
];
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/kyc");
curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode($payload)]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

When external verification is required, the response includes:

{
  "profileId": "profile-id",
  "fields": [],
  "state": {
    "canProceed": false,
    "requiredCapabilities": ["external_verification"]
  },
  "verification": {
    "method": "external",
    "sessionId": "session-id",
    "url": "https://verify.didit.me/session/example",
    "status": "not_started"
  }
}

Open verification.url in the same tab, a new tab, or an embedded browser appropriate for your application. callbackUrl controls where the hosted flow returns the user. Chainrails receives the provider webhook asynchronously. Returning to callbackUrl does not by itself mean KYC is approved. Poll GET /api/v1/ramp/kyc until one of these outcomes occurs:

canProceed: true — continue to order creation;
pendingRequirements is non-empty — keep waiting and poll again;
blocked: true — stop and direct the user to support;
missing or insufficient fields remain — collect and submit only those fields.

Progressive KYC loop

Do not render one large static form. Build the next form from the latest state:

Read missingRequirements, rejectedRequirements, and insufficientRequirements.
Ask only for those field requirements, dependent on what the provider needs.
Submit the fields to /api/v1/ramp/kyc with the same provider and corridor context.
If a verification URL is returned, send the user through it.
Poll /api/v1/ramp/kyc.
Continue when canProceed is true.

The profile is keyed by normalized email and reused across future transactions. Email ownership verification is the responsibility of your application; the KYC API does not send or validate an email OTP.

5. Create the ramp order

POST /api/v1/ramp/orders

The provider must come from the selected quote. Chainrails fetches a fresh quote during order creation, so you do not pass the previous quoteId.

Headless on-ramp order

cURL
JavaScript
PHP

curl --request POST \
  --url "https://api.chainrails.io/api/v1/ramp/orders" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "on-ramp",
    "provider": "YELLOW_CARD",
    "fiatCurrency": "NGN",
    "cryptoAmount": 25,
    "destinationChain": "BASE_MAINNET",
    "recipientAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "countryCode": "NG",
    "userEmail": "[email protected]",
    "fields": {
      "accountNumber": "0123456789"
    }
  }'

const payload = {
  type: "on-ramp", provider: "YELLOW_CARD", fiatCurrency: "NGN", cryptoAmount: 25,
  destinationChain: "BASE_MAINNET",
  recipientAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  countryCode: "NG", userEmail: "[email protected]",
  fields: { accountNumber: "0123456789" },
};
const response = await fetch("https://api.chainrails.io/api/v1/ramp/orders", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
const order = await response.json();

<?php
$payload = [
  "type" => "on-ramp", "provider" => "YELLOW_CARD", "fiatCurrency" => "NGN", "cryptoAmount" => 25,
  "destinationChain" => "BASE_MAINNET", "recipientAddress" => "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "countryCode" => "NG", "userEmail" => "[email protected]", "fields" => ["accountNumber" => "0123456789"],
];
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/orders");
curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode($payload)]);
$order = json_decode(curl_exec($curl), true);
curl_close($curl);

Only include keys requested by the selected quote’s fieldsRequired. A field with required: false can be omitted. Example headless response:

{
  "id": 475,
  "direction": "ON_RAMP",
  "status": "ORDER_INITIATED",
  "provider": "YELLOW_CARD",
  "providerOrderId": "provider-order-id",
  "fiatCurrency": "NGN",
  "fiatAmount": 35000,
  "cryptoCurrency": "USDC",
  "cryptoAmount": 25,
  "paymentChannel": "bank_transfer",
  "transferInstructions": {
    "type": "bank_transfer",
    "bankName": "Example Bank",
    "accountName": "Example Account",
    "accountNumber": "0123456789",
    "reference": "ABC123"
  },
  "widgetUrl": null,
  "expiresAt": "2026-08-12T01:30:00.000Z",
  "destinationChain": "BASE_MAINNET",
  "recipientAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
}

Show the transfer instructions and expiry to the user. The user should send the exact fiat amount and include the reference when one is provided. For a quote with transferType: "widget", do not call the Chainrails KYC endpoints first:

cURL
JavaScript
PHP

curl --request POST \
  --url "https://api.chainrails.io/api/v1/ramp/orders" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "on-ramp",
    "provider": "FONBNK",
    "fiatCurrency": "NGN",
    "cryptoAmount": 25,
    "destinationChain": "BASE_MAINNET",
    "recipientAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "countryCode": "NG"
  }'

const payload = {
  type: "on-ramp", provider: "FONBNK", fiatCurrency: "NGN", cryptoAmount: 25,
  destinationChain: "BASE_MAINNET", recipientAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  countryCode: "NG",
};
const response = await fetch("https://api.chainrails.io/api/v1/ramp/orders", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
const order = await response.json();

<?php
$payload = ["type" => "on-ramp", "provider" => "FONBNK", "fiatCurrency" => "NGN", "cryptoAmount" => 25, "destinationChain" => "BASE_MAINNET", "recipientAddress" => "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "countryCode" => "NG"];
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/orders");
curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode($payload)]);
$order = json_decode(curl_exec($curl), true);
curl_close($curl);

The response contains a hosted URL:

{
  "id": 476,
  "status": "ORDER_INITIATED",
  "provider": "FONBNK",
  "transferInstructions": null,
  "widgetUrl": "https://provider.example/checkout/..."
}

Redirect the user to widgetUrl. The provider collects its own KYC and payment information there. Do not send Chainrails KYC documents through the order fields object.

Headless off-ramp order

Off-ramp quotes expose payout fields and, where applicable, selectable networkId options. Use the option values exactly as returned by the quote.

cURL
JavaScript
PHP

curl --request POST \
  --url "https://api.chainrails.io/api/v1/ramp/orders" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "off-ramp",
    "provider": "YELLOW_CARD",
    "fiatCurrency": "NGN",
    "cryptoAmount": 25,
    "sourceChain": "BASE_MAINNET",
    "amountSymbol": "USDC",
    "senderAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "countryCode": "NG",
    "userEmail": "[email protected]",
    "fields": {
      "accountNumber": "0123456789",
      "accountName": "Ada Okafor",
      "networkId": "NETWORK_ID_FROM_QUOTE"
    }
  }'

const payload = {
  type: "off-ramp", provider: "YELLOW_CARD", fiatCurrency: "NGN", cryptoAmount: 25,
  sourceChain: "BASE_MAINNET", amountSymbol: "USDC",
  senderAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  countryCode: "NG", userEmail: "[email protected]",
  fields: { accountNumber: "0123456789", accountName: "Ada Okafor", networkId: "NETWORK_ID_FROM_QUOTE" },
};
const response = await fetch("https://api.chainrails.io/api/v1/ramp/orders", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
const order = await response.json();

<?php
$payload = ["type" => "off-ramp", "provider" => "YELLOW_CARD", "fiatCurrency" => "NGN", "cryptoAmount" => 25, "sourceChain" => "BASE_MAINNET", "amountSymbol" => "USDC", "senderAddress" => "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "countryCode" => "NG", "userEmail" => "[email protected]", "fields" => ["accountNumber" => "0123456789", "accountName" => "Ada Okafor", "networkId" => "NETWORK_ID_FROM_QUOTE"]];
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/orders");
curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode($payload)]);
$order = json_decode(curl_exec($curl), true);
curl_close($curl);

The response tells the user how to fund the Chainrails intent:

{
  "id": 477,
  "direction": "OFF_RAMP",
  "status": "ORDER_INITIATED",
  "provider": "YELLOW_CARD",
  "providerOrderId": "provider-order-id",
  "fiatCurrency": "NGN",
  "cryptoCurrency": "USDC",
  "paymentChannel": "bank_transfer",
  "transferInstructions": {
    "type": "intent_deposit",
    "instructionsText": "Send exactly 25.25 USDC to the intent address below on BASE_MAINNET",
    "transferDetails": [
      {
        "id": "depositAddress",
        "label": "Intent deposit address",
        "value": "0xIntentAddress"
      },
      {
        "id": "amountToSend",
        "label": "Amount to send",
        "value": "25.25"
      }
    ]
  },
  "widgetUrl": null
}

The user must send the exact token and amount to the returned intent address on the specified source chain. Chainrails then routes the funds and coordinates fiat payout.

6. Handle KYC order errors

Order creation revalidates KYC against the selected provider. This protects against stale frontend state. If KYC is incomplete, the order endpoint returns a 400 response with:

{
  "code": "KYC_REQUIRED",
  "message": "Additional KYC information is required",
  "profileId": "profile-id",
  "blocked": false,
  "missingRequirements": [],
  "pendingRequirements": [],
  "rejectedRequirements": [],
  "insufficientRequirements": [],
  "requiredCapabilities": ["external_verification"]
}

Return to the KYC state and submission loop, then retry order creation. If the response code is KYC_BLOCKED, stop automatic retries and ask the user to contact support.

7. Monitor the order

Get one order

cURL
JavaScript
PHP

curl --request GET \
  --url "https://api.chainrails.io/api/v1/ramp/orders/475" \
  --header "Authorization: Bearer YOUR_API_KEY"

const response = await fetch("https://api.chainrails.io/api/v1/ramp/orders/475", { headers: { Authorization: "Bearer YOUR_API_KEY" } });
const order = await response.json();

<?php
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/orders/475");
curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY"]]);
$order = json_decode(curl_exec($curl), true);
curl_close($curl);

Get an on-ramp order by intent address

cURL
JavaScript
PHP

curl --request GET \
  --url "https://api.chainrails.io/api/v1/ramp/orders/by-intent/0xIntentAddress" \
  --header "Authorization: Bearer YOUR_API_KEY"

const response = await fetch("https://api.chainrails.io/api/v1/ramp/orders/by-intent/0xIntentAddress", { headers: { Authorization: "Bearer YOUR_API_KEY" } });
const order = await response.json();

<?php
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/orders/by-intent/0xIntentAddress");
curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY"]]);
$order = json_decode(curl_exec($curl), true);
curl_close($curl);

List orders

cURL
JavaScript
PHP

curl --request GET \
  --url "https://api.chainrails.io/api/v1/ramp/orders?type=on-ramp" \
  --header "Authorization: Bearer YOUR_API_KEY"

const response = await fetch("https://api.chainrails.io/api/v1/ramp/orders?type=on-ramp", { headers: { Authorization: "Bearer YOUR_API_KEY" } });
const orders = await response.json();

<?php
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/orders?type=on-ramp");
curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY"]]);
$orders = json_decode(curl_exec($curl), true);
curl_close($curl);

Order statuses progress forward:

Status	Meaning
`ORDER_INITIATED`	The order exists and is waiting for the user’s payment or deposit.
`DEPOSIT_SUCCESSFUL`	The provider recognized the user’s initial deposit.
`PAYMENT_RECEIVED`	Crypto reached the Chainrails intent or the provider payout was received.
`COMPLETED`	Funds reached the final destination.
`PAYMENT_FAILED`	Provider processing failed.
`PAYMENT_EXPIRED`	The payment window expired.
`CANCELLED`	The order was cancelled before completion.

Poll every few seconds or subscribe to the ramp order webhooks to receive status updates.

Optional order actions

Cancel an order

cURL
JavaScript
PHP

curl --request POST \
  --url "https://api.chainrails.io/api/v1/ramp/orders/475/cancel" \
  --header "Authorization: Bearer YOUR_API_KEY"

const response = await fetch("https://api.chainrails.io/api/v1/ramp/orders/475/cancel", { method: "POST", headers: { Authorization: "Bearer YOUR_API_KEY" } });
const result = await response.json();

<?php
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/orders/475/cancel");
curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY"]]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

Cancellation succeeds only while the provider and Chainrails order state remain cancellable.

Confirm an order

Some provider flows can require explicit confirmation after the user completes a deposit action:

cURL
JavaScript
PHP

curl --request POST \
  --url "https://api.chainrails.io/api/v1/ramp/orders/475/confirm" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "fields": {} }'

const response = await fetch("https://api.chainrails.io/api/v1/ramp/orders/475/confirm", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ fields: {} }),
});
const result = await response.json();

<?php
$curl = curl_init("https://api.chainrails.io/api/v1/ramp/orders/475/confirm");
curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode(["fields" => []])]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

Do not call this endpoint automatically for every order. Most headless orders progress through payment/deposit instructions and webhook-driven status updates without a routine client confirmation call.

Implementation checklist

Use /ramp/countries with type and amount to build corridor selection.
Request quotes with countryCode and userEmail.
Select the provider from the quote response rather than hardcoding one.
Inspect transferType to choose the headless or widget flow.
For headless ramp flows, poll /ramp/kyc and submit only outstanding requirements.
Treat countryCode as transaction geography and fields.country as residence.
Redirect users through verification.url when external verification is required.
Wait for canProceed: true before creating a headless order.
Send only quote-defined payment fields in the order fields object.
For widget flows, redirect to widgetUrl and let the provider own KYC.
Display exact transfer instructions and expiry values from the order response.
Poll the order until a terminal status is reached.

If you do not need a custom interface, the easiest way to get started is the Chainrails Modal, which implements country and currency selection, quote retrieval, progressive KYC, hosted verification redirects, order creation, and status monitoring for you. See the Payment Modal documentation for setup instructions.

Introduction

Concepts

Developer Guides

Essentials

Overview

Before you begin

End-to-end flow

1. Retrieve supported countries

2. Request quotes

On-ramp quote

Off-ramp quote

3. Determine whether KYC is required

Inspect provider requirements

Get the user’s KYC state

4. Complete headless KYC

Text verification flow

External document and biometric verification

Progressive KYC loop

5. Create the ramp order

Headless on-ramp order

Widget on-ramp order

Headless off-ramp order

6. Handle KYC order errors

7. Monitor the order

Get one order

Get an on-ramp order by intent address

List orders

Optional order actions

Cancel an order

Confirm an order

Implementation checklist

​Overview

​Before you begin

​End-to-end flow

​1. Retrieve supported countries

​2. Request quotes

​On-ramp quote

​Off-ramp quote

​3. Determine whether KYC is required

​Inspect provider requirements

​Get the user’s KYC state

​4. Complete headless KYC

​Text verification flow

​External document and biometric verification

​Progressive KYC loop

​5. Create the ramp order

​Headless on-ramp order

​Widget on-ramp order

​Headless off-ramp order

​6. Handle KYC order errors

​7. Monitor the order

​Get one order

​Get an on-ramp order by intent address

​List orders

​Optional order actions

​Cancel an order

​Confirm an order

​Implementation checklist

​Using the Chainrails Modal

Overview

Before you begin

End-to-end flow

1. Retrieve supported countries

2. Request quotes

On-ramp quote

Off-ramp quote

3. Determine whether KYC is required

Inspect provider requirements

Get the user’s KYC state

4. Complete headless KYC

Text verification flow

External document and biometric verification

Progressive KYC loop

5. Create the ramp order

Headless on-ramp order

Widget on-ramp order

Headless off-ramp order

6. Handle KYC order errors

7. Monitor the order

Get one order

Get an on-ramp order by intent address

List orders

Optional order actions

Cancel an order

Confirm an order

Implementation checklist

Using the Chainrails Modal