Transactions API: Onramp, Offramp, Swaps & Transfers

The Transactions API handles every financial operation in Strails. You can fund user wallets by converting Naira to cNGN (onramp), return cNGN back to a Nigerian bank account (offramp), swap between cNGN, USDC, and USDT (swap), and withdraw assets to external wallets (transfer). Most operations are asynchronous - each call returns a requestId you can use to poll for the final status or receive a webhook notification.

Endpoints Overview

Section	Endpoint	Method	Description
User Onramp	`/cngnonramp`	POST	Fund a user wallet by converting Naira to cNGN or a supported token
User Offramp	`/cngnofframp`	POST	Convert a user’s cNGN back to Naira and pay out to their bank account
Fintech Onramp	`/getfintechvirtualaccount`	GET	Retrieve the persistent virtual bank account attached to your fintech
Fintech Offramp	`/initiateofframp`	POST	Convert cNGN from your fintech Smart Wallet to Naira
User Token Withdrawal	`/withdrawasset`	POST	Withdraw tokens from a user wallet to an external wallet
Fintech Token Withdrawal	`/fintechtransfer`	POST	Withdraw tokens from your fintech Smart Wallet to a registered external wallet
cNGN Onramp Status	`/cngnonrampstatus`	POST	Check the current status of a user onramp request
cNGN Offramp Status	`/cngnofframpstatus`	POST	Check the current status of a user offramp request
Fintech Offramp Status	`/getofframpstatus`	GET	Check the current status of a fintech offramp request
List Deposits	`/deposits`	GET	List deposit transactions with filtering and pagination
List Payouts	`/payouts`	GET	List payout transactions with filtering and pagination
List Transactions	`/transactions`	GET	List all transactions (deposits and payouts) with filtering and pagination
Withdraw History	`/withdrawals`	GET	List token withdrawal transfers with filtering and pagination
Swap Trigger	`/swaptrigger`	POST	Trigger an asynchronous swap for a specific wallet address
User Swap	`/swap`	POST	Request a token swap on a user’s default Smart Wallet
Swap Status	`/swapstatus`	GET	Get the status of an asynchronous swap request
Swap History	`/swaphistory`	GET	List historical swap requests for your fintech

User Onramp

POST /cngnonramp Creates a temporary Smart Wallet and a bank transfer instruction so your end-user can fund their wallet by paying Naira into a virtual account. After the bank transfer is confirmed, cNGN is disbursed to the generated wallet.

Use the /getvirtualaccount endpoint to retrieve the virtual bank account details for payment. The generated account is only active for 30 minutes after creation.

Payment into the generated virtual account must originate from the verified bank account of the Strails end-user. Payments from unverified accounts will not be processed.

The amount field is denominated in Naira. For example, 500 means ₦500 - not 500 kobo or 500 token units.

curl --request POST \
  --url "https://api.strails.io/v1/cngnonramp" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "userId": "user_uniqueID",
    "amount": 500,
    "assetSwap": "USDC",
    "autoSwap": true,
    "sweepToOfframp": false,
    "destinationAssetSwap": "0xDestinationAddress"
  }'

string

required

Unique identifier (hash or UUID) of the end-user initiating the onramp.

number

required

Amount to fund in Naira (e.g. 500 = ₦500). Must be greater than 0.

string

The token to swap cNGN into after funding (e.g. USDC, USDT). Only used when autoSwap is true.

boolean

When true, automatically swaps the funded cNGN into assetSwap after the bank payment is confirmed.

boolean

When true, automatically routes the funded (and optionally swapped) amount to the user’s default wallet after confirmation - their Strails-managed Smart Wallet, or their external default wallet if one is registered. When set, destinationAssetSwap is ignored.

string

Destination wallet address for the swapped assets. Only used when autoSwap is true and sweepToOfframp is false.

string

Your EOA wallet address to take ownership of the generated Smart Wallet. When set, you can withdraw tokens directly using your EOA. Note that Strails cannot withdraw funds from wallets with a custom owner.

autoSwap behaviour matrix

`autoSwap`	`sweepToOfframp`	`destinationAssetSwap`	Result
`false`	`false`	-	cNGN stays in the generated wallet
`false`	`true`	ignored	cNGN is swept to the user’s default Smart Wallet
`true`	`false`	not set	cNGN -> `assetSwap`, stays in the generated wallet
`true`	`false`	set	cNGN -> `assetSwap` -> `destinationAssetSwap`
`true`	`true`	ignored	cNGN -> `assetSwap` -> user’s default Smart Wallet

“User’s default Smart Wallet” resolves to the user’s external default wallet when one is registered. Because Strails cannot sign for external addresses, plan subsequent swap or offramp operations against a Strails-managed wallet.

object

Show data fields

string

Unique identifier for this onramp request. Use it with /cngnonrampstatus and /getvirtualaccount to track the bank account and status.

string

The generated Smart Wallet address that will receive the disbursed cNGN.

string

Initial status of the request (e.g. requested).

boolean

Whether auto-swap is active for this request.

boolean

Whether sweep-to-offramp is active for this request.

string

The swap target asset (e.g. USDC).

object

Show feeBreakdown fields

number

The base Naira amount before fees.

number

Fee charged by your fintech.

number

Fee charged by Strails.

number

Sum of all fees.

number

Total Naira amount to be paid (base + total fees).

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "cNGN request submitted successfully",
  "data": {
    "requestId": "uuid",
    "walletAddress": "0x..",
    "status": "requested",
    "version": "1.0.0",
    "message": "Ensure you pay 528.84 naira (520 + 8.84 total fees: 0.00 fintech + 8.84 strails) to the bank account generated. Wallet created successfully and Bank account generation in progress. Bank account is only active for 30mins after creation. Use requestId to get the bank account details for payment.",
    "autoSwapEnabled": false,
    "sweepToOfframpEnabled": false,
    "targetAsset": "USDC",
    "feeBreakdown": {
      "baseAmount": 520,
      "fintechFee": 0,
      "strailsFee": 8.84,
      "totalFee": 8.84,
      "totalAmount": 528.84
    }
  }
}

Error responses

Validation error

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Amount must be greater than 0"
}

User not found

{
  "status": "Error",
  "response_code": "02",
  "message": "User not found",
  "error": "No verified user found with the provided userId"
}

User Offramp

POST /cngnofframp Converts cNGN held in a user’s Smart Wallet to Naira and initiates a bank transfer to the specified account. The call returns immediately with a requestId; the actual bank transfer completes asynchronously.

The amount field is denominated in Naira (e.g. 5000 = ₦5,000), not in token units or kobo.

curl --request POST \
  --url "https://api.strails.io/v1/cngnofframp" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "userId": "user_uniqueID",
    "amount": 5000,
    "accountNumber": "0123456789",
    "bankCode": "058",
    "ticker": "CNGN"
  }'

string

required

Unique identifier (hash or UUID) of the user initiating the offramp.

number

required

Amount to convert and transfer in Naira (e.g. 5000 = ₦5,000). Must be greater than 0.

string

required

The destination bank account number (10 digits).

string

required

The NIBSS bank identifier code (e.g. 058 for GTBank). Use /getbankscode to get a full list.

string

required

The asset symbol being off-ramped (e.g. CNGN).

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Vault return token transfer completed, payout processing initiated",
  "data": {
    "requestId": "uuid",
    "status": "payout_pending",
    "stage": "payout",
    "tokenAddress": "0x...",
    "vaultAddress": "0x..."
  }
}

Error responses

Validation error

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Invalid bank code format"
}

Insufficient balance

{
  "status": "Failed",
  "response_code": "01",
  "message": "Insufficient wallet balance",
  "data": {
    "error": "Insufficient total balance across all networks. Required: 20000 CNGN, Available: 320.000000 CNGN across 36 network(s)"
  }
}

No funded wallet

{
  "status": "Failed",
  "response_code": "02",
  "message": "No funded wallet found for user",
  "data": {
    "error": "User has no funds available across any supported networks"
  }
}

User not found

{
  "status": "Error",
  "response_code": "02",
  "message": "User not found",
  "error": "No verified user found with the provided userId"
}

Fintech Onramp

GET /getfintechvirtualaccount Returns the persistent virtual bank account assigned to your fintech. Any Naira payment received on this account is automatically converted to cNGN and credited to your fintech Smart Wallet.

Use /getfintechwallet to find your Smart Wallet address - that is where disbursed cNGN is credited after a deposit is confirmed.

For full virtual account management (including per-user virtual accounts and fee configuration), see the Virtual Accounts API page.

curl --request GET \
  --url "https://api.strails.io/v1/getfintechvirtualaccount" \
  --header "x-api-key: YOUR_API_KEY"

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Virtual account retrieved successfully",
  "data": {
    "virtualAccount": {
      "accountNumber": "9800000094",
      "accountName": "Example Fintech",
      "bankName": "FAME Bank",
      "provider": "Sample Provider",
      "status": "active",
      "createdAt": "2026-01-28T13:06:38.867Z"
    }
  }
}

Fintech Offramp

POST /initiateofframp Converts cNGN from your fintech Smart Wallet to Naira and initiates a payout to a configured bank account. Returns a requestId immediately; the transfer completes asynchronously.

The amount field must be provided in the lowest token unit (cNGN has 6 decimals). For example, 1000000 represents 1.00 cNGN, not ₦1,000,000 - to off-ramp 1,000 cNGN send 1000000000. Use /listbankaccounts to find your bankAccountId.

curl --request POST \
  --url "https://api.strails.io/v1/initiateofframp" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 1000000,
    "bankAccountId": "uuid-of-bank-account"
  }'

number

required

Amount to transfer in the lowest token unit (e.g. 1000000 = 1.00 cNGN, 1000000000 = 1,000.00 cNGN). Must be greater than 0.

string

required

UUID of the destination bank account, as returned by /addbankaccount.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Offramp initiated successfully",
  "data": {
    "requestId": "uuid",
    "amount": 170,
    "walletSource": "system_wallet",
    "status": "pending",
    "message": "Your offramp request is being processed. cNGN will be transferred from your smart wallet. You will receive a webhook notification when completed."
  }
}

Error responses

Validation error

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Amount must be greater than 0"
}

Bank account not found

{
  "status": "Error",
  "response_code": "02",
  "message": "Bank account not found",
  "error": "No bank account found with the provided bankAccountId"
}

Insufficient balance

{
  "status": "Error",
  "response_code": "05",
  "message": "Insufficient balance",
  "error": "Smart wallet has insufficient cNGN balance"
}

User Token Withdrawal

POST /withdrawasset Withdraws a token from a user’s internal Smart Wallet to an external destination wallet. Supports multi-chain transfers - set the network parameter to route the withdrawal through a bridge to a non-Base chain.

curl --request POST \
  --url "https://api.strails.io/v1/withdrawasset" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "userId": "user_uniqueID",
    "internalWallet": "0xInternalWalletAddress",
    "destinationWallet": "0xExternalWalletAddress",
    "amount": 100,
    "ticker": "CNGN",
    "network": "base"
  }'

string

required

Unique identifier (hash or UUID) of the user initiating the withdrawal.

string

required

The user’s internal (source) wallet address on the platform.

string

required

The external destination address to receive the withdrawn tokens.

number

required

Amount to withdraw in human-readable token units (e.g. 100 = 100 cNGN). Must be greater than 0. Note this differs from /fintechtransfer, which takes the lowest token unit.

string

required

Asset symbol to withdraw (e.g. CNGN, USDC, USDT).

string

Target network for the withdrawal. When set, Strails routes the transfer through a bridge. Supported values: base, bsc, sol, eth, xbn, asc, arc, lisk. Defaults to base if not provided.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Withdrawal executed successfully",
  "data": {
    "transactionHash": "tranx_hash",
    "smartWalletAddress": "0xInternalWalletAddress",
    "requestId": "req_uuid_12345",
    "executedAt": "2026-06-11T08:47:59.653Z",
    "gasUsed": "85397",
    "effectiveGasPrice": "1010000000",
    "blockNumber": "47189167",
    "duration": 8641,
    "userId": "user_uniqueID",
    "amount": "200",
    "destinationWallet": "0xExternalWalletAddress",
    "tokenAddress": "0x46C85152bFe9f96829aA94755D9f915F9B10EF5F",
    "tokenSymbol": "CNGN",
    "network": "base",
    "networkDisplayName": "Base",
    "estimatedConfirmationTime": "2-5 minutes",
    "warnings": ["High gas fees relative to withdrawal amount"],
    "feeBreakdown": {
      "requestedAmount": "200",
      "totalFee": "5.965",
      "netAmount": "194.035",
      "usedFintechOverride": false
    }
  }
}

Error responses

Validation error

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Amount must be greater than 0"
}

User not found

{
  "status": "Error",
  "response_code": "02",
  "message": "User not found",
  "error": "No verified user found with the provided userId"
}

Insufficient balance

{
  "status": "Error",
  "response_code": "05",
  "message": "Insufficient balance",
  "error": "Wallet has insufficient balance for this withdrawal"
}

Fintech Token Withdrawal

POST /fintechtransfer Transfers tokens from your fintech Smart Wallet to a registered external wallet. The destination address must already be whitelisted via /addexternalwallet before you call this endpoint.

You must whitelist the destination address before calling /fintechtransfer. Use /addexternalwallet to register the address first.

The amount field must be in the lowest currency unit. For example, 5000000 = 5.0 cNGN (cNGN uses 6 decimal places). Active orders and escrows reduce the available balance - the API will reject the transfer if the net balance after commitments is insufficient.

curl --request POST \
  --url "https://api.strails.io/v1/fintechtransfer" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "destinationAddress": "0xExternalRegisteredAddress",
    "amount": 5000000,
    "ticker": "CNGN",
    "note": "Withdrawal to cold storage"
  }'

string

required

Ethereum address of the destination wallet. Must be a wallet already registered via /addexternalwallet.

number

required

Amount to transfer in the lowest token unit (e.g. 5000000 = 5.0 cNGN). Note this differs from /withdrawasset, which takes human-readable token units.

string

Token symbol to transfer: CNGN (default), USDC, or USDT.

string

Optional memo for internal record-keeping (max 500 characters).

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Transfer completed successfully",
  "data": {
    "requestId": "req_uuid_12345",
    "transactionHash": "0xabc...def",
    "smartWalletAddress": "0x123...456",
    "destinationAddress": "0x742...c87",
    "destinationLabel": "My Cold Wallet",
    "amount": "5000000",
    "ticker": "CNGN",
    "blockNumber": "12345678",
    "gasUsed": "150000",
    "commitmentsSafeguarded": {
      "activeOrders": 3,
      "activeEscrows": 1,
      "totalCommitted": "2000000",
      "remainingBalance": "3000000"
    },
    "executedAt": "2026-03-21T10:30:00Z",
    "version": "1.0.0",
    "feeBreakdown": {
      "requestedAmount": "5000000",
      "totalFee": "0.15",
      "netAmount": "4999999.85",
      "usedFintechOverride": false
    }
  }
}

Error responses

Destination not registered

{
  "code": "01",
  "message": "Validation error",
  "error": "Destination address is not a registered external wallet"
}

Insufficient balance

{
  "code": "05",
  "message": "Insufficient balance",
  "error": "Smart wallet has insufficient balance after accounting for active orders and escrows"
}

cNGN Onramp Status

POST /cngnonrampstatus Returns the current status of a user onramp request, including virtual account details, funding timestamps, and any active FX quote.

curl --request POST \
  --url "https://api.strails.io/v1/cngnonrampstatus" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "walletAddress": "0xGeneratedWalletAddress"
  }'

string

required

The Smart Wallet address returned by /cngnonramp.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Wallet status retrieved successfully",
  "data": {
    "status": "funded",
    "requestId": "uuid",
    "version": "1.0.0",
    "wallet": {
      "walletAddress": "0x.....",
      "owner": "0x.....",
      "tokenBuy": "USDC",
      "autoSwap": false,
      "sweepToOfframp": true,
      "amount": "200",
      "createdAt": "2026-01-28T11:17:47.513Z",
      "fundingRequestedAt": "2026-01-28T11:21:20.170Z",
      "fundedAt": "2026-01-28T11:22:01.527Z",
      "transactionHash": "0x......",
      "virtualAccountDetails": {
        "accountNumber": "xxxx",
        "bankName": "XXXX Bank",
        "accountName": "Okaformbah",
        "amount": 200,
        "createdAt": "2026-01-28T11:18:09.353Z"
      },
      "virtualAccountStatus": "created"
    },
    "fxQuote": {
      "available": true,
      "pair": "CNGN-USDC",
      "cngnAmount": "1000",
      "tokenAmount": "0.689655",
      "averagePrice": "1450.00",
      "averageSpread": 0.5,
      "expiresAt": "2026-04-04T08:58:36.072Z",
      "note": "This quote is valid for 5 minutes"
    }
  }
}

cNGN Offramp Status

POST /cngnofframpstatus Returns the current status of a user offramp request, including on-chain token transfer details and the fiat payout outcome.

curl --request POST \
  --url "https://api.strails.io/v1/cngnofframpstatus" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "requestId": "uuid"
  }'

string

required

The requestId returned by /cngnofframp.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Vault return status retrieved successfully",
  "data": {
    "requestId": "vr_1769599852415_oosd",
    "status": "completed",
    "stage": "completed",
    "createdAt": "2026-01-28T12:30:54.921Z",
    "updatedAt": "2026-01-28T12:31:10.690Z",
    "tokenAddress": "0x....",
    "amount": "200",
    "tokenTransfer": {
      "status": "confirmed",
      "transactionHash": "0x....",
      "blockNumber": "41405258",
      "timestamp": "2026-01-28T12:31:02.112Z"
    },
    "payout": {
      "status": "completed",
      "reference": "0x....",
      "transactionId": "0x....",
      "timestamp": "2026-01-28T12:31:10.690Z",
      "attempts": 1
    }
  }
}

Fintech Offramp Status

GET /getofframpstatus Returns the current status of a fintech offramp request initiated via /initiateofframp.

curl --request GET \
  --url "https://api.strails.io/v1/getofframpstatus?requestId=uuid" \
  --header "x-api-key: YOUR_API_KEY"

string

required

The requestId returned by /initiateofframp.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Offramp status retrieved successfully",
  "data": {
    "requestId": "uuid",
    "status": "completed",
    "amount": 17000,
    "currency": "NGN",
    "bankAccount": {
      "accountNumber": "123456789",
      "accountName": "Bidemi Chioma Hauwa",
      "bankName": "UNITED BANK"
    },
    "wallet": {
      "source": "system_wallet",
      "address": "0x...."
    },
    "transferDetails": {
      "txHash": "0x-transactionHash",
      "status": "confirmed"
    },
    "payoutDetails": {
      "reference": "uuid",
      "provider": "novac",
      "status": "completed"
    },
    "initiatedAt": "2026-01-29T03:56:20.198Z",
    "completedAt": "2026-01-29T03:57:07.012Z"
  }
}

List Deposits

GET /deposits Returns a paginated list of deposit transactions. Filter by type (fintech_deposit for direct fintech deposits, user_onramp for end-user onramps), status, date range, and user.

curl --request GET \
  --url "https://api.strails.io/v1/deposits?type=fintech_deposit&status=completed&limit=20&offset=0" \
  --header "x-api-key: YOUR_API_KEY"

string

Transaction type filter. One of fintech_deposit or user_onramp.

string

Filter by end-user ID. Only applicable when type is user_onramp.

string

Filter by status. One of pending, processing, completed, failed, or cancelled.

string

ISO 8601 start of the date range (e.g. 2026-01-01T00:00:00Z).

string

ISO 8601 end of the date range (e.g. 2026-01-31T23:59:59Z).

number

Maximum number of results to return. Defaults to 20, maximum 100.

number

Pagination offset. Defaults to 0.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Deposits retrieved successfully",
  "data": {
    "deposits": [
      {
        "id": "6653603d-74fd-4a1f-80a1-d9b84bc0173a",
        "type": "fintech_deposit",
        "direction": "in",
        "fintechId": "c8fe1911-d292-4f84-aa88-e34ceeea5b65",
        "amount": 500,
        "currency": "NGN",
        "virtualAccountNumber": "9800000094",
        "virtualAccountName": "Example Fintech",
        "depositor": {
          "name": "JOHN DOE",
          "accountNumber": "1234567890",
          "bankName": "SAMPLE BANK",
          "bankCode": "000001"
        },
        "transactionReference": "000015260129043400000000099569",
        "provider": "novac",
        "status": "completed",
        "walletAddress": "0x3af904Ff6FA747A3da92E7ce21d312de4b2Ef967",
        "mintTxHash": "0x59a8094c6dce96396d50e67083eba7d7d4ac7cd4393e976c7e73e46a67164077",
        "createdAt": "2026-01-29T03:34:35.582Z",
        "completedAt": "2026-01-29T03:35:12.198Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false,
    "filters": { "type": "fintech_deposit" }
  }
}

List Payouts

GET /payouts Returns a paginated list of payout transactions. Filter by type (fintech_offramp for fintech-initiated payouts, user_offramp for end-user offramps), status, date range, and user.

curl --request GET \
  --url "https://api.strails.io/v1/payouts?type=fintech_offramp&status=completed&limit=10&offset=0" \
  --header "x-api-key: YOUR_API_KEY"

string

Transaction type filter. One of fintech_offramp or user_offramp.

string

Filter by end-user ID. Only applicable when type is user_offramp.

string

Filter by status. One of pending, processing, completed, failed, or cancelled.

string

ISO 8601 start of the date range.

string

ISO 8601 end of the date range.

number

Maximum number of results to return. Defaults to 20, maximum 100.

number

Pagination offset. Defaults to 0.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Payouts retrieved successfully",
  "data": {
    "payouts": [
      {
        "id": "6653603d-74fd-4a1f-80a1-d9b84bc0173a",
        "type": "fintech_offramp",
        "direction": "out",
        "fintechId": "c8fe1911-d292-4f84-aa88-e34ceeea5b65",
        "amount": 5000,
        "currency": "NGN",
        "sourceWalletAddress": "0x3af904Ff6FA747A3da92E7ce21d312de4b2Ef967",
        "sourceNetwork": "base",
        "bankAccount": {
          "accountNumber": "0123456789",
          "accountName": "JANE DOE",
          "bankName": "UNITED BANK FOR AFRICA",
          "bankCode": "000004"
        },
        "status": "completed",
        "transferTxHash": "0x59a8094c6dce96396d50e67083eba7d7d4ac7cd4393e976c7e73e46a67164077",
        "payoutReference": "6653603d-74fd-4a1f-80a1-d9b84bc0173a",
        "payoutProvider": "novac",
        "payoutStatus": "completed",
        "processingFee": 75.00,
        "totalDeducted": 5075.00,
        "createdAt": "2026-01-29T03:56:20.198Z",
        "completedAt": "2026-01-29T03:57:07.012Z"
      }
    ],
    "total": 1,
    "limit": 10,
    "offset": 0,
    "hasMore": false,
    "filters": { "type": "fintech_offramp", "status": "completed" }
  }
}

List Transactions

GET /transactions Returns a paginated list of all transactions - both deposits and payouts - with a combined summary. Use direction to separate inbound from outbound flows.

curl --request GET \
  --url "https://api.strails.io/v1/transactions?direction=in&status=completed&limit=50&offset=0" \
  --header "x-api-key: YOUR_API_KEY"

string

Filter by flow direction. in for deposits, out for payouts.

string

Filter by type. One of fintech_deposit, user_onramp, fintech_offramp, or user_offramp.

string

Filter by end-user ID.

string

Filter by status. One of pending, processing, completed, failed, or cancelled.

string

ISO 8601 start of the date range.

string

ISO 8601 end of the date range.

number

Maximum number of results to return. Defaults to 20, maximum 100.

number

Pagination offset. Defaults to 0.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Transactions retrieved successfully",
  "data": {
    "transactions": [
      {
        "id": "000015260129043400000000099569",
        "type": "fintech_deposit",
        "direction": "in",
        "fintechId": "c8fe1911-d292-4f84-aa88-e34ceeea5b65",
        "amount": 500,
        "currency": "NGN",
        "virtualAccountNumber": "9800000094",
        "virtualAccountName": "Example Fintech",
        "depositor": {
          "name": "JOHN DOE",
          "accountNumber": "1234567890",
          "bankName": "SAMPLE BANK",
          "bankCode": "000001"
        },
        "transactionReference": "000015260129043400000000099569",
        "provider": "novac",
        "status": "completed",
        "walletAddress": "0x3af904Ff6FA747A3da92E7ce21d312de4b2Ef967",
        "createdAt": "2026-01-29T03:34:35.582Z",
        "completedAt": "2026-01-29T03:35:12.198Z"
      }
    ],
    "total": 2,
    "limit": 50,
    "offset": 0,
    "hasMore": false,
    "summary": {
      "totalDeposits": 2,
      "totalPayouts": 0,
      "depositVolume": "1500.00",
      "payoutVolume": "0.00"
    },
    "filters": { "direction": "in", "status": "completed" }
  }
}

Withdraw History

GET /withdrawals Returns a paginated list of token withdrawal transfers, including fintech self-transfers, fintech withdrawals on behalf of users, and direct user withdrawals. Filter by token ticker, status, transfer type, user, date range, and pagination.

curl --request GET \
  --url "https://api.strails.io/v1/withdrawals?ticker=CNGN&status=completed&type=fintech_user_withdrawal&limit=20&offset=0" \
  --header "x-api-key: YOUR_API_KEY"

Available query parameters

Param	Type	Description
`ticker`	string	Token ticker, e.g. `CNGN`
`status`	string	`pending`, `completed`, `failed`
`type`	string	`fintech_self_transfer`, `fintech_user_withdrawal`, `user_withdrawal`
`userId`	string	Filter by end-user hash/id
`startDate`	ISO date	e.g. `2026-09-01`
`endDate`	ISO date	e.g. `2026-09-15`
`limit`	number	Page size (default 20)
`offset`	number	Pagination offset (default 0)

string

Token ticker, e.g. CNGN.

string

Filter by status. One of pending, completed, or failed.

string

Filter by transfer type. One of fintech_self_transfer, fintech_user_withdrawal, or user_withdrawal.

string

Filter by end-user hash/id. Only applicable when type includes user-related withdrawals.

string

ISO 8601 start of the date range.

string

ISO 8601 end of the date range.

number

Maximum number of results to return. Defaults to 20.

number

Pagination offset. Defaults to 0.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Withdrawals retrieved successfully",
  "data": {
    "transfers": [
      {
        "transferId": "07148ef1-3e9a-45f4-9fcd-5a318c187ba5",
        "fintechId": "fintech_UniqueID",
        "userId": "user_UniqueID",
        "type": "fintech_user_withdrawal",
        "status": "completed",
        "source": {
          "smartWalletAddress": "0x92e48c8Ce75CD34aC83011296C817bA62D7bAC67",
          "network": "base"
        },
        "destination": {
          "address": "0x1843b0A71A716d0bD1F233Af45F451E48a49a2ed",
          "network": "base"
        },
        "token": {
          "ticker": "CNGN",
          "address": "0x46C85152bFe9f96829aA94755D9f915F9B10EF5F",
          "decimals": 6
        },
        "amounts": {
          "requested": "1600",
          "fee": "100",
          "net": "1500",
          "feeBreakdown": {
            "gasFee": "0",
            "usedFintechOverride": false,
            "platformFee": "100"
          }
        },
        "transactionHash": "0xe2ea9bfe8e84953c979d54ae29c3c9a2fe334b2cad45b5bec46e5a53b9fa91f7",
        "note": "Fintech withdrawal on behalf of user user_UniqueID",
        "createdAt": "2026-09-15T15:45:45.216Z",
        "updatedAt": "2026-09-15T15:45:45.216Z"
      }
    ],
    "pagination": {
      "total": 2,
      "limit": 20,
      "offset": 0,
      "hasMore": false
    },
    "filters": {}
  }
}

Swap Trigger

POST /swaptrigger Queues an asynchronous token swap for a specific wallet address. The swap is processed in the background - use /swapstatus with the returned requestId to poll for completion.

curl --request POST \
  --url "https://api.strails.io/v1/swaptrigger" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "walletAddress": "0xGeneratedWalletAddress",
    "sellToken": "CNGN",
    "buyToken": "USDC",
    "amount": 500,
    "slippage": 2
  }'

string

required

The Smart Wallet address generated during a /cngnonramp request.

string

required

The token to sell. One of CNGN, USDC, or USDT.

string

The token to buy. One of CNGN, USDC, or USDT. Falls back to the wallet’s configured tokenBuy if not provided.

number

Human-readable amount of sellToken to swap. Falls back to the wallet’s funded amount if not provided.

number

Maximum acceptable slippage percentage. Defaults to 5.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Swap trigger submitted successfully",
  "data": {
    "requestId": "req_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "queued",
    "message": "Your swap request has been queued and will be processed asynchronously",
    "swapConfig": {
      "sellToken": "CNGN",
      "buyToken": "USDT",
      "amount": "500.000000",
      "walletAddress": "0x..."
    },
    "destinationConfig": {
      "destinationWallet": "fintech_smart_wallet",
      "sweepToOfframp": false
    }
  }
}

Error responses

Validation error

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Invalid wallet address format"
}

Insufficient liquidity

{
  "status": "Error",
  "response_code": "05",
  "message": "Insufficient liquidity",
  "error": "Not enough liquidity in pool for swap"
}

User Swap

POST /swap Requests a token swap on a user’s default Smart Wallet. Primarily used for USDC -> cNGN conversions. The swap is processed asynchronously - use /swapstatus with the returned requestId to track completion.

curl --request POST \
  --url "https://api.strails.io/v1/swap" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "sellToken": "USDC",
    "buyToken": "CNGN",
    "amount": 100.50,
    "slippage": 2,
    "userId": "user_hash",
    "smartWalletAddress": "0xSmartWalletAddress",
    "destinationAssetSwap": "0xDestinationAddress"
  }'

string

required

The token to sell. One of USDC, USDT, or CNGN.

string

required

The token to buy. One of USDC, USDT, or CNGN.

number

required

Human-readable amount to swap (e.g. 100.50 = 100.50 USDC).

string

required

Unique identifier (hash or UUID) of the verified end-user.

number

Maximum acceptable slippage percentage. Defaults to 2.

string

The user’s Smart Wallet address to execute the swap from. If not provided, the user’s default Smart Wallet is used.

string

Alternative destination wallet for the output tokens. If not provided, output tokens are sent to the user’s default Smart Wallet.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Swap request submitted successfully",
  "data": {
    "requestId": "swap-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "requested",
    "message": "Your swap request has been submitted and will be processed asynchronously",
    "smartWalletExecutionDetails": {
      "smartWalletAddress": "0x...",
      "executionMethod": "smart_wallet_execute",
      "validationSummary": {
        "balanceCheck": "passed",
        "allowanceCheck": "passed"
      }
    }
  }
}

Error responses

Validation error

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Amount must be greater than 0"
}

User not found

{
  "status": "Error",
  "response_code": "02",
  "message": "User not found",
  "error": "No verified user found with the provided userId"
}

Insufficient balance

{
  "status": "Error",
  "response_code": "05",
  "message": "Insufficient balance",
  "error": "Wallet has insufficient balance for this swap"
}

Swap Status

GET /swapstatus Returns the current status of an asynchronous swap request. Use the requestId returned from either /swaptrigger or /swap.

curl --request GET \
  --url "https://api.strails.io/v1/swapstatus?requestId=swap-a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  --header "x-api-key: YOUR_API_KEY"

string

required

The requestId returned by /swaptrigger or /swap.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Operation status retrieved successfully",
  "data": {
    "requestId": "swap-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "swap_trigger",
    "status": "completed",
    "createdAt": "2026-05-26T10:30:00.000Z",
    "updatedAt": "2026-05-26T10:30:45.000Z",
    "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "amountOut": "775000000",
    "executionRate": "1550.25",
    "executionMethod": "smart_wallet_execute",
    "smartWalletAddress": "0x625A4612e3aAa7ce62C43EdDf5C81d7443418E4f"
  }
}

Error response

Request not found

{
  "status": "Error",
  "response_code": "02",
  "message": "Not found",
  "error": "No swap request found with the provided requestId"
}

Swap History

GET /swaphistory Returns a paginated list of historical swap requests for your fintech. Use this endpoint to reconcile completed, requested, and failed swaps without polling each requestId individually.

curl --request GET \
  --url "https://api.strails.io/v1/swaphistory?limit=20&offset=0" \
  --header "x-api-key: YOUR_API_KEY"

number

Maximum number of results to return. Defaults to 20.

number

Pagination offset. Defaults to 0.

string

Filter by swap status. One of requested, completed, or failed.

string

ISO 8601 start of the date range (e.g. 2026-01-01T00:00:00Z).

string

ISO 8601 end of the date range (e.g. 2026-01-31T23:59:59Z).

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Swap history retrieved",
  "data": {
    "swaps": [
      {
        "requestId": "swap-d5eb87a7-00e5-4651-87e3-05a9efa7c5c8",
        "type": "swap",
        "status": "completed",
        "sellToken": "USDC",
        "buyToken": "CNGN",
        "amountIn": "0.710696",
        "amountOut": "2198.456643",
        "executionRate": "1393",
        "smartWalletAddress": "0x431890688290b1b7Ff9AB28ee3070c0aDF7b3422",
        "txHash": "0x308b27309352f53ccd827a900cd1924c36394e8fd6c634cc6eb40b9b4358eds4",
        "triggerType": "direct",
        "createdAt": "2026-09-08T09:55:55.235Z",
        "updatedAt": "2026-09-08T09:57:04.866Z"
      }
    ],
    "pagination": {
      "total": 29,
      "limit": 20,
      "offset": 0,
      "hasMore": true
    }
  },
  "version": "1.0.0"
}

array

List of swap records. Each entry contains the swap’s requestId, status, sellToken, buyToken, amountIn, amountOut, executionRate, smartWalletAddress, txHash, triggerType, and timestamps.

object

Pagination metadata including total, limit, offset, and hasMore.

Overview

Core APIs

FX & Trading

Configuration

Transactions API: Onramp, Offramp, Swaps & Transfers

Endpoints Overview

User Onramp

autoSwap behaviour matrix

User Offramp

Fintech Onramp

Fintech Offramp

User Token Withdrawal

Fintech Token Withdrawal

cNGN Onramp Status

cNGN Offramp Status

Fintech Offramp Status

List Deposits

List Payouts

List Transactions

Withdraw History

Available query parameters

Swap Trigger

User Swap

Swap Status

Swap History

​Endpoints Overview

​User Onramp

​autoSwap behaviour matrix

​User Offramp

​Fintech Onramp

​Fintech Offramp

​User Token Withdrawal

​Fintech Token Withdrawal

​cNGN Onramp Status

​cNGN Offramp Status

​Fintech Offramp Status

​List Deposits

​List Payouts

​List Transactions

​Withdraw History

​Available query parameters

​Swap Trigger

​User Swap

​Swap Status

​Swap History

Endpoints Overview

User Onramp

autoSwap behaviour matrix

User Offramp

Fintech Onramp

Fintech Offramp

User Token Withdrawal

Fintech Token Withdrawal

cNGN Onramp Status

cNGN Offramp Status

Fintech Offramp Status

List Deposits

List Payouts

List Transactions

Withdraw History

Available query parameters

Swap Trigger

User Swap

Swap Status

Swap History