Skip to main content
POST
/
v1
/
transfer-requests
Create a transfer request (on-ramp or off-ramp)
curl --request POST \
  --url https://api.railsfromthecrypt.com/v1/transfer-requests \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "type": "onramp",
  "amount": 10000,
  "from_currency": "NGN",
  "to_currency": "USDC",
  "recipient_id": "rec_01J8V9ZP3A7"
}
'
{
  "success": true,
  "message": "Transfer created successfully",
  "data": {
    "id": "c17d2777-e604-45e2-b6d5-7743652eadf1",
    "type": "onramp",
    "status": "fetching_rates",
    "source": {
      "amount": 10000,
      "currency": "NGN"
    },
    "destination": {
      "amount": 0,
      "currency": "USDC"
    },
    "events": [
      {
        "status": "pending",
        "timestamp": "2023-11-07T05:31:56Z",
        "completed_at": "2023-11-07T05:31:56Z"
      }
    ],
    "payments": [],
    "created_at": "2025-10-10T09:15:21Z",
    "reference": "TXN-2Z82FVYO6BW22RC7",
    "rate": {
      "value": 0,
      "expires_at": null
    },
    "recipient": {
      "id": "rec_01J8V9ZP3A7",
      "type": "crypto",
      "name": "My USDT Wallet",
      "details": {
        "network": "Polygon",
        "wallet_address": "0xABC123DEF456...",
        "symbol": "USDT"
      }
    },
    "payment_instructions": {
      "type": "bank_transfer",
      "bank_transfer": {
        "account_number": "1234567890",
        "account_name": "HashRails Ltd",
        "bank_name": "Wema Bank",
        "bank_code": "035"
      }
    }
  }
}
Create a new transfer request to move funds between Fiat and Crypto. This endpoint supports both:
  • On-ramp (Fiat → Crypto): You pay in fiat (e.g., NGN), and your recipient receives cryptocurrency.
  • Off-ramp (Crypto → Fiat): You send crypto (e.g., USDT) over a specified network, and your recipient receives fiat in their bank account.

Headers

​
x-api-key
string
required

API key for authentication

​
x-idempotency-key
string
required

UUID v4 idempotency key to prevent duplicate transfers.

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

Convert fiat currency to crypto. You pay in fiat and your recipient receives crypto.

​
type
enum<string>
required

Transfer direction.

Available options:
onramp
Example:

"onramp"

​
amount
number
required

Amount to send in the source currency.

Example:

10000

​
from_currency
enum<string>
required

Source fiat currency.

Available options:
NGN,
KES,
UGX,
GHS,
ZAR
Example:

"NGN"

​
to_currency
enum<string>
required

Destination crypto currency.

Available options:
USDC,
USDT
Example:

"USDC"

​
recipient_id
string
required

Crypto recipient ID where settlement will be sent.

Example:

"rec_01J8V9ZP3A7"

Response

Transfer created successfully

​
success
boolean
Example:

true

​
message
string
Example:

"Transfer created successfully"

​
data
object