🔗 FiatRails API Reference

Complete API documentation for cross-border payments

🌍 Overview

The FiatRails API enables seamless fiat-to-crypto and crypto-to-fiat conversions across Africa. Our REST API uses standard HTTP methods, JSON payloads, and returns predictable responses.

Base URL

https://api.fiatrails.com

Key Features

🔐 Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization Header
Authorization: Bearer YOUR_API_KEY
🔑 API Key Format:
  • sandbox_... - For testing and development
  • live_... - For production use (MainNet)

🌐 Environments

Environment Base URL Network Purpose
Sandbox https://api.fiatrails.com FUJI Testnet Development & Testing
Production Coming with MainNet Avalanche MainNet Live Transactions

🌍 Supported Countries

🇰🇪

Kenya

KES • M-Pesa

1 - 100,000 KES

🇬🇭

Ghana

GHS • MTN MoMo

1 - 10,000 GHS

🇹🇿

Tanzania

TZS • M-Pesa

1 - 200,000 TZS

🇳🇬

Nigeria

NGN • Airtel Money

1 - 500,000 NGN

🔥 On-ramp

Convert mobile money to crypto tokens. Initiates an STK push to the customer's phone.

POST /api/v1/onramp

Parameters

Parameter Type Required Description
phoneNumber string Required Customer's phone number in international format
amountKES number Required Amount in local currency (1 - 100,000)
merchantWallet string Required Destination wallet address for tokens
currency string Optional Currency code (KES, GHS, TZS, NGN)

Example Request

cURL
curl -X POST https://api.fiatrails.com/api/v1/onramp \
  -H "Authorization: Bearer sandbox_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+254712345678",
    "amountKES": 1000,
    "merchantWallet": "0x742d35Cc6635C0532925a3b8D0C0F0E4C33a8cC7",
    "currency": "KES"
  }'

Success Response

200 OK
JSON Response
{
  "success": true,
  "transactionId": "txn_1234567890abcdef",
  "status": "initiated",
  "message": "STK push sent successfully",
  "data": {
    "mpesaCheckoutRequestID": "ws_CO_123456789",
    "merchantRequestID": "MR_123456789",
    "amount": 1000,
    "currency": "KES",
    "phoneNumber": "+254712345678",
    "estimatedTime": "2-5 minutes"
  }
}

💸 Off-ramp

Convert crypto tokens back to mobile money. Burns tokens and initiates mobile money disbursement.

POST /api/offramp/initiate

Parameters

Parameter Type Required Description
userWallet string Required Source wallet address containing tokens
amount string Required Amount in local currency
currency string Required Currency code (KES, GHS, TZS, NGN)
phoneNumber string Required Recipient's phone number
disbursementMethod string Required Payment method (MPESA, MTN_MOMO, AIRTEL)

Example Request

cURL
curl -X POST https://api.fiatrails.com/api/offramp/initiate \
  -H "Authorization: Bearer sandbox_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userWallet": "0x742d35Cc6635C0532925a3b8D0C0F0E4C33a8cC7",
    "amount": "1000",
    "currency": "KES",
    "phoneNumber": "+254712345678",
    "disbursementMethod": "MPESA"
  }'

Success Response

200 OK
JSON Response
{
  "success": true,
  "transactionId": "offramp_1234567890abcdef",
  "disbursementId": "disbursement_9876543210",
  "burnTxHash": "0xabc123...",
  "estimatedTime": "5-10 minutes",
  "steps": [
    "validation_complete",
    "disbursement_queued",
    "token_burn_scheduled"
  ]
}

📊 Transaction Status

Check the status of any transaction using its transaction ID.

GET /api/status

Query Parameters

Parameter Type Required Description
transactionId string Required Transaction ID from on-ramp or off-ramp response

Example Request

cURL
curl -X GET "https://api.fiatrails.com/api/status?transactionId=txn_1234567890abcdef" \
  -H "Authorization: Bearer sandbox_your_api_key"

Success Response

200 OK
JSON Response
{
  "success": true,
  "transactionId": "txn_1234567890abcdef",
  "status": "completed",
  "type": "onramp",
  "amount": "1000",
  "currency": "KES",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:32:15Z",
  "blockchainTxHash": "0xdef456...",
  "confirmations": 12
}

Transaction Statuses

Status Description
initiated Transaction created, STK push sent
pending Customer has entered PIN, processing payment
completed Payment successful, tokens minted/burned
failed Payment failed or cancelled
expired Customer didn't complete payment in time

💚 Health Check

Check API availability and system status.

GET /health

Example Request

cURL
curl -X GET https://api.fiatrails.com/health

Success Response

200 OK
JSON Response
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0",
  "network": "fuji-testnet",
  "services": {
    "database": "healthy",
    "blockchain": "healthy",
    "mpesa": "healthy",
    "mtn_momo": "healthy"
  }
}

⚠️ Error Codes

FiatRails uses conventional HTTP response codes to indicate the success or failure of API requests.

HTTP Code Error Code Description
400 INVALID_REQUEST Missing or invalid parameters
401 UNAUTHORIZED Invalid or missing API key
400 INSUFFICIENT_BALANCE Insufficient funds in wallet
400 INVALID_PHONE_NUMBER Phone number format is invalid
400 AMOUNT_OUT_OF_RANGE Amount exceeds min/max limits
500 INTERNAL_ERROR Server error, please try again

Error Response Format

400 Bad Request
JSON Response
{
  "success": false,
  "error": "INVALID_PHONE_NUMBER",
  "message": "Phone number must be in international format",
  "code": "INVALID_PHONE_NUMBER",
  "details": {
    "field": "phoneNumber",
    "provided": "0712345678",
    "expected": "+254712345678"
  }
}

🚀 Ready to Get Started?

Get your API keys and start integrating FiatRails today

Get API Keys Quick Start Guide