Balances

Three endpoints, all giving you current balances. For balances at a past time, jump to Balance history.

All three return cached balances by default and trigger an on-chain refresh when the cache is older than max_age seconds (default 300). Pass force_refresh=true to always re-fetch from chain.

GET /api/balance/ - one (account, token)

1curl 'https://api.tokenkithq.io/api/balance/?account_address=0x...&token_address=0x053c91253...' \
2  -H 'api-key: YOUR_API_KEY'

1{
2  "success": true,
3  "data": {
4    "account_address": "0x00000005dd3d2f4429af886cd1a3b08289dbcea99a294197e9eb43b0e0325b4b",
5    "token_address":   "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8",
6    "balance":         "6543110900255",
7    "balance_usd":     6543110.900255,
8    "last_updated":    "2026-01-25T14:43:57+00:00"
9  }
10}

balance is the raw on-chain integer as a string (no implicit decimals applied). Divide by 10^decimals for the human-readable amount; the decimals live on the token object from /api/tokens/.

POST /api/balances/ - batch lookup

Pass up to 20 (account, token) pairs in the request body and you get an array of balances back. Saves you a request per pair when rendering a multi-asset view.

1{
2  "success": true,
3  "data": [
4    {
5      "account_address": "0x...",
6      "token_address": "0x053c91253...",
7      "balance": "6543110900255",
8      "balance_usd": 6543110.900255,
9      "last_updated": "2026-01-25T14:43:57+00:00"
10    }
11  ],
12  "errors": null
13}

If any pair fails (malformed address, chain-fetch error), the request still returns 200 with the remaining successful results in data and per-pair errors in errors. Inspect both.

GET /api/account-balances/ - everything one account holds

Returns every indexed ERC-20 / ERC-721 / ERC-1155 row for the account, even balances of 0. Filter client-side if you only want non-zero holdings.

1curl 'https://api.tokenkithq.io/api/account-balances/?account_address=0x...' \
2  -H 'api-key: YOUR_API_KEY'

1{
2  "success": true,
3  "count": 12,
4  "data": [
5    {
6      "id": 1234,
7      "account": { "address": "0x..." },
8      "token": {
9        "address": "0x053c91253...",
10        "symbol": "USDC",
11        "name": "USD Coin",
12        "decimals": 6,
13        "current_price_usd": "1.000123",
14        "logo": "https://.../usdc.png"
15      },
16      "balance": "6543110900255",
17      "balance_usd": "6543110.900255",
18      "last_updated": "2026-01-25T14:43:57Z"
19    }
20  ]
21}

Each entry is a full AccountToken serializer row: a nested token object (so you don't need a second lookup) plus the balance fields. Returns an empty data array (not 404) if the account isn't indexed yet.

See also

• Balance history - per-event timeline for one (account, token) pair
• Portfolio - total USD across every token an account holds