Resources
Wallets

Wallets API

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

List User's Wallets

Retrieve all wallets associated with a specific user, including their balances, currencies, and statuses.

Endpoint

GET /api/v1/users/{id}/wallets

Authentication

This endpoint requires JWT authentication. Include your access token in the Authorization header:

Authorization: Bearer <your-access-token>

Path Parameters

ParameterTypeDescription
idstring (UUID)The unique identifier of the user whose wallets to retrieve

Success Response (200 OK)

Returns an array of wallet objects:

[
  {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "user_id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210",
    "currency": "USD",
    "currency_name": "US Dollar",
    "balance": "12345.67",
    "available_balance": "12345.67",
    "status": "active",
    "created_at": "2024-03-15T10:30:00Z",
    "updated_at": "2025-05-30T18:35:49Z"
  },
  {
    "id": "b2c3d4e5-f6a7-8901-2345-678901bcdefg",
    "user_id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210",
    "currency": "NGN",
    "currency_name": "Nigerian Naira",
    "balance": "5000000.00",
    "available_balance": "4500000.00",
    "status": "active",
    "created_at": "2024-03-15T10:30:00Z",
    "updated_at": "2025-05-30T18:35:49Z"
  },
  {
    "id": "c3d4e5f6-a7b8-9012-3456-789012cdefgh",
    "user_id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210",
    "currency": "EUR",
    "currency_name": "Euro",
    "balance": "500.00",
    "available_balance": "500.00",
    "status": "active",
    "created_at": "2024-04-01T12:00:00Z",
    "updated_at": "2025-05-30T18:35:49Z"
  }
]

Response Fields

FieldTypeDescription
idstring (UUID)Unique identifier of the wallet
user_idstring (UUID)Unique identifier of the user who owns this wallet
currencystringISO 4217 currency code (e.g., "USD", "EUR", "NGN")
currency_namestringFull name of the currency
balancestringTotal current balance of the wallet (decimal string)
available_balancestringPortion of balance available for transactions (decimal string)
statusstringCurrent status of the wallet (e.g., "active", "suspended", "closed")
created_atstring (ISO 8601)Timestamp when the wallet was created (UTC)
updated_atstring (ISO 8601)Timestamp when the wallet was last updated (UTC)

Wallet Statuses

  • active - Wallet is active and can be used for transactions
  • suspended - Wallet is temporarily suspended
  • closed - Wallet is closed and cannot be used

Balance vs Available Balance

  • balance - Total balance including any funds on hold
  • available_balance - Balance available for immediate use (excludes funds on hold)

The difference between balance and available_balance represents funds that are currently on hold (e.g., pending transactions, reserves).

Error Responses

Status CodeDescription
401Unauthorized - Invalid or missing JWT token
403Forbidden - User does not have permission to access these wallets
404User not found
500Internal server error

Example: cURL

# Get wallets for a user
curl -X GET "/api/v1/users/f0e9d8c7-b6a5-4321-fedc-ba9876543210/wallets" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Example: HTTP Request

GET /api/v1/users/f0e9d8c7-b6a5-4321-fedc-ba9876543210/wallets HTTP/1.1
Host: api.sznd.app
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Use Cases

  1. Balance Display - Show users their wallet balances across all currencies
  2. Available Funds Check - Verify available balance before creating transactions
  3. Multi-Currency Dashboard - Display all user wallets in a single view
  4. Balance Validation - Check if user has sufficient funds for a transaction
  5. Hold Amount Tracking - Calculate and display funds on hold

Best Practices

  1. Check Available Balance - Always use available_balance for transaction validation, not balance
  2. Handle Multiple Wallets - Users may have multiple wallets for different currencies
  3. Display Status - Show wallet status to users (active, suspended, closed)
  4. Show On-Hold Funds - Display the difference between balance and available balance
  5. Cache Results - Cache wallet balances but refresh frequently for accuracy
  6. Handle Empty Wallets - Some users may not have wallets for all currencies

Next Steps

TransfersQuote API System