Wallet Management API

The Wallet Management API allows fintechs to manage their wallets:

Smart Wallet — Contract-based wallet for cNGN, USDC, USDT. Can be fintech or Strails-controlled.
MPC Vault — Multi-party computation wallet for secure custody of USDC/USDT.
External Wallets — User-registered wallets for withdrawals and storage.

Wallet Management API — Endpoints Overview

Section	Endpoint	Method	Description
Get Fintech Wallet	`/getfintechwallet`	GET	Retrieve fintech wallet information including the system (MPC) wallet and external wallets.
Add External Wallet	`/addexternalwallet`	POST	Add an external wallet to your fintech account. Not usable for escrow.
Update External Wallet	`/updateexternalwalletstatus`	PUT	Activate or deactivate an external wallet.
Remove External Wallet	`/removeexternalwallet`	DELETE	Remove an external wallet from the fintech account.
Get User Wallets	`/listuserwallets`	POST	Retrieve all wallets associated with a specific user, including balances.
Migrate User Wallets	`/migrateuserwallets`	POST	Create default wallets for existing users created before wallet provisioning was automated.

Retrieve the fintech smart wallet and all external wallets

Request (Fintech Wallet)
Response (Fintech Wallet)

GET {{BASE_URL}}/getfintechwallet

{
  "responseCode": "00",
  "responseMessage": "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",
        "previousAddress": "0x69E4eA33BF7E2f6bAE7F1DEF247534C0aD3515C3",
        "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

Request (Add Wallet)
Body (Add Wallet)
Response (Add Wallet)
Error (Add Wallet)

POST {{BASE_URL}}/addexternalwallet

{
  "address": "0x-WalletAddress",
  "label": "Hot Wallet - Operations",
  "blockchain": "base",
  "type": "hot",
  "purpose": "Daily operations and withdrawals",
  "isDefault": true,
  "metadata": {
    "custodian": "Internal",
    "location": "AWS KMS",
    "backupExists": true
  }
}

Parameters

Parameter	Type	Required	Description
`address`	string	Yes	Wallet address to be added to the platform
`label`	string	No	Human-readable name for easy identification
`blockchain`	string	Yes	Blockchain network the wallet belongs to (e.g. `base`)
`type`	enum	Yes	Wallet type (`hot`, `cold`, `custodial` or `other`)
`purpose`	string	No	Intended use of the wallet (e.g. operations, withdrawals)
`isDefault`	boolean	No	true or false (defaults to false)
`metadata`	object	No	Additional wallet information and custody details

`metadata` Object

Field	Type	Required	Description
`custodian`	string	No	Entity responsible for wallet custody
`location`	string	No	Key or wallet storage location (e.g. KMS, HSM)
`backupExists`	boolean	No	Indicates whether a secure backup exists

{
  "responseCode": "00",
  "responseMessage": "External wallet added successfully",
  "data": {
    "wallet": {
      "address": "wallet-address",
      "status": "active",
      "type": "hot",
      "blockchain": "base"
    }
  }
}

{
  "responseCode": "01",
  "responseMessage": "Validation error",
  "error": "Invalid wallet address format"
}

{
  "responseCode": "01",
  "responseMessage": "Wallet already exists",
  "error": "This wallet address is already registered"
}

Update external wallet status

Request (Update)
Body (Update)
Response (Update)
Error (Update)

PUT {{BASE_URL}}/updateexternalwalletstatus

{
  "address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
  "status": "inactive"
}

Parameters

Parameter	Type	Required	Description
`address`	string	Yes	Wallet address to be updated
`status`	string	Yes	New wallet status (`active` or `inactive`)

{
  "responseCode": "00",
  "responseMessage": "External wallet status updated successfully",
  "data": {
    "address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "status": "inactive"
  }
}

{
  "responseCode": "02",
  "responseMessage": "Wallet not found",
  "error": "No external wallet found with the provided address"
}

{
  "responseCode": "01",
  "responseMessage": "Validation error",
  "error": "Status must be 'active' or 'inactive'"
}

Remove an external wallet

Request (Remove)
Body (Remove)
Response (Remove)
Error (Remove)

DELETE {{BASE_URL}}/removeexternalwallet

{
  "address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
}

{
  "responseCode": "00",
  "responseMessage": "External wallet removed successfully",
  "data": {
    "address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
  }
}

{
  "responseCode": "02",
  "responseMessage": "Wallet not found",
  "error": "No external wallet found with the provided address"
}

Retrieve user wallets

Request (User Wallets)
Body (User Wallets)
Response (User Wallets)
Error (User Wallets)

POST {{BASE_URL}}/listuserwallets

{
  "userId": "user_uniqueID"
}

{
  "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": "strails_internal_0x684f5f118ed7d0e00b1c0",
                "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": "system_controlled",
                "tokenBuy": "CNGN",
                "blockchain": "bantu",
                "balances": {
                    "cngn": null,
                    "tokenBuy": null
                }
            },
            {
                "walletAddress": "sample_4ZpwXDXZUPiyi2NNTtMFZyMojFZrYFs",
                "status": "multi_chain",
                "createdAt": "2026-06-03T10:46:38.324Z",
                "owner": "system_controlled",
                "tokenBuy": "CNGN",
                "blockchain": "solana",
                "balances": {
                     "cngn": null,
                    "tokenBuy": null
                }
            }
    ],
    "count": 5,
    "userId": "user_uniqueID",
    "version": "1.0.0"
  }
}

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

Migrate user wallets

Ensure funds are transferred out of the existing wallet before calling this endpoint.

Request (Migrate)
Body (Migrate)
Response (Migrate)

POST {{BASE_URL}}/migrateuserwallets

{
  "userId": ["userId", "userId1"],
  "force": true
}

Parameters

Parameter	Type	Required	Description
`userId`	array	Yes	List of user identifiers (hash/UUID) to be migrated
`force`	boolean	No	Force migration even if the user already exists or has partial data

{
  "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" }
    ]
  }
}

​Wallet Management API

​Wallet Management API — Endpoints Overview

​Retrieve the fintech smart wallet and all external wallets

​Add an external wallet

​Parameters

​metadata Object

​Update external wallet status

​Parameters

​Remove an external wallet

​Retrieve user wallets

​Migrate user wallets

​Parameters

Wallet Management API

Wallet Management API — Endpoints Overview

Retrieve the fintech smart wallet and all external wallets

Add an external wallet

Parameters

`metadata` Object

Update external wallet status

Parameters

Remove an external wallet

Retrieve user wallets

Migrate user wallets

Parameters