Wallets API

The Wallets API allows you to retrieve wallet information for customers, including balances, currency details, and status. Wallets are multi-currency accounts that hold funds in different currencies.

Get Wallets

Retrieve all wallets for the authenticated business customer. Returns an array of all wallets with their balances, currency information, and status. Only includes wallets with active currencies.

Endpoint

Client API Endpoint: GET /api/v1/client/wallets

Authentication

This endpoint requires HMAC authentication (Business API Key). Include your API key and signature in the request headers:

http
x-api-key: <your-api-key>x-timestamp: <RFC3339-timestamp>x-signature: <HMAC-signature>

Note: For HMAC authentication details, see the .

Query Parameters

ParameterTypeRequiredDescription
default_currencystringNoPreferred currency code (ISO 4217, e.g., USD, CAD). If not provided, uses user's preferred currency from profile or defaults to CAD.

Success Response (200 OK)

json
{  "wallets": [    {      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",      "user_id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210",      "currency": "USD",      "currency_name": "US Dollar",      "ledger_balance": "12345.67",      "available_balance": "12345.67",      "status": "active",      "created_at": "2024-03-15T10:30:00Z",      "updated_at": "2025-05-30T18:35:49Z",      "bank_account_details": [],      "user_first_name": "John",      "user_last_name": "Doe",      "user_email": "john.doe@example.com",      "user_type": "INDIVIDUAL"    },    {      "id": "b2c3d4e5-f6a7-8901-2345-678901bcdefg",      "user_id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210",      "currency": "NGN",      "currency_name": "Nigerian Naira",      "ledger_balance": "500000.00",      "available_balance": "450000.00",      "status": "active",      "created_at": "2024-03-15T10:30:00Z",      "updated_at": "2025-05-30T18:35:49Z",      "bank_account_details": [],      "user_first_name": "John",      "user_last_name": "Doe",      "user_email": "john.doe@example.com",      "user_type": "INDIVIDUAL"    }  ]}

Response Fields

FieldTypeDescription
walletsarrayArray of wallet objects. Only includes wallets with active currencies. Each wallet contains:
wallets[].idstring (UUID)Unique wallet identifier
wallets[].user_idstring (UUID)Customer user ID who owns the wallet
wallets[].currencystringCurrency code (ISO 4217, e.g., "USD", "EUR", "NGN")
wallets[].currency_namestringFull name of the currency
wallets[].ledger_balancestringTotal balance in the wallet (decimal string)
wallets[].available_balancestringAvailable balance after holds (decimal string)
wallets[].statusstringWallet status: active, inactive, suspended
wallets[].created_atstring (ISO 8601)Wallet creation timestamp
wallets[].updated_atstring (ISO 8601)Last update timestamp
wallets[].bank_account_detailsarrayVirtual bank account details (if applicable)
wallets[].user_first_namestringCustomer's first name
wallets[].user_last_namestringCustomer's last name
wallets[].user_emailstringCustomer's email address
wallets[].user_typestringCustomer type: INDIVIDUAL or BUSINESS

Error Responses

Status CodeDescription
401Unauthorized - Invalid or missing API key or signature
500Internal server error

Example: cURL

bash
curl -X GET "https://api.sznd.app/api/v1/client/wallets" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here"

Example: HTTP Request

http
GET /api/v1/client/wallets HTTP/1.1Host: api.sznd.appx-api-key: your_api_key_herex-timestamp: 2025-01-30T12:20:15Zx-signature: generated_signature_hereContent-Type: application/json

Get Wallet by ID

Retrieve detailed information about a specific wallet, including balance, currency, and status.

Endpoint

Client API Endpoint: GET /api/v1/client/wallets/{id}

Authentication

This endpoint requires HMAC authentication (Business API Key). Include your API key and signature in the request headers:

http
x-api-key: <your-api-key>x-timestamp: <RFC3339-timestamp>x-signature: <HMAC-signature>

Note: For HMAC authentication details, see the .

Path Parameters

ParameterTypeDescription
idstring (UUID)Unique wallet identifier

Success Response (200 OK)

json
{  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",  "user_id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210",  "currency": "USD",  "currency_name": "US Dollar",  "ledger_balance": "12345.67",  "available_balance": "12345.67",  "status": "active",  "created_at": "2024-03-15T10:30:00Z",  "updated_at": "2025-05-30T18:35:49Z",  "bank_account_details": [],  "user_first_name": "John",  "user_last_name": "Doe",  "user_email": "john.doe@example.com",  "user_type": "INDIVIDUAL"}

Response Fields

FieldTypeDescription
idstring (UUID)Unique wallet identifier
user_idstring (UUID)Customer user ID who owns the wallet
currencystringCurrency code (ISO 4217, e.g., "USD", "EUR", "NGN")
currency_namestringFull name of the currency
ledger_balancestringTotal balance in the wallet (decimal string)
available_balancestringAvailable balance after holds (decimal string)
statusstringWallet status: active, inactive, suspended
created_atstring (ISO 8601)Wallet creation timestamp
updated_atstring (ISO 8601)Last update timestamp
bank_account_detailsarrayVirtual bank account details (if applicable)
user_first_namestringCustomer's first name
user_last_namestringCustomer's last name
user_emailstringCustomer's email address
user_typestringCustomer type: INDIVIDUAL or BUSINESS

Error Responses

Status CodeDescription
400Invalid wallet ID format
401Unauthorized - Invalid or missing API key or signature
403Forbidden - Wallet does not belong to authenticated customer
404Wallet not found
500Internal server error

Example: cURL

bash
curl -X GET "https://api.sznd.app/api/v1/client/wallets/a1b2c3d4-e5f6-7890-1234-567890abcdef" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here"

Example: HTTP Request

http
GET /api/v1/client/wallets/a1b2c3d4-e5f6-7890-1234-567890abcdef HTTP/1.1Host: api.sznd.appx-api-key: your_api_key_herex-timestamp: 2025-01-30T12:20:15Zx-signature: generated_signature_hereContent-Type: application/json

Use Cases

  1. Balance Checking - Check individual wallet balances for specific currencies
  2. Multi-Currency Overview - View all wallets for a customer to see their multi-currency holdings
  3. Wallet Status Monitoring - Monitor wallet status (active, inactive, suspended)
  4. Transaction Preparation - Verify wallet balances before creating transactions or quotes

Best Practices

  1. Cache Wallet Data - Wallet balances don't change as frequently as transactions, so consider caching for short periods
  2. Handle Inactive Wallets - Check wallet status before attempting transactions
  3. Monitor Available Balance - Always check available_balance rather than ledger_balance to account for holds
  4. Currency-Specific Operations - Use individual wallet endpoints when working with specific currencies

Next Steps

  • - Onboard customers to virtual wallets for receiving deposits
  • - View transaction history for wallets
  • - Get list of supported currencies