Account Balances

GET

/custody/accounts/:accountId/balances

Returns detailed balance information for a specific custody account across all blockchains. This endpoint provides the current balances with real-time data from the custody provider.

Path Parameters

Parameter	Type	Description
accountId required	string	The unique identifier of the custody account

Example Request

GET /custody/accounts/550e8400-e29b-41d4-a716-446655440000/balances
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response Parameters

Parameter	Type	Description
account_id	string	The ID of the custody account
last_updated	string	ISO 8601 timestamp of when the balances were last updated
total_usd_value	number	The total USD value of all balances across all blockchains
balances	array	Array of balance objects, one for each blockchain/token combination

Each balance object in the balances array contains:

Parameter	Type	Description
blockchain	string	The blockchain network (e.g., ETH, BSC, TRX, SOL)
token	string	The token symbol (e.g., USDT)
balance	number	The balance amount in the native token
usd_value	number	The USD value of the balance
available	number	The available balance (may be less than total balance if some funds are locked or reserved)
locked	number	The locked or reserved balance (e.g., for pending withdrawals)
last_transaction_at	string	ISO 8601 timestamp of the last transaction for this blockchain/token

Example Response

{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "last_updated": "2025-04-16T15:30:25.123Z",
  "total_usd_value": 15240.50,
  "balances": [
    {
      "blockchain": "ETH",
      "token": "USDT",
      "balance": 10000.00,
      "usd_value": 10000.00,
      "available": 9500.00,
      "locked": 500.00,
      "last_transaction_at": "2025-04-16T14:25:10.456Z"
    },
    {
      "blockchain": "BSC",
      "token": "USDT",
      "balance": 5240.50,
      "usd_value": 5240.50,
      "available": 5240.50,
      "locked": 0.00,
      "last_transaction_at": "2025-04-15T18:45:22.789Z"
    },
    {
      "blockchain": "TRX",
      "token": "USDT",
      "balance": 0.00,
      "usd_value": 0.00,
      "available": 0.00,
      "locked": 0.00,
      "last_transaction_at": null
    }
  ]
}

Error Codes

Status Code	Error Code	Description
401	authentication_failed	Authentication failed. Check your API key or JWT token
403	insufficient_permissions	You do not have permission to view balances for this account
404	account_not_found	Custody account with the specified ID was not found
429	rate_limit_exceeded	You have exceeded the rate limit for this endpoint
500	custody_provider_error	An error occurred when fetching balances from the custody provider

Notes

• The balances are fetched in real-time from the custody provider which may cause a slight delay in response time
• Zero balances for supported blockchains are included in the response
• The locked amount represents funds that are reserved or in the process of being withdrawn
• The available amount is the balance that can be used for new withdrawals

POST

/custody/accounts/:accountId/sync

Synchronizes the account balances with the custody provider to ensure the most up-to-date information. This is useful if you suspect the cached balance information might be outdated.

Path Parameters

Parameter	Type	Description
accountId required	string	The unique identifier of the custody account

Example Request

POST /custody/accounts/550e8400-e29b-41d4-a716-446655440000/sync
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response

{
  "success": true,
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "last_synced": "2025-04-16T15:45:30.123Z",
  "message": "Account balances successfully synchronized"
}

Error Codes

Status Code	Error Code	Description
401	authentication_failed	Authentication failed. Check your API key or JWT token
403	insufficient_permissions	You do not have permission to synchronize this account
404	account_not_found	Custody account with the specified ID was not found
429	rate_limit_exceeded	You have exceeded the rate limit for this endpoint
500	custody_provider_error	An error occurred when synchronizing with the custody provider

Notes

• This operation may take a few seconds to complete as it requires communication with the custody provider
• Excessive use of this endpoint may trigger rate limiting by the custody provider
• Regular balance updates occur automatically on a scheduled basis, so frequent manual synchronization is usually unnecessary