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 returnedrequestId 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 therequestId 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
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 areason - 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. Uselimit 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
sweepToOfframpis enabled
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. ReturnsdefaultWallet: 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:settlementNetworkon the/cngnonramprequest (that request only, optionally with asettlementAddress)- The user’s settlement network, set with
/setusersettlementnetwork - The network the user’s external default wallet is registered for
- Your fintech’s default, set with
/setfintechsettlementnetwork - Base
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.
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.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.