Wallets API

The Wallets API allows you to retrieve wallet information for your business account or for a specific customer, including balances, currency details, and status. Wallets are multi-currency accounts that hold funds in different currencies.

Get Wallets

Retrieve all wallets for a user. By default this returns wallets for the authenticated business account. Pass user_id to return wallets for one of your customers instead.

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:

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

Note: For HMAC authentication details, see the Authentication guide.

Query Parameters

Success Response (200 OK)

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

Error Responses

Example: List a customer's wallets

curl -X GET "https://api.sznd.app/api/v1/client/wallets?user_id=f0e9d8c7-b6a5-4321-fedc-ba9876543210" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here"

Example: List business (self) wallets

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

GET /api/v1/client/wallets?user_id=f0e9d8c7-b6a5-4321-fedc-ba9876543210 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:

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

Note: For HMAC authentication details, see the Authentication guide.

Path Parameters

Success Response (200 OK)

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

Error Responses

Example: cURL

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

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 via GET /client/wallets/{id}
2. Customer Multi-Currency Overview - Pass user_id on GET /client/wallets to list a customer's wallets
3. Business Self Balances - Omit user_id to list the business account's own wallets
4. Wallet Status Monitoring - Monitor wallet status (active, inactive, suspended)
5. 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

• Virtual Wallets API - Onboard customers to virtual wallets for receiving deposits
• Transactions API - View transaction history for wallets
• Currencies API - Get list of supported currencies