Transactions API

The Transactions API handles all financial operations including onramp (funding), offramp (payout), token swaps, asset transfers, and transaction tracking.

Transactions API — Endpoints Overview

Section	Endpoint	Method	Description
User Onramp	`/cngnonramp`	POST	Fund a user wallet by converting fiat to cNGN or supported tokens
User Offramp	`/cngnofframp`	POST	Returns cNGN in user’s wallet to payout fiat to user bank account
Fintech Onramp	`/getfintechvirtualaccount`	GET	Returns the bank account attached to a fintech
Fintech Offramp	`/initiateofframp`	POST	Returns cNGN in fintech’s wallet to payout fiat
User Token Withdrawal	`/withdrawasset`	POST	Multi-asset support. Withdraw assets from user wallet to external wallet
Fintech Token Withdrawal	`/fintechtransfer`	POST	Multi-asset support. Withdraw assets from fintech smart wallet to external wallet
cNGN Onramp Status	`/cngnonrampstatus`	POST	Check funding request status
cNGN Offramp Status	`/cngnofframpstatus`	POST	Check offramp transaction status
Fintech Offramp Status	`/getofframpstatus`	GET	Check fintech offramp transaction status
List Deposits	`/deposits`	GET	Retrieve deposit transactions with filters
List Payouts	`/payouts`	GET	Retrieve payout transactions with filters
List Transactions	`/transactions`	GET	Retrieve all transactions (deposits & payouts) with filters
Swap Trigger	`/swaptrigger`	POST	Trigger an asynchronous token swap (cNGN ↔ USDC/USDT)
User Swap	`/swap`	POST	Swap tokens on user’s default smart wallet (USDC → cNGN)
Swap Status	`/swapstatus`	GET	Get the status of an asynchronous swap request

User Onramp (user wallet funding)

Use the /getvirtualaccount endpoint to get the account to make payment. Bank account is only active for 30mins after creation.

Payment into the generated account must be from the bank account of the verified Fintech user. The generated wallet is a Smart Wallet which can be controlled/owned by your external EOA wallet. Also, kindly note that OWNER parameter is not compulsory.

Request (Onramp)
Body (Onramp)
Response (Onramp)
Error (Onramp)

POST {{BASE_URL}}/cngnonramp

{
  "owner": "",
  "amount": 500,
  "assetSwap": "USDC",
  "autoSwap": true,
  "userId": "user_uniqueID",
  "sweepToOfframp": true,
  "destinationAssetSwap": "0x..."
}

Parameters

Parameter	Type	Required	Description
`owner`	string	No	Your EOA wallet address to control the generated Smart Wallet. When set, you can withdraw tokens directly using your EOA. Note: StRails cannot withdraw funds from wallets with a custom owner.
`amount`	number	Yes	Amount to fund in Naira (e.g., `500` = ₦500)
`assetSwap`	string	No	Asset to swap into after funding (e.g. `USDC`)
`autoSwap`	boolean	No	Automatically swap funded amount to `assetSwap`
`userId`	string	Yes	Unique identifier (hash/UUID) of the user
`sweepToOfframp`	boolean	No	Automatically route funds to the user’s default wallet after funding
`destinationAssetSwap`	string	No	Destination wallet address for swapped assets. Only used when `autoSwap=true` and `sweepToOfframp=false`.

Behavior Matrix

`autoSwap`	`sweepToOfframp`	`destinationAssetSwap`	Result
`false`	`false`	—	cNGN stays in generated wallet
`false`	`true`	ignored	cNGN → user’s default wallet
`true`	`false`	not set	cNGN→USDC, stays in generated wallet
`true`	`false`	set	cNGN→USDC → `destinationAssetSwap`
`true`	`true`	ignored	cNGN→USDC → user’s default wallet

Note: When sweepToOfframp=true, the destination is automatically resolved to the user’s default smart wallet (verifiedUsers.smartWalletAddress). You don’t need to set destinationAssetSwap.

{
  "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
    }
  }
}

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

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

User Offramp (payout to user bank account)

Request (Offramp)
Body (Offramp)
Response (Offramp)
Error (Offramp)

POST {{BASE_URL}}/cngnofframp

{
  "userId": "user_uniqueID",
  "amount": 5000,
  "accountNumber": "0123456789",
  "bankCode": "058",
  "ticker": "CNGN"
}

Parameters

Parameter	Type	Required	Description
`userId`	string	Yes	Unique identifier (hash/UUID) of the user initiating the offramp
`amount`	number	Yes	Amount to convert and transfer to bank in Naira (e.g., `5000` = ₦5,000)
`accountNumber`	string	Yes	Destination bank account number
`bankCode`	string	Yes	Bank identifier code (e.g. NIBSS bank code such as `058`)
`ticker`	string	Yes	Asset symbol being off-ramped (e.g. `CNGN`)

{
  "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..."
  }
}

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

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

{
  "status": "Error",
  "response_code": "05",
  "message": "Insufficient balance",
  "error": "User wallet has insufficient cNGN balance for this offramp"
}

Fintech Onramp

Use the /getfintechwallet endpoint to get the fintech default wallet where cNGN is sent to after payment is confirmed.

Request (Fintech Onramp)
Response (Fintech Onramp)

GET {{BASE_URL}}/getfintechvirtualaccount

{
  "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 Offramping

Request (Wallet→Bank)
Body (Wallet→Bank)
Response (Wallet→Bank)
Error (Wallet→Bank)

POST {{BASE_URL}}/initiateofframp

{
  "amount": 1000000,
  "bankAccountId": "uuid"
}

Parameters

Parameter	Type	Required	Description
`amount`	number	Yes	Amount to transfer from wallet to bank (in lowest currency unit)
`bankAccountId`	string	Yes	Unique identifier (UUID) of the beneficiary bank account

{
    "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."
    }
}

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

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

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

User Token Withdrawal

Request (Withdrawal)
Body (Withdrawal)
Response (Withdrawal)
Error (Withdrawal)

POST {{BASE_URL}}/withdrawasset

{
  "userId": "user_uniqueID",
  "internalWallet": "0xInternal",
  "destinationWallet": "0xExternal",
  "amount": 100,
  "ticker": "CNGN",
  "network": "base"
}

Parameters

Parameter	Type	Required	Description
`userId`	string	Yes	Unique identifier (hash/UUID) of the user initiating the withdrawal
`internalWallet`	string	Yes	User’s internal wallet address on the platform (source wallet)
`destinationWallet`	string	Yes	External wallet or bank-linked wallet address to receive funds
`amount`	number	Yes	Amount to withdraw (must be greater than 0)
`ticker`	string	Yes	Asset symbol to withdraw (e.g. `CNGN`)
`network`	string	No	When set, uses a bridge to withdraw the token via the specified network (e.g., `base`, `bsc`, `sol`, `eth`, `xbn`, `asc`, `arc`, `lisk`). Defaults to Base if left empty

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

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

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

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

Fintech Token Withdrawal

Ensure you whitelist the address you are about to transfer to before calling /fintechtransfer endpoint. Use the /addexternalwallet endpoint to whitelist an address.

Request (Fintech Withdrawal)
Body (Fintech Withdrawal)
Response (Fintech Withdrawal)
Error (Fintech Withdrawal)

POST {{BASE_URL}}/fintechtransfer

{
  "destinationAddress": "0xExternal",
  "amount": 5000000,
  "ticker": "CNGN",
  "note": "Withdrawal to cold storage"
}

Parameters

Parameter	Type	Required	Description
`destinationAddress`	string	Yes	Ethereum address (must be a registered external wallet)
`amount`	number	Yes	Amount in smallest unit (e.g., 5000000 = 5.0 cNGN)
`ticker`	string	No	Token symbol: CNGN (default), USDC, USDT
`note`	string	No	Optional note (max 500 characters)

{
  "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"
  }
}

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

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

cNGN OnRamp Status

Request (OnRamp Status)
Body (OnRamp Status)
Response (OnRamp Status)

POST {{BASE_URL}}/cngnonrampstatus

{
  "walletAddress": "0x.."
}

{
  "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

Request (OffRamp Status)
Body (OffRamp Status)
Response (OffRamp Status)

POST {{BASE_URL}}/cngnofframpstatus

{
  "requestId": "uuid"
}

{
  "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

Request (Fintech Offramp Status)
Response (Fintech Offramp Status)

GET {{BASE_URL}}/getofframpstatus?requestId=uuid

Query Parameters

Parameter	Type	Required	Description
`requestId`	string	Yes	Unique identifier (UUID) of the offramp request

{
  "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": "Ox-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

Retrieve deposit transactions with optional filters for type, status, date range, and pagination.

Request (List Deposits)
Response (List Deposits)

GET {{BASE_URL}}/deposits?type=fintech_deposit&offset=0

Query Parameters

Filter	Type	Values
`type`	string	`fintech_deposit`, `user_onramp`
`userId`	string	User hash (for `user_onramp` only)
`status`	string	`pending`, `processing`, `completed`, `failed`, `cancelled`
`startDate`	ISO date	e.g., `2026-01-01T00:00:00Z`
`endDate`	ISO date	e.g., `2026-01-31T23:59:59Z`
`limit`	number	Max results (default: 20, max: 100)
`offset`	number	Pagination offset

{
  "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

Retrieve payout transactions with optional filters for type, status, date range, and pagination.

Request (List Payouts)
Response (List Payouts)

GET {{BASE_URL}}/payouts?type=fintech_offramp&status=completed&limit=10

Query Parameters

Filter	Type	Values
`type`	string	`fintech_offramp`, `user_offramp`
`userId`	string	User hash (for `user_offramp` only)
`status`	string	`pending`, `processing`, `completed`, `failed`, `cancelled`
`startDate`	ISO date	e.g., `2026-01-01T00:00:00Z`
`endDate`	ISO date	e.g., `2026-01-31T23:59:59Z`
`limit`	number	Max results (default: 20, max: 100)
`offset`	number	Pagination offset

{
  "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",
        "initiatedAt": "2026-01-29T03:56:20.198Z",
        "completedAt": "2026-01-29T03:57:07.012Z",
        "updatedAt": "2026-01-29T03:57:07.012Z"
      }
    ],
    "total": 1,
    "limit": 10,
    "offset": 0,
    "hasMore": false,
    "filters": {
      "type": "fintech_offramp",
      "status": "completed"
    }
  }
}

List Transactions

Retrieve all transactions (both deposits and payouts) with optional filters for direction, type, status, date range, and pagination.

Request (List Transactions)
Response (List Transactions)

GET {{BASE_URL}}/transactions?direction=in&status=completed&limit=50

Query Parameters

Filter	Type	Values
`direction`	string	`in` (deposits), `out` (payouts)
`type`	string	`fintech_deposit`, `user_onramp`, `fintech_offramp`, `user_offramp`
`userId`	string	User hash
`status`	string	`pending`, `processing`, `completed`, `failed`, `cancelled`
`startDate`	ISO date	e.g., `2026-01-01T00:00:00Z`
`endDate`	ISO date	e.g., `2026-01-31T23:59:59Z`
`limit`	number	Max results (default: 20, max: 100)
`offset`	number	Pagination offset

{
  "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"
      },
      {
        "id": "000015260128161759000004122348",
        "type": "fintech_deposit",
        "direction": "in",
        "fintechId": "c8fe1911-d292-4f84-aa88-e34ceeea5b65",
        "amount": 1000,
        "currency": "NGN",
        "virtualAccountNumber": "9800000094",
        "virtualAccountName": "Example Fintech",
        "depositor": {
          "name": "JOHN DOE",
          "accountNumber": "1234567890",
          "bankName": "SAMPLE BANK",
          "bankCode": "000001"
        },
        "transactionReference": "000015260128161759000004122348",
        "provider": "novac",
        "status": "completed",
        "walletAddress": "0x3af904Ff6FA747A3da92E7ce21d312de4b2Ef967",
        "createdAt": "2026-01-28T15:18:20.327Z",
        "completedAt": "2026-01-28T15:19:05.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"
    }
  }
}

Swap Trigger

Trigger an asynchronous token swap between cNGN and USDC/USDT. The swap is queued and processed in the background.

Request (Swap Trigger)
Body (Swap Trigger)
Response (Swap Trigger)
Error (Swap Trigger)

POST {{BASE_URL}}/swaptrigger

{
  "walletAddress": "0x...",
  "sellToken": "CNGN",
  "buyToken": "USDC",
  "amount": 500,
  "slippage": 2
}

Parameters

Parameter	Type	Required	Description
`walletAddress`	string	Yes	Wallet address generated during `/cngnonramp` request
`sellToken`	string	Yes	Token to sell (`CNGN`, `USDC`, or `USDT`)
`buyToken`	string	No	Token to buy (`CNGN`, `USDC`, or `USDT`). Falls back to wallet’s `tokenBuy` if not provided
`amount`	number	No	Fiat amount of `sellToken` to swap (human-readable format). Falls back to funded amount if not provided
`slippage`	number	No	Maximum slippage percentage (default: 5%)

{
  "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
    }
  }
}

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

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

User Swap

Request a token swap on the user’s default smart wallet address. Primarily used for USDC → cNGN conversions.

Request (User Swap)
Body (User Swap)
Response (User Swap)
Error (User Swap)

POST {{BASE_URL}}/swap

{
  "sellToken": "USDC",
  "buyToken": "CNGN",
  "amount": 100.50,
  "slippage": 2,
  "userId": "user_hash",
  "smartWalletAddress": "0x...",
  "destinationAssetSwap": "0x..."
}

Parameters

Parameter	Type	Required	Description
`sellToken`	string	Yes	Token to sell (`USDC`, `USDT`, or `CNGN`)
`buyToken`	string	Yes	Token to buy (`USDC`, `USDT`, or `CNGN`)
`amount`	number	Yes	Human-readable amount to swap (e.g., `100.50` = 100.50 USDC)
`slippage`	number	No	Maximum slippage percentage (default: 2%)
`userId`	string	Yes	User identifier (verified user hash)
`smartWalletAddress`	string	No	User’s smart wallet address. If not provided, uses user’s default smart wallet
`destinationAssetSwap`	string	No	Alternative destination wallet for output tokens. If not provided, tokens go to user’s default smart wallet

{
  "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"
      }
    }
  }
}

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

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

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

Swap Status

Get the status of an asynchronous swap request. Use the requestId returned from /swaptrigger or /swap to track progress.

Request (Swap Status)
Response (Swap Status)
Error (Swap Status)

GET {{BASE_URL}}/swapstatus?requestId=swap-xxx

Query Parameters

Parameter	Type	Required	Description
`requestId`	string	Yes	Request ID from `/swaptrigger` 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"
  }
}

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

​Transactions API