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:

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

Parameter	Type	Required	Description
`default_currency`	string	No	Preferred 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)

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

Field	Type	Description
`wallets`	array	Array of wallet objects. Only includes wallets with active currencies. Each wallet contains:
`wallets[].id`	string (UUID)	Unique wallet identifier
`wallets[].user_id`	string (UUID)	Customer user ID who owns the wallet
`wallets[].currency`	string	Currency code (ISO 4217, e.g., "USD", "EUR", "NGN")
`wallets[].currency_name`	string	Full name of the currency
`wallets[].ledger_balance`	string	Total balance in the wallet (decimal string)
`wallets[].available_balance`	string	Available balance after holds (decimal string)
`wallets[].status`	string	Wallet status: `active`, `inactive`, `suspended`
`wallets[].created_at`	string (ISO 8601)	Wallet creation timestamp
`wallets[].updated_at`	string (ISO 8601)	Last update timestamp
`wallets[].bank_account_details`	array	Virtual bank account details (if applicable)
`wallets[].user_first_name`	string	Customer's first name
`wallets[].user_last_name`	string	Customer's last name
`wallets[].user_email`	string	Customer's email address
`wallets[].user_type`	string	Customer type: `INDIVIDUAL` or `BUSINESS`

Error Responses

Status Code	Description
`401`	Unauthorized - Invalid or missing API key or signature
`500`	Internal server error

Example: cURL

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 HTTP/1.1
Host: api.sznd.app
x-api-key: your_api_key_here
x-timestamp: 2025-01-30T12:20:15Z
x-signature: generated_signature_here
Content-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

Parameter	Type	Description
`id`	string (UUID)	Unique wallet identifier

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

Field	Type	Description
`id`	string (UUID)	Unique wallet identifier
`user_id`	string (UUID)	Customer user ID who owns the wallet
`currency`	string	Currency code (ISO 4217, e.g., "USD", "EUR", "NGN")
`currency_name`	string	Full name of the currency
`ledger_balance`	string	Total balance in the wallet (decimal string)
`available_balance`	string	Available balance after holds (decimal string)
`status`	string	Wallet status: `active`, `inactive`, `suspended`
`created_at`	string (ISO 8601)	Wallet creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp
`bank_account_details`	array	Virtual bank account details (if applicable)
`user_first_name`	string	Customer's first name
`user_last_name`	string	Customer's last name
`user_email`	string	Customer's email address
`user_type`	string	Customer type: `INDIVIDUAL` or `BUSINESS`

Error Responses

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

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.1
Host: api.sznd.app
x-api-key: your_api_key_here
x-timestamp: 2025-01-30T12:20:15Z
x-signature: generated_signature_here
Content-Type: application/json

Use Cases

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

Best Practices

Cache Wallet Data - Wallet balances don't change as frequently as transactions, so consider caching for short periods
Handle Inactive Wallets - Check wallet status before attempting transactions
Monitor Available Balance - Always check available_balance rather than ledger_balance to account for holds
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

💼 Virtual Wallets 📋 Overview