Wallet Management API: Balances & External Wallets

The Wallet Management API gives you full control over the three wallet types in Strails. Your Smart Wallet is a contract-based EVM wallet that holds cNGN, USDC, and USDT and can be fintech- or Strails-controlled. Your MPC Vault provides multi-party computation custody for USDC and USDT. External Wallets are third-party addresses - cold storage, hot wallets, or custodial accounts - that you register on the platform for withdrawals and storage.

Endpoints Overview

Section	Endpoint	Method	Description
Retrieve the Fintech Wallet	`/getfintechwallet`	GET	Retrieve your Smart Wallet details and all registered External Wallets
Add an External Wallet	`/addexternalwallet`	POST	Register a new external wallet on your fintech account
Update External Wallet Status	`/updateexternalwalletstatus`	PUT	Activate or deactivate a registered external wallet
Remove an External Wallet	`/removeexternalwallet`	DELETE	Remove an external wallet from your fintech account
Retrieve User Wallets	`/listuserwallets`	POST	Retrieve all wallets for a specific end-user, including balances
Migrate User Wallets	`/migrateuserwallets`	POST	Provision default wallets for users created before automated wallet provisioning
Fintech System Wallet Balance	`/balance/multi`	GET	Get your fintech Smart Wallet balance across EVM networks
Balance for a Specific Address	`/balance/address`	POST	Get token balance for any specific EVM address across networks
End User Balance	`/balance/user/:userId`	GET	Get an end-user’s wallet balances

Retrieve the Fintech Wallet

GET /getfintechwallet Returns your fintech’s Smart Wallet configuration and the complete list of registered External Wallets.

curl --request GET \
  --url "https://api.strails.io/v1/getfintechwallet" \
  --header "x-api-key: YOUR_API_KEY"

object

Show data fields

string

Unique identifier of your fintech account.

string

Registered name of your fintech.

object

Show smartWallet fields

string

On-chain address of the deployed Smart Wallet contract.

string

EOA address that controls the Smart Wallet.

boolean

Whether the contract has been deployed on-chain.

string

ISO 8601 timestamp of wallet creation.

string

Version identifier used during contract deployment (e.g. v2).

string

Transaction hash of the deployment transaction.

array

List of registered external wallets. Each entry contains address, label, blockchain, type, addedAt, addedBy, status, isDefault, and purpose.

number

Total number of end-users associated with your fintech.

string

ISO 8601 timestamp when the fintech account was created.

string

ISO 8601 timestamp of the last update.

Response

{
  "status": "success",
  "response_code": "00",
  "message": "Fintech wallet retrieved successfully",
  "data": {
    "fintechId": "fintech_abc123",
    "fintechName": "Example Fintech Ltd",
    "smartWallet": {
      "address": "0x69E4eA33BF7E2f6bAE7F1DEF247534C0aD3515C3",
      "owner": "0x684f5f118ed7d0e00b1c0a27dcdce6e37cf652e1",
      "deployed": true,
      "createdAt": "2026-04-02T08:45:02.007Z",
      "saltVersion": "v2",
      "deploymentTxHash": "0x3cd779012c51172781202e9fff8eff749fda01f8f9e530bd0fb3a0dbab68ca46"
    },
    "externalWallets": [
      {
        "address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
        "label": "Cold Storage Wallet",
        "blockchain": "base",
        "type": "cold",
        "addedAt": "2026-02-09T11:44:38.960Z",
        "addedBy": "4e769009-7a30-42df-89eb-7234a29e53c2",
        "status": "active",
        "isDefault": false,
        "purpose": "Long-term storage"
      }
    ],
    "totalUsers": 150,
    "createdAt": "2026-01-15T15:03:03.977Z",
    "updatedAt": "2026-04-29T13:20:36.574Z"
  }
}

Add an External Wallet

POST /addexternalwallet Registers an external wallet address on your fintech account. External wallets cannot be used for escrow operations. The address must be valid for the specified blockchain before it is accepted.

This endpoint registers wallets at the fintech level. To nominate an external delivery destination for an individual end-user’s cNGN, use Set User Default Wallet instead.

curl --request POST \
  --url "https://api.strails.io/v1/addexternalwallet" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "0xAbCd1234AbCd1234AbCd1234AbCd1234AbCd1234",
    "label": "Hot Wallet - Operations",
    "blockchain": "base",
    "type": "hot",
    "purpose": "Daily operations and withdrawals",
    "isDefault": true,
    "metadata": {
      "custodian": "Internal",
      "location": "AWS KMS",
      "backupExists": true
    }
  }'

string

required

The wallet address to register on the platform.

string

required

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

string

required

The wallet custody type. One of hot, cold, custodial, or other.

string

A human-readable name for easy identification (e.g. Cold Storage Wallet).

string

The intended use of this wallet (e.g. Daily operations and withdrawals).

boolean

Whether to set this wallet as your fintech’s default external wallet. Defaults to false. This does not affect end-user deliveries - see User Default Wallet.

object

Additional custody information.

Show metadata fields

string

Entity responsible for wallet custody (e.g. Internal, Fireblocks).

string

Key or wallet storage location (e.g. AWS KMS, HSM).

boolean

Whether a secure backup of the wallet key exists.

Response

{
  "status": "success",
  "response_code": "00",
  "message": "External wallet added successfully",
  "data": {
    "wallet": {
      "address": "0xAbCd1234AbCd1234AbCd1234AbCd1234AbCd1234",
      "status": "active",
      "type": "hot",
      "blockchain": "base"
    }
  }
}

Error responses

Invalid address format

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

Wallet already registered

{
  "status": "error",
  "response_code": "01",
  "message": "Wallet already exists",
  "error": "This wallet address is already registered"
}

Update External Wallet Status

PUT /updateexternalwalletstatus Activates or deactivates a registered external wallet. Inactive wallets cannot receive transfers from the platform.

curl --request PUT \
  --url "https://api.strails.io/v1/updateexternalwalletstatus" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "status": "inactive"
  }'

string

required

The wallet address to update.

string

required

The new status for the wallet. Must be either active or inactive.

Response

{
  "status": "success",
  "response_code": "00",
  "message": "External wallet status updated successfully",
  "data": {
    "address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "status": "inactive"
  }
}

Error responses

Wallet not found

{
  "status": "error",
  "response_code": "02",
  "message": "Wallet not found",
  "error": "No external wallet found with the provided address"
}

Invalid status value

{
  "status": "error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Status must be 'active' or 'inactive'"
}

Remove an External Wallet

DELETE /removeexternalwallet Permanently removes an external wallet from your fintech account. This action cannot be undone.

curl --request DELETE \
  --url "https://api.strails.io/v1/removeexternalwallet" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
  }'

string

required

The wallet address to remove from your fintech account.

Response

{
  "status": "success",
  "response_code": "00",
  "message": "External wallet removed successfully",
  "data": {
    "address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
  }
}

Error response

Wallet not found

{
  "status": "error",
  "response_code": "02",
  "message": "Wallet not found",
  "error": "No external wallet found with the provided address"
}

Retrieve User Wallets

POST /listuserwallets Returns all wallets provisioned for a specific end-user, including their current token balances. Each user has a primary EVM Smart Wallet on Base plus multi-chain wallets on Bantu and Solana.

curl --request POST \
  --url "https://api.strails.io/v1/listuserwallets" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "userId": "user_uniqueID"
  }'

string

required

The unique identifier (hash or UUID) of the end-user.

object

Show data fields

array

Array of wallet objects. Each wallet contains walletAddress, status, createdAt, owner, tokenBuy, blockchain, and balances.

On this endpoint status carries the wallet type - smart_wallet or multi_chain - not an active/inactive state. Every user has a primary EVM Smart Wallet on Base plus multi-chain wallets on Bantu and Solana.

number

Total number of wallets returned.

string

The user ID used to retrieve the wallets.

string

API version string.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "User wallets retrieved successfully",
  "data": {
    "wallets": [
      {
        "walletAddress": "sample_0x23341e77675b4513bEbA945B05afb2",
        "status": "smart_wallet",
        "createdAt": "2026-06-03T10:46:37.494Z",
        "owner": "0x684f5f118ed7d0e00b1c0a27dcdce6e37cf652e1",
        "tokenBuy": "CNGN",
        "blockchain": "base",
        "balances": {
          "CNGN": { "balance": "0.00" },
          "USDC": { "balance": "0.00" },
          "USDT": { "balance": "0.00" }
        }
      },
      {
        "walletAddress": "sample_GAFIWE3JABCQ5LTOUO4BPFQ3QRBEHTVOKETYLB",
        "status": "multi_chain",
        "createdAt": "2026-06-03T10:46:37.695Z",
        "owner": "strails-managed",
        "tokenBuy": "CNGN",
        "blockchain": "bantu",
        "balances": {
          "cngn": null,
          "tokenBuy": null
        }
      },
      {
        "walletAddress": "sample_4ZpwXDXZUPiyi2NNTtMFZyMojFZrYFs",
        "status": "multi_chain",
        "createdAt": "2026-06-03T10:46:38.324Z",
        "owner": "strails-managed",
        "tokenBuy": "CNGN",
        "blockchain": "solana",
        "balances": {
          "cngn": null,
          "tokenBuy": null
        }
      }
    ],
    "count": 5,
    "userId": "user_uniqueID",
    "version": "1.0.0"
  }
}

Error response

User not found

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

Migrate User Wallets

POST /migrateuserwallets Provisions default wallets for end-users who were created before automated wallet provisioning was enabled. Use this endpoint to bring legacy users up to the current wallet structure.

Ensure all funds have been transferred out of any existing legacy wallets before calling this endpoint. Migration may result in new wallet addresses being issued for affected users.

curl --request POST \
  --url "https://api.strails.io/v1/migrateuserwallets" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "userId": ["userId_abc123", "userId_def456"],
    "force": true
  }'

array

required

A list of user identifiers (hashes or UUIDs) to migrate. You can pass multiple user IDs in a single call.

boolean

When true, the migration proceeds even if a user already has partial wallet data. Defaults to false.

object

Show data fields

string

Unique identifier for this migration batch.

number

Total number of user IDs submitted.

number

Number of wallets newly created.

number

Number of wallets migrated from a legacy structure.

number

Number of users skipped (wallet already exists).

number

Number of users for whom wallet creation failed.

array

Per-user migration outcome. Each entry includes userId, status, walletAddress, deployed, and optionally reason.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Wallet migration completed",
  "data": {
    "requestId": "migrate_fintech123_1706457600000",
    "totalProcessed": 3,
    "created": 2,
    "migrated": 0,
    "skipped": 1,
    "failed": 0,
    "results": [
      { "userId": "abc123", "status": "created", "walletAddress": "0x...", "deployed": true },
      { "userId": "def456", "status": "created", "walletAddress": "0x...", "deployed": true },
      { "userId": "ghi789", "status": "skipped", "walletAddress": "0x...", "reason": "Wallet already exists" }
    ]
  }
}

Fintech System Wallet Balance

GET /balance/multi Returns your fintech’s own Smart Wallet token balance across one or more EVM networks. Use the networks query parameter to limit the check to specific chains.

curl --request GET \
  --url "https://api.strails.io/v1/balance/multi?token=CNGN&networks=base,eth,bsc" \
  --header "x-api-key: YOUR_API_KEY"

string

The token ticker to query (e.g. CNGN, USDC, USDT). Defaults to CNGN.

string

Comma-separated list of EVM network keys to check (e.g. base,eth,bsc). Defaults to all supported EVM networks.

object

Show data fields

string

The token that was queried.

string

Your Smart Wallet address.

string

Aggregate balance across all checked networks.

boolean

Whether the Base network holds a non-zero balance.

boolean

Whether any non-Base network holds a non-zero balance.

string

Balance on the Base network.

string

Combined balance on all non-Base networks.

boolean

Whether a cross-chain bridge is needed to consolidate funds.

array

Per-network balance entries. Each entry contains network and balance, plus an optional error if the RPC call failed.

array

Subset of networkBalances showing only networks with a non-zero balance.

string

ISO 8601 timestamp of when the balance check was performed.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Multi-network balance retrieved",
  "data": {
    "token": "CNGN",
    "walletAddress": "0x25AC115350Af0a6B53475d2e667898D7267C78B1",
    "totalBalance": "1299.974550",
    "hasBaseNetworkFunds": true,
    "hasCrossNetworkFunds": false,
    "baseNetworkBalance": "1299.974550",
    "crossNetworkBalance": "0.000000",
    "bridgingRequired": false,
    "networkBalances": [
      { "network": "base", "balance": "1299.974550" },
      { "network": "eth", "balance": "0", "error": "All RPC endpoints failed for eth" }
    ],
    "walletsWithFunds": [
      { "network": "base", "balance": "1299.974550" }
    ],
    "checkedAt": "2026-07-22T09:12:49.339Z"
  }
}

Balance for a Specific Address

POST /balance/address Returns the token balance for any arbitrary EVM address across one or more networks. Useful for checking balances of addresses that are not necessarily your Smart Wallet.

curl --request POST \
  --url "https://api.strails.io/v1/balance/address" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "0xF223A5962c3901159465A0511Db4a74FFaCF3f8A",
    "token": "CNGN",
    "networks": ["base", "eth"]
  }'

string

required

The EVM wallet address to query.

string

The token ticker to query (e.g. CNGN, USDC, USDT). Defaults to CNGN.

array

Array of EVM network keys to check (e.g. ["base", "eth", "bsc"]). Defaults to all supported EVM networks.

object

Show data fields

string

The token that was queried.

string

The address that was queried.

string

Aggregate balance across all checked networks.

array

Per-network balance entries. Each entry contains network and balance, plus an optional error if the RPC call failed.

string

ISO 8601 timestamp of when the balance check was performed.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "Address balance retrieved",
  "data": {
    "token": "CNGN",
    "address": "0xF223A5962c3901159465A0511Db4a74FFaCF3f8A",
    "totalBalance": "326.695000",
    "networkBalances": [
      { "network": "base", "balance": "326.695000" },
      { "network": "eth", "balance": "0", "error": "All RPC endpoints failed for eth" }
    ],
    "checkedAt": "2026-07-22T09:01:29.058Z"
  }
}

End-User Balance

GET /balance/user/:userId Returns the token balances across all wallets provisioned for a specific end-user. Balances are resolved from the user’s Smart Wallet and all additional network addresses associated with the user.

curl --request GET \
  --url "https://api.strails.io/v1/balance/user/abc123?token=CNGN" \
  --header "x-api-key: YOUR_API_KEY"

string

required

The unique identifier of the end-user whose balance you want to retrieve.

string

The token ticker to query (e.g. CNGN, USDC, USDT). Defaults to CNGN.

object

Show data fields

string

The user ID that was queried.

string

The token that was queried.

string

Aggregate balance across all the user’s wallets.

array

Per-network entries containing network, walletAddress, and balance, plus an optional error if the RPC call failed.

string

ISO 8601 timestamp of when the balance check was performed.

Response

{
  "status": "Success",
  "response_code": "00",
  "message": "User balance retrieved",
  "data": {
    "userId": "abc123",
    "token": "CNGN",
    "totalBalance": "326.695000",
    "networkBalances": [
      { "network": "base", "walletAddress": "0x...", "balance": "326.695000" },
      { "network": "eth", "walletAddress": "0x...", "balance": "0", "error": "All RPC endpoints failed for eth" }
    ],
    "checkedAt": "2026-07-22T09:01:29.058Z"
  }
}

Overview

Core APIs

FX & Trading

Configuration

Wallet Management API: Balances & External Wallets

Endpoints Overview

Retrieve the Fintech Wallet

Add an External Wallet

Update External Wallet Status

Remove an External Wallet

Retrieve User Wallets

Migrate User Wallets

Fintech System Wallet Balance

Balance for a Specific Address

End-User Balance

​Endpoints Overview

​Retrieve the Fintech Wallet

​Add an External Wallet

​Update External Wallet Status

​Remove an External Wallet

​Retrieve User Wallets

​Migrate User Wallets

​Fintech System Wallet Balance

​Balance for a Specific Address

​End-User Balance

Endpoints Overview

Retrieve the Fintech Wallet

Add an External Wallet

Update External Wallet Status

Remove an External Wallet

Retrieve User Wallets

Migrate User Wallets

Fintech System Wallet Balance

Balance for a Specific Address

End-User Balance