Skip to main content
Understanding these concepts will help you integrate the Strails API correctly and avoid common pitfalls.

​
Asynchronous Processing

All blockchain operations return a requestId immediately and process in the background:
This keeps API responses fast (~200ms) while complex operations (wallet creation, token minting, swaps) complete reliably. Track the final status via webhooks or by polling the relevant status endpoint.

​
Virtual Accounts

Every user gets a dedicated Nigerian bank account that automatically converts deposits to cNGN:
  • Bank accounts generated via licensed payment integration
  • Auto-swap option: NGN -> cNGN -> USDC/USDT in a single flow
  • Depositor details captured for compliance
See the Virtual Accounts Guide for account types and deposit flows.

​
Wallet System

Fintechs operate with three wallet types: Tokens live in smart wallets and managed wallets. A user’s disbursed cNGN lands in their Strails-managed wallet by default. Fintechs can instead nominate an external default wallet per user - a delivery destination for virtual account mints, onramps, and sweepToOfframp. Strails holds no keys for it, so swaps, offramp, and escrow continue to operate only on Strails-managed wallets.

​
FX Orderbook

Fintechs can trade between cNGN and USDC/USDT with other fintechs:
  • Limit orders: Set your price and wait for counterparties
  • Market orders: Execute instantly at best available price
  • Escrow-based settlement with a 5-minute price lock
  • Self-trading prevention built-in
  • Auto-approval of trades that meet your set threshold via dedicated virtual machines
Learn more in Orderbook Management and Trading Management.

​
Webhooks

All critical operations send real-time notifications to your configured webhook URL:
  • Wallet creation, deposits, trades, withdrawals
  • HMAC signature verification (optional but recommended)
  • Retry logic with exponential backoff
See Webhook Events for payload details.

​
Amount Formats

The API uses four amount formats. Which one applies is a property of the individual endpoint, so check Payload Formats before sending an amount.

​
Naira (onramp / offramp / virtual accounts)

Plain Naira, the main currency unit:
5000 means ₦5,000, not 5,000 kobo.
  • Create virtual account: "amount": 5000 -> user pays ₦5,000
  • Onramp: "amount": 200 -> costs ₦203 with fees
  • Offramp: "amount": 3000 -> user receives ₦3,000 in their bank

​
Kobo (Fee Management endpoints only)

Every endpoint under Fee Management - /feewithdrawal, /getaccumulatedfees, /getwithdrawalhistory, /fees/strails/preview, and capFee on /managefees - is denominated in kobo:
50000 means ₦500.00.

​
Human-readable token units

/withdrawasset, /swap, /swaptrigger, and all FX price and amount fields take the token amount as a person would write it:

​
Smallest unit (wei format)

/fintechtransfer, /initiateofframp, on-chain balances, and the amount field returned by blockchain status endpoints use the smallest unit: Use the string-based helpers in Payload Formats to convert - amount * 1e6 in plain JavaScript loses precision on large balances and overflows entirely at 18 decimals.
Key takeaway: there is no single rule that covers “fiat” or “blockchain” endpoints. /cngnofframp takes Naira while /initiateofframp takes smallest units; /withdrawasset takes human-readable token units while /fintechtransfer takes smallest units. Look up the endpoint.

​
Response Format

All API responses follow a consistent structure. Success (HTTP 200):
Error (HTTP 4xx/5xx):
The casing of status is not stable across endpoints - you will see Success/success, Error/error, and Failed. Branch on response_code and the HTTP status instead, and use status for display only.

​
Response Codes

For detailed request/response payloads per endpoint, see Request & Response Formats.