Skip to main content
The User Management API lets you register end-users on Strails using their Bank Verification Number (BVN), track the async KYC process through to completion, fetch full user profiles including wallet addresses and virtual accounts, control user account status, and route a user’s cNGN deliveries to an external default wallet. Because BVN verification is handled by an external identity provider, all onboarding requests are processed asynchronously - you receive a requestId immediately and poll or listen for the result.

Endpoints Overview


POST /onboarduser

Initiates onboarding for a new user by submitting their 11-digit BVN for identity verification. The request is processed asynchronously - use the returned requestId to poll /onboardstatus, or wait for the user.onboarded webhook event.

Request Parameters

string
required
The user’s 11-digit Bank Verification Number. Must be exactly 11 numeric digits and must not belong to an existing Strails user.
bvn is the only field this endpoint accepts. Identity details (names, phone, date of birth) are resolved from the BVN record, and the user’s identifier is issued by Strails and returned as userHash - do not supply your own userId.

Response

Store the requestId returned here - you will need it to check onboarding status via /onboardstatus.

Error Responses


POST /onboardstatus

Checks the current status of a pending user onboarding request using the requestId returned by /onboarduser. Poll this endpoint until status is "completed" or "failed", or handle the user.onboarded webhook event instead.

Request Parameters

string
required
The unique identifier returned by /onboarduser when the registration was initiated.

Response

Once status is "completed", use the userId from the response to call /getuserdetails and retrieve the user’s full profile.

Error Responses


POST /getuserdetails

Retrieves the full profile for a verified user, including their personal details pulled from BVN verification, all multi-chain wallet addresses provisioned by Strails, and any virtual accounts assigned to them.

Request Parameters

string
required
The unique identifier for the user, returned as userId in the /onboardstatus response once onboarding is complete.

Response

Error Responses


POST /manageuserstatus

Activates or deactivates a user account. When deactivating, you must supply a reason - this is recorded in the audit trail. Deactivated users cannot initiate transactions or receive deposits until reactivated.

Request Parameters

string
required
The unique identifier of the user whose status you want to change.
boolean
required
Set to true to activate the account or false to deactivate it.
string
A human-readable explanation for the status change. Required when active is false. Recorded in the audit log for compliance purposes.

Response

Error Responses


POST /listfintechusers

Returns a paginated list of all users belonging to your fintech, with summary wallet and virtual account information for each. Use limit and offset to page through large user sets, and status to filter by account state.

Request Parameters

number
Number of users to return per page. Accepts values between 1 and 100. Defaults to 20.
number
Number of users to skip before returning results. Use with limit to paginate through the full list. Defaults to 0.
string
Filter users by account state. Accepted values: "active", "inactive", "all". Defaults to "all".
string
Field to sort results by. Accepted values: "createdAt", "verifiedAt". Defaults to "verifiedAt".
string
Sort direction. Accepted values: "asc", "desc". Defaults to "desc".

Response

array
Array of user summary objects, one per verified user belonging to your fintech.
number
Total number of users matching the applied filter, regardless of limit and offset.
number
Total number of pages available at the current limit setting.
boolean
true if there are more users beyond the current page. Increment offset by limit to fetch the next page.
boolean
true if the current offset is greater than 0, meaning a previous page exists.

User Default Wallet

By default, cNGN disbursed for a user is delivered to the Strails-managed smart wallet provisioned during onboarding. Setting an external default wallet redirects those deliveries to an address you control on behalf of the user - useful when the user self-custodies or when your fintech settles into its own treasury addresses. The external default wallet applies to three delivery paths only:
  • cNGN disbursed from a deposit into the user’s permanent virtual account
  • cNGN disbursed through /cngnonramp
  • Tokens swept when sweepToOfframp is enabled
Deposit and funding webhooks fire as normal; the destination address in the payload reflects the external wallet.
An external default wallet is a delivery destination only. Strails holds no keys for it, so swaps, offramp, and escrow continue to operate against the user’s Strails-managed wallet and never against this address. Funds delivered here must be moved by whoever holds the keys.

POST /setuserdefaultwallet

Sets or replaces the external default wallet for a user. Calling this endpoint again with a different address overwrites the existing configuration. The address must be valid for the specified blockchain.

Request Parameters

string
required
The unique identifier of the user the wallet belongs to.
string
required
The external EVM wallet address (0x...) that should receive the user’s cNGN deliveries.
string
The EVM network the address belongs to (e.g. base, eth, bsc). Defaults to base. A network other than Base is accepted only when bridged settlement is available - see Settlement Network.
string
A human-readable name for the wallet (e.g. User payout wallet).

Response

string
Always external for wallets registered through this endpoint.
string
Whether the wallet is currently receiving deliveries. active once set.
string
Plain-language reminder of the delivery-only behaviour of external default wallets.

Error Responses


POST /getuserdefaultwallet

Retrieves the external default wallet currently configured for a user. Returns defaultWallet: null when no external wallet is set - in that case cNGN is delivered to the user’s system smart wallet.

Request Parameters

string
required
The unique identifier of the user whose default wallet you want to retrieve.

Response

object
The configured external wallet. null if the user has no external default wallet.

Error Responses


DELETE /removeuserdefaultwallet

Clears the external default wallet for a user. Once removed, cNGN deliveries revert to the user’s Strails-managed smart wallet.

Request Parameters

string
required
The unique identifier of the user whose default wallet you want to clear.

Response

Removing a default wallet only changes where future deliveries go. Balances already sent to the external address remain there.

Settlement Network

The settlement network is the chain a user’s onramp cNGN is delivered on. Unless you set one, every onramp settles on Base. You can set a network per user, set a default for all of your users, or name one on a single /cngnonramp request. It applies to cNGN disbursed from a deposit into the user’s permanent virtual account and to cNGN disbursed through /cngnonramp.

How the network is chosen

Strails uses the first of these that is set:
  1. settlementNetwork on the /cngnonramp request (that request only, optionally with a settlementAddress)
  2. The user’s settlement network, set with /setusersettlementnetwork
  3. The network the user’s external default wallet is registered for
  4. Your fintech’s default, set with /setfintechsettlementnetwork
  5. Base
Because steps 2 and 3 outrank step 4, a fintech default never overrides a user who has their own setting or an external default wallet.

Where the cNGN lands

A /cngnonramp request that sends settlementAddress is delivered to that address, whatever the user has registered. Otherwise: Off Base, cNGN is delivered only to an external default wallet registered for that network. The user’s Strails-managed smart wallet exists only on Base, so it is never a destination on another chain. On Base, cNGN goes to the user’s external default wallet if it is registered for Base, otherwise to their smart wallet. Use /listusersettlementdestinations to check where a user can be paid before you pick a network.
Strails bridges the cNGN from Base to the settlement network and absorbs the bridge fee, so the user receives the same amount they would have received on Base. A bridged deposit is reported complete only after the bridge releases the cNGN on the destination network. If a bridge transfer can’t be started (for example, the amount is above the bridged-settlement limit), the cNGN is delivered on Base instead.
Permanent virtual account deposits always settle to a registered wallet, so a user’s settlement network other than Base needs an external default wallet on that network - /setusersettlementnetwork refuses it otherwise. If a user has no address on the resolved network, a permanent virtual account deposit is held rather than paid on another network, and Strails is alerted.A /cngnonramp request that names such a network in settlementNetwork without a settlementAddress is refused when you make it. For a /cngnonramp payment where the network comes from a stored setting instead, the cNGN is delivered on Base.

Network values

base, bsc, eth, pol, trx, sol, xbn, atc, lisk, monad, arc, celo. Common names such as ethereum, polygon, bnb, and celo chain are also accepted and normalised to these codes. A network other than Base can be stored only while bridged settlement is available on Strails. Otherwise the set endpoints, and /cngnonramp, return:

POST /setusersettlementnetwork

Sets the network a user’s onramps settle on. Strails stores the network only if the user already has an address that can receive on it, so a stored setting is always one the onramp can honour.

Request Parameters

string
required
The unique identifier of the user.
string
required
The settlement network. See network values.

Response

string
The address that will receive the user’s onramp cNGN on this network.
string
Which of the user’s wallets that address is: external_default (their external default wallet) or smart_wallet (their Strails-managed smart wallet, Base only).

Error Responses


POST /getusersettlementnetwork

Returns the network a user’s onramps settle on and the address that would receive them. When the user has no setting of their own, this reports Base.

Request Parameters

string
required
The unique identifier of the user.

Response

boolean
true when the user has a settlement network set with /setusersettlementnetwork. false means the user has no setting and Base is reported.
string
The address that would receive on settlementNetwork, or null if the user has none there.
This reports the user’s own setting only. When isExplicit is false, an onramp can still settle elsewhere through the user’s external default wallet network or your fintech default - see How the network is chosen.

POST /removeusersettlementnetwork

Clears a user’s settlement network setting. Onramps for the user then follow the rest of the precedence order.

Request Parameters

string
required
The unique identifier of the user.

Response


POST /listusersettlementdestinations

Lists every supported network and whether the user can be paid on it. Call this before setting a user’s network or naming one on /cngnonramp - a network with canSettle: false would be refused or held.

Request Parameters

string
required
The unique identifier of the user.

Response

array
One entry per supported network, with network, networkName, canSettle, destinationAddress, destinationSource (external_default, smart_wallet, or null), and requiresBridge (true for every network except Base).
array
The networks where canSettle is true.

POST /setfintechsettlementnetwork

Sets the default settlement network for all of your users. It is a default, not an override: a user’s own setting and their external default wallet network both take precedence.
Strails can’t check this setting against each user’s wallets. A user with no address on the chosen network has their permanent virtual account deposits held rather than paid elsewhere, so register an external default wallet on that network for those users.

Request Parameters

string
required
The default settlement network. See network values.

Response

Error Responses


POST /getfintechsettlementnetwork

Returns your fintech’s default settlement network. When none is set, this reports Base.

Response

boolean
true when a default is set. false means none is set and Base is reported.

POST /removefintechsettlementnetwork

Clears your fintech’s default settlement network. Users without their own setting or an external default wallet network settle on Base again.

Response