NGN

The NGN wallet holds Nigerian naira. Customers can receive funds by bank transfer or, when enabled, cNGN on Base. Both routes credit the same NGN wallet. Available NGN can fund trades or withdrawals, subject to account limits. Use currency: "NGN" for wallet activity and settlement_rail: "CNGN" for cNGN transfers. Both use the NGN balance. NGN amounts are decimal strings with two decimal places; use decimal arithmetic rather than floating point.

Before you start

Set STABYL_BASE_URL to your environment’s API URL, including /v1. Authenticated reads require X-Api-Key with wallets:view. Withdrawal quotes and submissions require wallets:withdraw and Ed25519 request signing. In production, approved KYB is required to retrieve deposit instructions and submit withdrawals. Read route availability before offering a deposit or withdrawal option:

curl "$STABYL_BASE_URL/partner/wallets/chains?currency=NGN"

Check each rail’s deposit_enabled and withdrawal_enabled, and the same flags on its network routes. Bank rails have no blockchain routes. CNGN uses network: "evm" and chain.slug: "base". Availability can differ by environment; the presence of a rail in the response does not mean it is enabled.

Receive NGN by bank transfer

Retrieve your deposit account:

curl "$STABYL_BASE_URL/partner/wallets/fiat/deposit-account?currency=NGN" \
  -H "X-Api-Key: $STABYL_API_KEY"

Show the returned bank name, account name, and account number exactly. Subscribe to deposit.success and deposit.failed, and reconcile activity through wallet transactions:

curl "$STABYL_BASE_URL/partner/wallets/transactions?currency=NGN&tx_type=deposit" \
  -H "X-Api-Key: $STABYL_API_KEY"

Store the transaction id as your reconciliation identifier. Follow next_cursor to retrieve subsequent pages. See Fiat deposit accounts for bank discovery and account verification.

Read balances and trade

Call GET /partner/wallets/balances/overview. Read the NGN entry in data.balances and the separate data.withdrawable.ngn value:

Field	How to use it
`total`	Total NGN balance, including available and locked funds.
`available`	NGN available to spend or trade. Use this for your trading balance display.
`locked`	Funds unavailable for spending, including pending activity and CNGN awaiting conversion capacity.
`withdrawable.ngn`	NGN eligible for withdrawal after credit restrictions; may be `null` when temporarily unavailable. Use withdrawal quotes for rail-specific limits and fees.

Use the returned available amount directly; it already excludes locked funds. A balance read does not reserve funds; the trade or withdrawal request checks availability when submitted. Use Exchange to discover markets and place trades.

Withdraw NGN to a bank

Quote with POST /partner/wallets/withdrawal/quotes, using currency: "NGN" and bank-account items. Submit the same intent to POST /partner/wallets/withdrawals with a stable idempotency_key. See Single withdrawals for request bodies and signing, or Bulk withdrawals for multiple beneficiaries. Read the bank_transfer quote’s status, max_withdrawable_amount, fee, and debit_amount. The maximum is recipient principal after allowing for fees and applicable limits. Funds awaiting CNGN conversion are excluded. A valid request above the maximum returns an unavailable quote with the current maximum, so your application can offer a smaller amount. Store the submitted transaction ID. A processing response is not payment completion: follow wallet transactions and withdrawal events for the final outcome.

cNGN

cNGN is a naira-denominated digital currency. On Stabyl, customers can receive and send cNGN on Base through their NGN wallet. Amounts convert at 1 cNGN = ₦1, before fees. Use NGN as the wallet currency and CNGN as the settlement rail in API requests. A cNGN deposit may be credited before its full value is available for trading or bank withdrawal. Your integration should check conversion availability before showing deposit instructions, then use balances and withdrawal quotes to show what the customer can do with credited funds.

Check conversion capacity

Check the cNGN route’s enabled flags using GET /partner/wallets/chains?currency=NGN. Then check how much cNGN can currently convert to spendable NGN:

curl "$STABYL_BASE_URL/partner/wallets/rails/CNGN/pool" \
  -H "X-Api-Key: $STABYL_API_KEY"

{
  "status": "success",
  "data": {
    "rail": "CNGN",
    "currency": "NGN",
    "cap": "500000000.00",
    "utilized": "450000000.00",
    "available": "50000000.00",
    "status": "available",
    "as_of": "2026-10-20T12:00:00Z"
  }
}

Amounts are NGN decimal strings. cap is the total conversion limit, utilized is the amount in use, and available is the remaining capacity at as_of.

`status`	How to use it
`available`	Show the current `available` amount.
`exhausted`	Explain that new deposits may need to wait before trading or bank withdrawal.
`paused`	Explain that conversion to spendable NGN is temporarily paused.

Availability is shared across customers and can change before a deposit arrives. This response does not reserve capacity. A deposit route must also be enabled before you offer it.

For a 503 response, show availability as temporarily unknown and retry with backoff. The rail path accepts either CNGN or cngn; responses use CNGN.

Receive cNGN

Retrieve the Base deposit address:

curl "$STABYL_BASE_URL/partner/wallets/crypto/address?chain=evm&slug=base" \
  -H "X-Api-Key: $STABYL_API_KEY"

Show cNGN on Base, the returned address, any memo, and the route’s minimum_deposit_amount. Customers must send the supported token on the correct network. Subscribe to deposit events and read wallet transactions to track the deposit. cNGN activity uses currency: "NGN" and settlement_rail: "CNGN". Store the wallet transaction id. If required_action.type is travel_rule, complete the Travel Rule flow. The standard deposit fee is 0.02% (2 basis points). Account pricing may differ; discovery shows standard pricing, while the transaction records the applied fee and net NGN credit.

Show the customer’s usable balance

deposit.success confirms that the deposit was credited. It does not guarantee that the full amount is available for trading or bank withdrawal. Refresh GET /partner/wallets/balances/overview after the deposit:

Customer action	Value to use
Trade or spend NGN	The NGN balance’s `available` amount.
View funds not yet available to spend	The NGN balance’s `locked` amount, which also includes other holds.
Withdraw to a bank or as cNGN	That rail’s withdrawal quote and `max_withdrawable_amount`.

When capacity returns

Funds awaiting conversion become available automatically when conversion completes. This can happen in parts; no conversion request is needed and no completion time is guaranteed. Customers can also request a cNGN withdrawal of funds awaiting conversion, subject to the withdrawal quote.

Track conversion progress

Use the incoming wallet transaction ID to read progress:

curl "$STABYL_BASE_URL/partner/wallets/transactions/$TRANSACTION_ID/conversion" \
  -H "X-Api-Key: $STABYL_API_KEY"

{
  "status": "success",
  "data": {
    "transaction_id": "019a0430-0000-7000-8000-000000000001",
    "revision": 3,
    "currency": "NGN",
    "settlement_rail": "CNGN",
    "initially_restricted_amount": "10000000.00",
    "released_amount": "4000000.00",
    "returned_amount": "1000000.00",
    "remaining_amount": "5000000.00",
    "status": "pending"
  }
}

Field	Meaning
`revision`	Increasing version of this transaction’s progress. Keep the highest version received.
`initially_restricted_amount`	Net deposit amount that initially awaited conversion.
`released_amount`	Cumulative amount that has become available through conversion.
`returned_amount`	Cumulative amount withdrawn as cNGN or sent to another Stabyl account while awaiting conversion.
`remaining_amount`	Amount still awaiting conversion or return. This can include a pending withdrawal; it is not a withdrawable balance.
`status`	`pending` while an amount remains; `completed` when none remains.

All amounts are NGN strings, net of the deposit fee. completed can mean funds were converted, returned, or both. A deposit available in full from the start has zero amounts and is already completed. Treat this response as progress for the original deposit, not a new credit. Refresh balances and quotes for current spending and withdrawal amounts. If the endpoint returns 404, progress is not available: check the transaction ID and deposit status rather than marking it completed. You can poll the progress endpoint or subscribe to the optional conversion.updated webhook. Add it to your endpoint’s event_types alongside deposit.action_required, deposit.success, and deposit.failed. Use POST /partner/webhooks to create an endpoint or PUT /partner/webhooks/{webhook_id} to replace its configuration, retaining all topics you need. These events require wallets:view; managing the endpoint also requires webhooks:manage. The event’s data matches the conversion progress response:

{
  "id": "30f0c0a3-99e0-56b4-89cf-5398b856da06",
  "type": "conversion.updated",
  "version": 1,
  "occurred_at": "2026-10-20T12:05:00Z",
  "data": {
    "transaction_id": "019a0430-0000-7000-8000-000000000001",
    "revision": 3,
    "currency": "NGN",
    "settlement_rail": "CNGN",
    "initially_restricted_amount": "10000000.00",
    "released_amount": "4000000.00",
    "returned_amount": "1000000.00",
    "remaining_amount": "5000000.00",
    "status": "pending"
  }
}

Follow the webhook delivery contract to verify signatures and acknowledge deliveries. Deduplicate by event id, and only replace stored progress with a higher revision for the same transaction. Events can repeat or arrive out of order, including before deposit.success. version identifies the event format; revision identifies transaction progress. Use the progress endpoint to recover missed updates. A conversion event is not another deposit and does not incur another deposit fee.

Withdraw as cNGN

Request a quote with currency: "NGN", settlement_rail: "CNGN", and a Base recipient address. Send this body to the signed POST /partner/wallets/withdrawal/quotes endpoint:

{
  "currency": "NGN",
  "settlement_rail": "CNGN",
  "items": [
    {
      "client_item_id": "cngn-withdrawal-1",
      "amount": "10000000.00",
      "destination": {
        "type": "crypto_address",
        "chain": "evm",
        "slug": "base",
        "address": "0x1111111111111111111111111111111111111111"
      }
    }
  ]
}

Replace the example address with the recipient’s address. Read status, max_withdrawable_amount, fee, debit_amount, and estimated_receive before submitting. If unavailable, use reason_code and the current maximum to help the customer choose another amount or route. To compare with a bank withdrawal, request a separate quote using a bank destination. Returning funds that are still awaiting conversion as cNGN has no withdrawal fee. The original deposit fee still applies. Other cNGN withdrawals normally cost 0.02% (2 basis points), subject to account pricing. A withdrawal that includes both types of funds is charged only on the amount already available as NGN. Always display the fee returned by the quote. For example, a customer with ₦1 million available and ₦10 million awaiting conversion can request the latter as cNGN without a withdrawal fee. A bank withdrawal can use only the available ₦1 million, allowing for fees and limits. Use fresh quotes to determine the amounts currently permitted on each rail. Submit the same withdrawal details to POST /partner/wallets/withdrawals, adding a stable idempotency_key. Follow Single withdrawals for signing and retry handling. A quote does not reserve funds or require a quote ID on submission. Track the returned withdrawal transaction ID and withdrawal events for completion; conversion progress alone does not confirm that the recipient was paid.

Get Started

Wallets

Exchange

Webhooks

WebSocket

Before you start

Receive NGN by bank transfer

Read balances and trade

Withdraw NGN to a bank

cNGN

Check conversion capacity

Receive cNGN

Show the customer’s usable balance

When capacity returns

Track conversion progress

Withdraw as cNGN

​Before you start

​Receive NGN by bank transfer

​Read balances and trade

​Withdraw NGN to a bank

​cNGN

​Check conversion capacity

​Receive cNGN

​Show the customer’s usable balance

​When capacity returns

​Track conversion progress

​Subscribe to conversion updates

​Withdraw as cNGN

Before you start

Receive NGN by bank transfer

Read balances and trade

Withdraw NGN to a bank

cNGN

Check conversion capacity

Receive cNGN

Show the customer’s usable balance

When capacity returns

Track conversion progress

Subscribe to conversion updates

Withdraw as cNGN