Wallets

The Wallets API allows you to manage digital wallets linked to your company account. It supports retrieving wallet information and checking balances across different asset types (USDT, USDC, BTC). Use this API to track balances, monitor available funds, and ensure sufficient balance before initiating transactions.

Key Features

Multi-currency support: View balances across USDT, USDC, and BTC wallets.

Real-time balances: Get up-to-date ledger and available balances.

Formatted output: Receive human-readable balance strings alongside raw values.

Wallet Endpoints

Get Balances

Use Case

This endpoint returns a real-time snapshot of your wallet balances across every supported currency on your account. Each entry reflects funds that are currently available to spend, send, or convert — making it the single source of truth for dashboards, pre-trade checks, withdrawal eligibility, reconciliation jobs, and any workflow that needs to confirm liquidity before initiating a transaction.

Note

Balance values are returned as strings in the smallest unit of each currency. Stablecoins (USDT, USDC) use 6 decimal places; BTC uses 8 decimal places. Always rely on the _formatted fields for display, and perform arithmetic on the raw integer strings to avoid floating-point drift.

Get Balances

Get Balances Response

This is the standard shape of a balances response returned by the API.

successBoolean

Top-level flag indicating whether the request was processed successfully.

messageString

Human-readable status message describing the outcome of the request.

dataObject

Envelope wrapping the list of per-currency accounts and the company they belong to.

data.company_idUUID

Unique identifier of the company whose balances are being retrieved.

data.accountsArray<Account>

Per-currency account balances for this company.

account_idUUID

Unique identifier for the currency-specific account.

account_numberString

The company account number shared across all currency accounts.

currencyString

The currency of the account (e.g., USDT, USDC, BTC).

ledger_balanceString

Total ledger balance as an integer string in the currency's smallest unit (satoshis for BTC, 6-decimal minor units for USDT/USDC). Use ledger_balance_formatted for display.

available_balanceString

Balance available for spending (ledger_balance minus any holds), also expressed as an integer string in the smallest unit. Use available_balance_formatted for display.

ledger_balance_formattedString

Human-readable ledger balance with currency symbol (e.g. '5101.335847 USDT', '0.00375783 BTC').

available_balance_formattedString

Human-readable available balance with currency symbol.

created_atDate

RFC 3339 / ISO 8601 timestamp of when the currency account was created.

metadataObject

Top-level response metadata (support and debugging info).

metadata.request_idString

Unique identifier for this API request, useful for log correlation and support.

timestampDate

Top-level RFC 3339 / ISO 8601 server timestamp of when the response was generated (UTC).

Balances Sample Response

Get Balance By Currency

Use Case

This endpoint retrieves your account balance for a specific currency. Use it to check available funds in a particular wallet (e.g., BTC, USDT, USDC) before initiating transfers or for currency-specific reporting.

Path Parameters

:currencystringRequired

The currency code to retrieve the balance for. Supported values: 'BTC', 'USDT', 'USDC'.

Get Balance By Currency

Get Balance By Currency Response

This is the standard shape of a single currency balance response returned by the API.

successBoolean

Top-level flag indicating whether the request was processed successfully.

messageString

Human-readable status message describing the outcome of the request.

dataObject

Envelope wrapping the single-currency balance snapshot.

data.account_numberString

The account number associated with your company.

data.currencyString

The currency code for this balance (e.g. 'USDT', 'USDC', 'BTC').

data.total_balanceString

Total balance as an integer string in the currency's smallest unit (satoshis for BTC, 6-decimal minor units for USDT/USDC). Equals available_balance + pending_balance.

data.available_balanceString

Balance available for spending right now (total_balance minus pending_balance), expressed as an integer string in the smallest unit.

data.pending_balanceString

Portion of the balance currently held for in-flight operations (e.g. unconfirmed deposits or pending withdrawals), in the smallest unit.

data.company_idUUID

Unique identifier of the company whose balance is being retrieved.

metadataObject

Top-level response metadata (support and debugging info).

metadata.request_idString

Unique identifier for this API request, useful for log correlation and support.

timestampDate

Top-level RFC 3339 / ISO 8601 server timestamp of when the response was generated (UTC).

Balance By Currency Sample Response

Error Responses

The Wallets API returns standard error responses. Below are common errors you may encounter.

Authentication Errors

401 UnauthorizedError

The request is missing or has invalid authentication headers. Verify your x-auth-client, x-auth-timestamp, x-auth-nonce, and x-auth-signature are correct.

403 ForbiddenError

Your API key does not have permission to access wallet data. Check your API credentials and permissions in the dashboard.

Request Errors

400 Bad RequestError

The currency parameter is invalid or not supported. Supported currencies: BTC, USDT, USDC.

404 Not FoundError

The requested currency wallet does not exist for your account.

429 Too Many RequestsError

You have exceeded the rate limit. Wait and retry after the cooldown period.

Error Response Examples