Get Balance Summary

Get a comprehensive summary of all balances for the tenant, including wallet balances and custody account balances.

Endpoint

GET /manage/users/balances

Authentication

This endpoint requires an OAuth 2.0 access token with tenant administrator or global administrator role:

Authorization: Bearer {access_token}

Parameters

Query Parameters

Parameter	Type	Default	Description
include_wallets	boolean	true	Whether to include wallet balances in the response
include_custody	boolean	true	Whether to include custody account balances in the response

Response

200 OK

A successful response will include a detailed summary of all balances:

{
  "total_balances": [
    {
      "blockchain": "ETH",
      "token": "USDT",
      "hot_wallet_balance": 1000.0,
      "cold_wallet_balance": 5000.0,
      "custody_balance": 2000.0,
      "total_balance": 8000.0
    },
    {
      "blockchain": "BSC",
      "token": "USDT",
      "hot_wallet_balance": 500.0,
      "cold_wallet_balance": 2500.0,
      "custody_balance": 1500.0,
      "total_balance": 4500.0
    }
  ],
  "wallets": [
    {
      "id": "wallet-123",
      "name": "ETH Hot Wallet",
      "blockchain": "ETH",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "is_cold_wallet": false,
      "balance": 1000.0,
      "token": "USDT",
      "last_check": "2025-04-19T12:34:56.789Z"
    }
  ],
  "custody_accounts": [
    {
      "id": "account-123",
      "tenant_id": "tenant-123",
      "name": "Main Custody Account",
      "external_id": "ext-123",
      "account_type": "standard",
      "is_active": true,
      "is_verified": true,
      "created_at": "2025-04-19T12:34:56.789Z",
      "updated_at": "2025-04-19T12:34:56.789Z",
      "last_sync": "2025-04-19T12:34:56.789Z"
    }
  ],
  "last_updated": "2025-04-19T12:34:56.789Z"
}

Response Fields

total_balances Array

Each object in the total_balances array contains:

Field	Type	Description
blockchain	string	Blockchain identifier (e.g., "ETH", "BSC")
token	string	Token symbol (e.g., "USDT")
hot_wallet_balance	number	Total balance in hot wallets
cold_wallet_balance	number	Total balance in cold wallets
custody_balance	number	Total balance in custody accounts
total_balance	number	Sum of all balances

wallets Array

Each object in the wallets array contains:

Field	Type	Description
id	string	Wallet identifier
name	string	Wallet name
blockchain	string	Blockchain identifier
address	string	Wallet address
is_cold_wallet	boolean	Whether this is a cold wallet
balance	number	Current wallet balance
token	string	Token symbol
last_check	string	Timestamp of last balance check

custody_accounts Array

Each object in the custody_accounts array contains:

Field	Type	Description
id	string	Custody account identifier
tenant_id	string	Tenant identifier
name	string	Account name
external_id	string	External identifier
account_type	string	Account type (e.g., "standard")
is_active	boolean	Whether the account is active
is_verified	boolean	Whether the account is verified
created_at	string	Creation timestamp
updated_at	string	Last update timestamp
last_sync	string	Last synchronization timestamp

401 Unauthorized

Occurs when the OAuth 2.0 access token is missing or invalid:

{
  "detail": "Not authenticated"
}

403 Forbidden

Occurs when the authenticated user doesn't have tenant administrator role:

{
  "detail": "Only tenant administrators can access this endpoint"
}

Example Request

curl -X GET "https://api.cryptofuse.io/manage/users/balances" \
  -H "Authorization: Bearer eyJ0eXAiOiJPQXV0aFRva2VuIiwiYWxnIjoiUlMyNTYifQ..."

Example Response

{
  "total_balances": [
    {
      "blockchain": "ETH",
      "token": "USDT",
      "hot_wallet_balance": 1000.0,
      "cold_wallet_balance": 5000.0,
      "custody_balance": 2000.0,
      "total_balance": 8000.0
    },
    {
      "blockchain": "BSC",
      "token": "USDT",
      "hot_wallet_balance": 500.0,
      "cold_wallet_balance": 2500.0,
      "custody_balance": 1500.0,
      "total_balance": 4500.0
    }
  ],
  "wallets": [
    {
      "id": "wallet-123",
      "name": "ETH Hot Wallet",
      "blockchain": "ETH",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "is_cold_wallet": false,
      "balance": 1000.0,
      "token": "USDT",
      "last_check": "2025-04-19T12:34:56.789Z"
    },
    {
      "id": "wallet-456",
      "name": "ETH Cold Wallet",
      "blockchain": "ETH",
      "address": "0xabcdef1234567890abcdef1234567890abcdef12",
      "is_cold_wallet": true,
      "balance": 5000.0,
      "token": "USDT",
      "last_check": "2025-04-19T12:34:56.789Z"
    }
  ],
  "custody_accounts": [
    {
      "id": "account-123",
      "tenant_id": "tenant-123",
      "name": "Main Custody Account",
      "external_id": "ext-123",
      "account_type": "standard",
      "is_active": true,
      "is_verified": true,
      "created_at": "2025-04-19T12:34:56.789Z",
      "updated_at": "2025-04-19T12:34:56.789Z",
      "last_sync": "2025-04-19T12:34:56.789Z"
    }
  ],
  "last_updated": "2025-04-19T12:34:56.789Z"
}