Quick Start Guide - FiatRails API

🌍 Overview

FiatRails enables seamless fiat-to-crypto and crypto-to-fiat conversions across Africa using mobile money. Our API supports real-time payments in multiple countries with smart contract settlement on FUJI testnet.

🇰🇪 Kenya (KES)

🇬🇭 Ghana (GHS)

🇹🇿 Tanzania (TZS)

🇳🇬 Nigeria (NGN)

⚡ Quick Setup

1 Get Your API Keys

Sign up at partners.fiatrails.com to get your sandbox API key instantly.

2 Install SDK (Optional)

Use our SDKs for faster integration or make direct HTTP requests.

3 Make Your First Request

Test an on-ramp transaction in sandbox mode.

🔥 Your First On-ramp

Convert mobile money to crypto tokens with a simple API call:

POST Request

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

✅ Response: You'll receive a transaction ID and STK push will be sent to the customer's phone.

💸 Your First Off-ramp

Convert crypto tokens back to mobile money:

POST Request

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

✅ Response: Tokens are burned and mobile money is sent to the specified phone number.

📊 Check Transaction Status

Monitor your transactions in real-time:

GET Request

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

🛡️ Authentication

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

Authorization: Bearer sandbox_YOUR_API_KEY_HERE

⚠️ Security: Never expose your API keys in client-side code. Always make API calls from your backend.

🧪 Sandbox Testing

Use these test credentials in sandbox mode:

🇰🇪 Kenya Test Numbers

+254700000000
+254711111111

Use any amount between 1-100,000 KES

🇬🇭 Ghana Test Numbers

+233200000000
+233244444444

Use any amount between 1-10,000 GHS

🇹🇿 Tanzania Test Numbers

+255700000000
+255788888888

Use any amount between 1-200,000 TZS

🇳🇬 Nigeria Test Numbers

+234800000000
+234900000000

Use any amount between 1-500,000 NGN

⚙️ Environment URLs

🧪 Sandbox

https://api.fiatrails.com

For testing and development

FUJI Testnet

🚀 Production

Coming with MainNet

Real transactions with live money

MainNet Soon

📚 Code Examples

JavaScript/Node.js

JavaScript

const fiatRails = require('@fiatrails/sdk');

const client = new fiatRails({
  apiKey: 'sandbox_your_api_key',
  environment: 'sandbox'
});

// On-ramp example
const onramp = await client.onramp.create({
  phoneNumber: '+254712345678',
  amountKES: 1000,
  merchantWallet: '0x742d35Cc6635C0532925a3b8D0C0F0E4C33a8cC7'
});

console.log('Transaction ID:', onramp.transactionId);

Python

import fiatrails

client = fiatrails.Client(
    api_key='sandbox_your_api_key',
    environment='sandbox'
)

# On-ramp example
onramp = client.onramp.create(
    phone_number='+254712345678',
    amount_kes=1000,
    merchant_wallet='0x742d35Cc6635C0532925a3b8D0C0F0E4C33a8cC7'
)

print(f'Transaction ID: {onramp.transaction_id}')

🚀 FiatRails Quick Start