User Management API: BVN Onboarding, KYC & Account Control

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

Section	Endpoint	Method	Description
Onboard User	`/onboarduser`	POST	Initiate BVN-based KYC and create a new user account.
Onboard Status	`/onboardstatus`	POST	Check the current status of a pending onboarding request.
Get User Details	`/getuserdetails`	POST	Retrieve a user’s full profile, wallets, and virtual accounts.
Manage User Status	`/manageuserstatus`	POST	Activate or deactivate a user account with an audit reason.
List Fintech Users	`/listfintechusers`	POST	Retrieve a paginated list of all users belonging to your fintech.
Set User Default Wallet	`/setuserdefaultwallet`	POST	Route a user’s cNGN deliveries to an external wallet address.
Get User Default Wallet	`/getuserdefaultwallet`	POST	Retrieve the external default wallet currently set for a user.
Remove User Default Wallet	`/removeuserdefaultwallet`	DELETE	Clear the external default wallet and revert to the system smart wallet.

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.

curl -X POST https://api.strails.io/v1/onboarduser \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -d '{
    "bvn": "12345678901"
  }'

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

{
  "status": "Success",
  "response_code": "00",
  "message": "User registration initiated",
  "data": {
    "requestId": "7898f29e-10a6-4b2b-9496-f4ee50549fd4",
    "status": "processing",
    "userHash": "user_uniqueID",
    "message": "User registration request has been submitted for processing",
    "estimatedCompletionTime": "2-5 minutes"
  }
}

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

Error Responses

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Invalid BVN format. BVN must be 11 digits"
}

{
  "status": "Error",
  "response_code": "01",
  "message": "User already exists",
  "error": "A user with this BVN is already registered"
}

{
  "status": "Error",
  "response_code": "05",
  "message": "BVN verification failed",
  "error": "Unable to verify BVN with identity provider"
}

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.

curl -X POST https://api.strails.io/v1/onboardstatus \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -d '{
    "requestId": "7898f29e-10a6-4b2b-9496-f4ee50549fd4"
  }'

Request Parameters

string

required

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

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "User registration completed successfully",
  "data": {
    "type": "user_registration",
    "userId": "user_uniqueID",
    "status": "completed",
    "createdAt": "2026-01-18T19:33:39.945Z",
    "message": "User registration completed successfully"
  }
}

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

Error Responses

{
  "status": "Error",
  "response_code": "02",
  "message": "Request not found",
  "error": "No onboarding request found with the provided requestId"
}

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.

curl -X POST https://api.strails.io/v1/getuserdetails \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -d '{
    "userId": "user_uniqueID"
  }'

Request Parameters

string

required

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

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "User details retrieved successfully",
  "data": {
    "userId": "user_uniqueID",
    "isActive": true,
    "personalDetails": {
      "firstName": "John",
      "middleName": "Doe",
      "lastName": "Smith"
    },
    "walletDetails": {
      "evmWallet": "0x2KCC051A79dE65d7068542cB5D9D03754cc22F60",
      "bantuWallet": "GB63QBTTWQXRO5BNO3Z4RRAGBPQFDGAGWNHKHTGSJOZF3V2NKG7V4XTY",
      "solanaWallet": "HaXjvARhAxjKZRojmer86G31kXm52Nd4FZP4jrg4H2hf",
      "walletCreatedAt": "2025-08-20T10:15:00.000Z"
    },
    "virtualAccounts": [
      {
        "accountNumber": "1234567890",
        "accountName": "John Doe",
        "bankName": "Optimus Bank",
        "bankCode": "0000",
        "provider": "novac",
        "accountType": "user_permanent",
        "reference": "userId",
        "createdAt": "2026-05-29T12:42:45.034Z"
      }
    ]
  }
}

Error Responses

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

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.

curl -X POST https://api.strails.io/v1/manageuserstatus \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -d '{
    "userId": "user_uniqueID",
    "active": false,
    "reason": "Account suspended by customer request"
  }'

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

{
  "status": "Success",
  "response_code": "00",
  "message": "User deactivated successfully",
  "data": {
    "userId": "user_uniqueID",
    "active": false,
    "changedAt": "2025-12-16T09:17:33.658Z"
  }
}

Error Responses

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

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Reason is required when deactivating a user"
}

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.

curl -X POST https://api.strails.io/v1/listfintechusers \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -d '{
    "limit": 20,
    "offset": 0,
    "status": "all",
    "orderBy": "verifiedAt",
    "orderDirection": "desc"
  }'

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

{
  "status": "Success",
  "response_code": "00",
  "message": "Users retrieved successfully",
  "data": {
    "users": [
      {
        "userId": "abc123...",
        "firstName": "John",
        "lastName": "Doe",
        "isActive": true,
        "hasWallet": true,
        "wallets": {
          "evm": "0x...",
          "solana": null,
          "bantu": null
        },
        "virtualAccount": {
          "accountNumber": "1234567890",
          "accountName": "John Doe",
          "bankName": "Fidelity Bank",
          "bankCode": "070",
          "provider": "redbiller"
        },
        "verifiedAt": "2026-05-10T12:00:00.000Z",
        "createdAt": "2026-05-10T12:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 150,
      "limit": 20,
      "offset": 0,
      "currentPage": 1,
      "totalPages": 8,
      "hasNextPage": true,
      "hasPreviousPage": false
    }
  }
}

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.

curl -X POST https://api.strails.io/v1/setuserdefaultwallet \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -d '{
    "userId": "user_uniqueID",
    "address": "0xc5422E03B8250917023501E4697c738E7427b540",
    "blockchain": "base",
    "label": "User payout wallet"
  }'

Request Parameters

string

required

The unique identifier of the user the wallet belongs to.

string

required

The external wallet address that should receive the user’s cNGN deliveries.

string

required

The blockchain network the address belongs to (e.g. base, eth, bsc).

string

A human-readable name for the wallet (e.g. User payout wallet).

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Default wallet set successfully",
  "data": {
    "userId": "user_uniqueID",
    "defaultWallet": {
      "address": "0x52428ccd2529ff22d03c72a60aec877ca0a69308",
      "blockchain": "base",
      "type": "external",
      "status": "active",
      "label": "User payout wallet"
    },
    "note": "cNGN will be delivered to this wallet. Platform swaps/offramp do not operate on it."
  }
}

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

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

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Invalid wallet address for the specified blockchain"
}

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.

curl -X POST https://api.strails.io/v1/getuserdefaultwallet \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -d '{
    "userId": "user_uniqueID"
  }'

Request Parameters

string

required

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

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Default wallet retrieved successfully",
  "data": {
    "userId": "user_uniqueID",
    "defaultWallet": null
  }
}

object

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

Error Responses

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

DELETE /removeuserdefaultwallet

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

curl -X DELETE https://api.strails.io/v1/removeuserdefaultwallet \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -d '{
    "userId": "user_uniqueID"
  }'

Request Parameters

string

required

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

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Default wallet removed successfully",
  "data": {
    "userId": "user_uniqueID",
    "defaultWallet": null,
    "note": "Funding reverts to the user's system smart wallet."
  }
}

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

Overview

Core APIs

FX & Trading

Configuration

User Management API: BVN Onboarding, KYC & Account Control

Endpoints Overview

POST /onboarduser

Request Parameters

Response

Error Responses

POST /onboardstatus

Request Parameters

Response

Error Responses

POST /getuserdetails

Request Parameters

Response

Error Responses

POST /manageuserstatus

Request Parameters

Response

Error Responses

POST /listfintechusers

Request Parameters

Response

User Default Wallet

POST /setuserdefaultwallet

Request Parameters

Response

Error Responses

POST /getuserdefaultwallet

Request Parameters

Response

Error Responses

DELETE /removeuserdefaultwallet

Request Parameters

Response

​Endpoints Overview

​POST /onboarduser

​Request Parameters

​Response

​Error Responses

​POST /onboardstatus

​Request Parameters

​Response

​Error Responses

​POST /getuserdetails

​Request Parameters

​Response

​Error Responses

​POST /manageuserstatus

​Request Parameters

​Response

​Error Responses

​POST /listfintechusers

​Request Parameters

​Response

​User Default Wallet

​POST /setuserdefaultwallet

​Request Parameters

​Response

​Error Responses

​POST /getuserdefaultwallet

​Request Parameters

​Response

​Error Responses

​DELETE /removeuserdefaultwallet

​Request Parameters

​Response

Endpoints Overview

POST /onboarduser

Request Parameters

Response

Error Responses

POST /onboardstatus

Request Parameters

Response

Error Responses

POST /getuserdetails

Request Parameters

Response

Error Responses

POST /manageuserstatus

Request Parameters

Response

Error Responses

POST /listfintechusers

Request Parameters

Response

User Default Wallet

POST /setuserdefaultwallet

Request Parameters

Response

Error Responses

POST /getuserdefaultwallet

Request Parameters

Response

Error Responses

DELETE /removeuserdefaultwallet

Request Parameters

Response