Core Concepts

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:

{ "requestId": "req_abc123", "status": "processing" }

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:

Wallet	Holds	Control
Multi-Chain Wallet	cNGN, USDC, USDT	Strails-controlled HSM managed wallet
Smart Wallet	cNGN, USDC, USDT	Fintech or Strails-controlled smart contract wallet
MPC Wallet	USDC, USDT	Fintech-controlled with MPC signing

Tokens live in smart wallets and managed wallets.

FX Orderbook

Fintechs can trade cNGN ↔ 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 different amount formats depending on the operation type.

Fiat Operations (Onramp / Offramp / Virtual Accounts)

Amounts are in Naira (main currency unit):

{
  "amount": 5000    // = ₦5,000 (NOT 5000 kobo)
}

Examples:

Create virtual account: "amount": 5000 → User pays ₦5,000
Onramp: "amount": 200 → Costs ₦203 (with fees)
Offramp: "amount": 3000 → User receives ₦3,000 in bank

Token Operations (Blockchain Transfers / Balances)

Amounts use the smallest unit (wei format) with token decimals:

Token	Decimals	Example
cNGN	6	`500000000` = 500 cNGN
USDC	6	`1000000` = 1 USDC
USDT	6	`1000000` = 1 USDT
DAI	18	`1000000000000000000` = 1 DAI

JavaScript conversion (token operations only):

// Blockchain response → Display
const displayAmount = Number("500000000") / 1e6; // = 500 cNGN

// User input → Blockchain request
const rawAmount = String(Math.floor(123.45 * 1e6)); // = "123450000"

Key takeaway: Fiat endpoints use regular Naira amounts. Only blockchain/token operations use wei format with decimals.

Response Format

All API responses follow a consistent structure. Success (HTTP 200):

{
  "status": "success",
  "response_code": "00",
  "message": "Operation completed successfully",
  "data": { "requestId": "req_abc123" }
}

Error (HTTP 4xx/5xx):

{
  "status": "error",
  "response_code": "01",
  "message": "Validation error: Invalid amount",
  "error": { "field": "amount", "reason": "Must be greater than 0" }
}

Response Codes

Code	Meaning
`00`	Success
`01`	Validation Error
`02`	Not Found
`03`	Unauthorized
`04`	Rate Limited
`05`	Internal Error

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

​Core Concepts

​Asynchronous Processing

​Virtual Accounts

​Wallet System

​FX Orderbook

​Webhooks

​Amount Formats

​Fiat Operations (Onramp / Offramp / Virtual Accounts)

​Token Operations (Blockchain Transfers / Balances)

​Response Format

​Response Codes

Core Concepts

Asynchronous Processing

Virtual Accounts

Wallet System

FX Orderbook

Webhooks

Amount Formats

Fiat Operations (Onramp / Offramp / Virtual Accounts)

Token Operations (Blockchain Transfers / Balances)

Response Format

Response Codes