End-to-End Strails Integration Walkthrough

This guide walks you through a complete Strails integration, from your first API call to executing an FX trade. Follow the steps in order - each one builds on the previous.

Before you start, make sure you have:

A Strails API key (contact support@strails.co to obtain one)
An HTTPS webhook endpoint you control (use webhook.site or ngrok during development)
A test BVN (11-digit Nigerian BVN) for user onboarding tests

Test Your API Connection

Verify your API key and confirm you can reach the staging environment by retrieving your fintech wallet.

curl -X GET https://api.strails.io/v1/getfintechwallet \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Expected response:

{
  "status": "Success",
  "response_code": "00",
  "message": "Fintech wallet retrieved successfully",
  "data": {
    "fintechId": "fintech_abc123",
    "fintechName": "Example Fintech Ltd",
    "smartWallet": {
      "address": "0x69E4eA33BF7E2f6bAE7F1DEF247534C0aD3515C3",
      "owner": "0x684f5f118ed7d0e00b1c0a27dcdce6e37cf652e1",
      "deployed": true,
      "saltVersion": "v2"
    },
    "externalWallets": [],
    "totalUsers": 0
  }
}

If you see your Smart Wallet address, your API key is valid and you are connected to the test environment. Save data.smartWallet.address - you will reference it throughout the integration. See Wallet Management for the full response schema.

This endpoint returns your Smart Wallet and registered external wallets only. Your MPC Vault token wallets are returned by GET /fx/settings once MPC registration is approved, and Managed Wallets are provisioned per user - retrieve them with POST /listuserwallets.

The header name must be x-api-key in lowercase. Headers named X-API-Key or api-key will return 401 Unauthorized.

Configure Your Webhook

Register your webhook URL so Strails can notify you when asynchronous operations complete. This is strongly recommended before you proceed - without it you will need to poll every status endpoint manually.

curl -X POST https://api.strails.io/v1/setwebhook \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://yourapp.com/webhooks/strails",
    "events": ["all"]
  }'

Set up your handler to verify the HMAC signature on every incoming request:

const express = require('express');
const crypto  = require('crypto');

const app = express();

// express.raw - NOT express.json. The signature is computed over the raw
// bytes, so parsing and re-serialising the body will break verification.
app.post('/webhooks/strails', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-strails-signature'];
  const timestamp = req.headers['x-strails-timestamp'];
  const rawBody   = req.body.toString('utf-8');

  if (!signature || !timestamp) {
    return res.status(400).send('Missing signature headers');
  }

  // X-Strails-Timestamp is ISO 8601, so parse it as a date - not as a number
  const ageSeconds = (Date.now() - new Date(timestamp).getTime()) / 1000;
  if (ageSeconds > 300) {
    return res.status(400).send('Timestamp too old');
  }

  const expected = crypto
    .createHmac('sha256', process.env.STRAILS_WEBHOOK_SECRET)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  let isValid = false;
  try {
    isValid = crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expected,  'hex')
    );
  } catch {
    isValid = false; // length mismatch
  }
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Acknowledge immediately - process asynchronously
  res.sendStatus(200);

  const { eventType, payload } = JSON.parse(rawBody);
  console.log(`Received event: ${eventType}`, payload);
  // Update your database, notify users, trigger downstream logic
});

Deduplicate on the X-Webhook-ID header - a retried delivery repeats the same event. Full verification details and a Python version are on the HMAC Signatures page.

Return 200 OK before doing any processing. If your handler takes too long to respond, Strails will retry the delivery, causing duplicate events.

Onboard Your First User

Register a user with BVN verification. Strails verifies the BVN against Nigerian records and creates a wallet for the user.Initiate onboarding:

curl -X POST https://api.strails.io/v1/onboarduser \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bvn": "12345678901"
  }'

bvn is the only field this endpoint accepts. The user’s identity is resolved from the BVN record and Strails issues the user identifier itself - you do not supply one.

Response:

{
  "status": "Success",
  "response_code": "00",
  "message": "User registration initiated",
  "data": {
    "requestId": "7898f29e-10a6-4b2b-9496-f4ee50549fd4",
    "status": "processing",
    "userHash": "user_uniqueID",
    "estimatedCompletionTime": "2-5 minutes"
  }
}

Check onboarding status by posting the requestId you just received:

curl -X POST https://api.strails.io/v1/onboardstatus \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "user_uniqueID"
  }'

Successful verification response:

{
  "status": "Success",
  "response_code": "00",
  "message": "User registration completed successfully",
  "data": {
    "type": "user_registration",
    "userId": "user_uniqueID",
    "status": "completed",
    "createdAt": "2026-01-18T19:33:39.945Z"
  }
}

Poll until status is "completed" or "failed", or listen for the user.onboarded webhook event instead of polling. Once complete, use the returned userId for every subsequent call for this user.

Optional: route the user’s cNGN to an external addressOnboarding provisions a Strails-managed wallet that receives the user’s cNGN. If the user self-custodies, or you settle into your own treasury addresses, register an external destination with POST /setuserdefaultwallet:

curl -X POST https://api.strails.io/v1/setuserdefaultwallet \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_uniqueID",
    "address": "0xc5422E03B8250917023501E4697c738E7427b540",
    "blockchain": "base",
    "label": "User payout wallet"
  }'

This redirects virtual account mints, onramps, and sweepToOfframp transfers. Swaps, offramp, and escrow still run against the Strails-managed wallet, so keep balance there for those flows. Call DELETE /removeuserdefaultwallet to revert.

Fund a User Wallet

Initiate an onramp to generate a virtual bank account and fund the user’s wallet with cNGN (optionally auto-swapped to USDC or USDT).The /cngnonramp endpoint accepts three parameters that control what happens after NGN is deposited. Use the table below to choose the combination that matches your product:

`autoSwap`	`assetSwap`	`sweepToOfframp`	Outcome
`false`	-	`false`	NGN deposited -> cNGN disbursed to user wallet. No swap.
`true`	`"USDC"` or `"USDT"`	`false`	NGN deposited -> cNGN disbursed -> auto-swapped to `assetSwap` token via fx orders in Strails orderbook.
`true`	`"USDC"` or `"USDT"`	`true`	NGN deposited -> cNGN disbursed -> auto-swapped -> swept to the user’s default Smart Wallet. When set, `destinationAssetSwap` is ignored.

Initiate the onramp:

curl -X POST https://api.strails.io/v1/cngnonramp \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_uniqueID",
    "amount": 5000,
    "assetSwap": "USDC",
    "autoSwap": true,
    "sweepToOfframp": false
  }'

Response (with fee breakdown):

{
  "status": "Success",
  "response_code": "00",
  "message": "cNGN request submitted successfully",
  "data": {
    "requestId": "f16c0e3c-0c0f-473f-91f7-ab2b85bc9117",
    "walletAddress": "0xF94384E5792F44fDF231A56cea4f4C14d998e58c",
    "status": "requested",
    "message": "Ensure you pay 5075.00 naira to the bank account generated. Use requestId to get the bank account details for payment.",
    "autoSwapEnabled": true,
    "targetAsset": "USDC",
    "feeBreakdown": {
      "baseAmount": 5000,
      "totalFee": 75,
      "totalAmount": 5075
    }
  }
}

Retrieve the virtual account details to show your user:

curl -X POST https://api.strails.io/v1/getvirtualaccount \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "f16c0e3c-0c0f-473f-91f7-ab2b85bc9117"
  }'

Response:

{
  "status": "Success",
  "response_code": "00",
  "data": {
    "accountNumber": "9800001234",
    "bankName": "FAME Bank",
    "accountName": "Test User Strails",
    "amount": 5000,
    "totalAmountWithFee": 5075,
    "expiresAt": "2026-04-10T11:30:00Z"
  }
}

Virtual accounts expire 30 minutes after creation. Display the expiresAt time prominently to your user so they complete the transfer before the window closes.

Check the onramp status after payment:

curl -X POST https://api.strails.io/v1/cngnonrampstatus \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "f16c0e3c-0c0f-473f-91f7-ab2b85bc9117"
  }'

Completed response:

{
  "status": "Success",
  "response_code": "00",
  "data": {
    "requestId": "f16c0e3c-0c0f-473f-91f7-ab2b85bc9117",
    "status": "completed",
    "walletAddress": "0xF94384E5792F44fDF231A56cea4f4C14d998e58c",
    "amount": "5000000000",
    "swapCompleted": true,
    "finalAsset": "USDC",
    "txHash": "0xabcd1234...",
    "completedAt": "2026-04-10T10:35:00Z"
  }
}

Note that amount in the completed response is in the smallest unit (wei format): 5000000000 = 5,000 cNGN at 6 decimals. See Amount Formats for conversion details.

Process a Withdrawal (Offramp)

Convert a user’s cNGN back to Naira and send it to their Nigerian bank account.Get the list of supported banks:

curl -X POST https://api.strails.io/v1/getbankscode \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "status": "Success",
  "response_code": "00",
  "message": "Banks retrieved successfully",
  "data": {
    "countryCode": "NG",
    "banks": [
      { "bank_name": "GTBank", "bank_code": "058" },
      { "bank_name": "Access Bank", "bank_code": "044" },
      { "bank_name": "UBA", "bank_code": "033" }
    ]
  }
}

/getbankscode is a POST endpoint that takes no request body. Cache the result - the bank list changes rarely and the call counts against your rate limit.

Initiate the offramp:

curl -X POST https://api.strails.io/v1/cngnofframp \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_uniqueID",
    "amount": 3000,
    "accountNumber": "0123456789",
    "bankCode": "058",
    "ticker": "CNGN"
  }'

Response:

{
  "status": "Success",
  "response_code": "00",
  "message": "Vault return token transfer completed, payout processing initiated",
  "data": {
    "requestId": "req_offramp_xyz",
    "status": "payout_pending",
    "stage": "payout"
  }
}

Check the offramp status:

curl -X POST https://api.strails.io/v1/cngnofframpstatus \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "req_offramp_xyz"
  }'

Listen for the vault.return.payout.completed webhook event to confirm the bank transfer has settled - a user offramp emits vault.return.transfer.confirmed first (cNGN moved on-chain), then vault.return.payout.completed. Store the requestId from every offramp so you can query its status if the user disputes a withdrawal.

Execute an FX Trade

Post an order to the cNGN/USDC/USDT orderbook, get a quote, and execute the trade.Create an orderbook entry:

curl -X POST https://api.strails.io/v1/fx/limit-order \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pair": "CNGN-USDC",
    "side": "sell",
    "price": "1350.00",
    "spread": 0.5,
    "minAmount": "1000",
    "maxAmount": "100000"
  }'

Response:

{
  "status": "Success",
  "response_code": "00",
  "message": "Limit order created successfully",
  "data": {
    "orderId": "order_abc123",
    "pair": "CNGN-USDC",
    "side": "sell",
    "price": "1350.00",
    "spread": 0.5,
    "minAmount": "1000.00",
    "maxAmount": "100000.00",
    "availableLiquidity": "95000.00",
    "status": "active"
  }
}

Get an FX quote (POST, with the cNGN amount as a human-readable decimal):

curl -X POST https://api.strails.io/v1/fx/quote \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pair": "CNGN-USDC",
    "side": "sell",
    "cngnAmount": "50000"
  }'

The quote response includes a quoteId and is valid for 5 minutes. Pass the quoteId directly to the trade endpoint.Execute the trade:

curl -X POST https://api.strails.io/v1/fx/trade \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "quote_7f3a9d2c-8e41-4b29-9a1c-5d8e7f2b3a9c",
    "idempotencyKey": "trade_20260501_001"
  }'

After execution, tokens from both sides are held in escrow and settlement completes automatically.

FX trades do not emit webhook events. Poll GET /fx/trades/status?tradeId=... until the trade reaches completed, expired, or failed. The lock window is 5 minutes.

FX amounts are human-readable decimals, not wei - "price": "1350.00" means 1,350 cNGN per USDC and "minAmount": "1000" means 1,000 cNGN. See Orderbook Management and Trading Management for every field.

Common Integration Patterns

Simple Wallet Funding Onboard a user -> generate a virtual account -> user pays NGN -> cNGN is disbursed to their wallet. Use this pattern when your users just need a cNGN balance. Wallet Funding with Auto-Swap Set "autoSwap": true and "assetSwap": "USDC" on the onramp request. After the NGN deposit is received, Strails mints cNGN and immediately swaps it to USDC via fx order in StRails orderbook - no extra API calls required. Use this pattern for products where users want USD-denominated stablecoins. Fintech Liquidity Management Post a limit order on the FX orderbook -> wait for a match -> confirm the trade quote -> execute. Escrow settles the counterparty automatically. Use this pattern to rebalance your fintech’s cNGN and USDC/USDT pools.

Testing Tips

Use Postman: Import the Strails Postman collection, set BASE_URL to https://api.strails.io/v1 and API_KEY to your key, then run the collection to exercise all endpoints.
Start small: Test onramp and offramp flows with amounts between ₦100 and ₦500 before increasing transaction sizes.
Inspect webhooks locally: Use webhook.site for a hosted listener, or ngrok to tunnel to your local machine during development.

Troubleshooting

Problem	Solution
`401 Unauthorized` on every request	Check that your header is named `x-api-key` (lowercase) and that the key value is correct.
IP not in allowlist error	Add your server’s public IP via `/manageipallowlist` or contact support to add it for you.
`429 Too Many Requests`	Implement exponential backoff. Contact support@strails.io if you need a higher rate limit.
BVN verification returns `failed`	Confirm the BVN is exactly 11 numeric digits with no spaces or hyphens, and that it is not already registered to another Strails user. A `failed` record cannot be retried - submit a fresh `/onboarduser` request.
Transaction stuck in `pending` for more than 10 minutes	Query `/cngnonrampstatus` with the `requestId`, then call `POST /manualstatusrecovery` with `{"requestId": "..."}` to trigger a reconciliation check. Contact support if the issue persists.
Webhooks not arriving	Confirm your URL is HTTPS, returns `200 OK`, and is publicly reachable. Check your HMAC verification logic for off-by-one errors in the signature string.

Get Started

Wallets

Guides

Tools

End-to-End Strails Integration Walkthrough

Common Integration Patterns

Testing Tips

Troubleshooting

​Common Integration Patterns

​Testing Tips

​Troubleshooting

Common Integration Patterns

Testing Tips

Troubleshooting