Token Balances by Wallet Address
curl --request GET \
--url https://pro-api.coingecko.com/api/v3/onchain/wallets/{address}/balances \
--header 'x-cg-pro-api-key: <api-key>'{
"data": {
"id": "0x9642b23ed1e01df1092b92641051881a322f5d4e",
"type": "wallet_balance",
"attributes": {
"wallet_address": "0x9642b23ed1e01df1092b92641051881a322f5d4e",
"total_value_usd": "91333695.8924553249294795652",
"total_holdings": 3235,
"networks": [
{
"network": "eth",
"value_usd": "91333647.2139247191042473531",
"holdings": 2784,
"last_updated_at": "2026-09-09T04:53:53Z"
},
{
"network": "base",
"value_usd": "48.6785306058252322121",
"holdings": 451,
"last_updated_at": "2026-09-09T04:54:00Z"
}
],
"balances": [
{
"network": "eth",
"address": "0xae7ab96520de3a18e5e111b5eaab095312d7fe84",
"token_type": "erc20",
"name": "Liquid staked Ether 2.0",
"symbol": "stETH",
"decimals": 18,
"coingecko_coin_id": "staked-ether",
"balance_raw": "1285426654835126578249",
"balance": "1285.426654835126578249",
"price_usd": "2505.0197550041",
"value_usd": "3220019.16397083",
"h24_price_change_percentage": "1.1092026358",
"total_reserve_in_usd": "76309888.5752643"
},
{
"network": "base",
"address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
"token_type": "native",
"name": "Ether",
"symbol": "ETH",
"decimals": 18,
"coingecko_coin_id": "ethereum",
"balance_raw": "5689474631933105",
"balance": "0.005689474631933105",
"price_usd": "2509.94",
"value_usd": "14.2802399576741775637",
"h24_price_change_percentage": "1.1788611331",
"total_reserve_in_usd": "278512639.260865"
}
]
}
}
}Token Balances by Wallet Address
To query the token balances of a wallet address across networks
GET
/
onchain
/
wallets
/
{address}
/
balances
Token Balances by Wallet Address
curl --request GET \
--url https://pro-api.coingecko.com/api/v3/onchain/wallets/{address}/balances \
--header 'x-cg-pro-api-key: <api-key>'{
"data": {
"id": "0x9642b23ed1e01df1092b92641051881a322f5d4e",
"type": "wallet_balance",
"attributes": {
"wallet_address": "0x9642b23ed1e01df1092b92641051881a322f5d4e",
"total_value_usd": "91333695.8924553249294795652",
"total_holdings": 3235,
"networks": [
{
"network": "eth",
"value_usd": "91333647.2139247191042473531",
"holdings": 2784,
"last_updated_at": "2026-09-09T04:53:53Z"
},
{
"network": "base",
"value_usd": "48.6785306058252322121",
"holdings": 451,
"last_updated_at": "2026-09-09T04:54:00Z"
}
],
"balances": [
{
"network": "eth",
"address": "0xae7ab96520de3a18e5e111b5eaab095312d7fe84",
"token_type": "erc20",
"name": "Liquid staked Ether 2.0",
"symbol": "stETH",
"decimals": 18,
"coingecko_coin_id": "staked-ether",
"balance_raw": "1285426654835126578249",
"balance": "1285.426654835126578249",
"price_usd": "2505.0197550041",
"value_usd": "3220019.16397083",
"h24_price_change_percentage": "1.1092026358",
"total_reserve_in_usd": "76309888.5752643"
},
{
"network": "base",
"address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
"token_type": "native",
"name": "Ether",
"symbol": "ETH",
"decimals": 18,
"coingecko_coin_id": "ethereum",
"balance_raw": "5689474631933105",
"balance": "0.005689474631933105",
"price_usd": "2509.94",
"value_usd": "14.2802399576741775637",
"h24_price_change_percentage": "1.1788611331",
"total_reserve_in_usd": "278512639.260865"
}
]
}
}
}Notes
-
total_value_usdandtotal_holdingsare scoped to the request, not to the wallet’s whole portfolio:- Only the networks named in
networksare counted. token_type,value_usd_minandreserve_in_usd_minfilters are applied first.
- Only the networks named in
-
price_usdandvalue_usdcome backnullrather than omitted when a token has no price. -
balanceis full precision and never rounded, but comes backnullwhen the token cannot be resolved.balance_rawis always present, so fall back to it and convert withdecimals:balance_raw / 10^decimals. -
Filtering by
token_typereturns thesebalances.token_typevalues:token_typeparambalances.token_typefieldnativenativenon_nativeerc20,splomitted all of the above
Supported networks
Supported networks
| Chain | Network id |
|---|---|
| Ethereum | eth |
| Base | base |
| BNB Chain | bsc |
| Polygon | polygon_pos |
| Arbitrum | arbitrum |
| Optimism | optimism |
| Avalanche | avax |
| Stable | stable |
| Robinhood | robinhood |
| Linea | linea |
| Arc | arc |
| Monad | monad |
| Unichain | unichain |
| ZkSync | zksync |
| World Chain | world-chain |
| HyperEVM | hyperevm |
Every network in one request must belong to the same VM family, or the request returns a
400.- For example,
networks=eth,base,arbitrumis valid because all three are EVM. - Networks from different VM families must be queried in separate calls.
SDK Examples
New to the SDK? Install and authenticate theclient first:TypeScript | Python
const response = await client.onchain.wallets.balances.get('0x9642b23ed1e01df1092b92641051881a322f5d4e', {
networks: 'eth,base',
});
console.log(JSON.stringify(response, null, 2));
response = client.onchain.wallets.balances.get(
"0x9642b23ed1e01df1092b92641051881a322f5d4e",
networks="eth,base",
)
print(response.model_dump_json(indent=2))
Authorizations
headerAuthqueryAuth
Learn how to set up your API key
Path Parameters
Query Parameters
Query balances by networks, comma-separated if more than one. *refers to supported networks.
Response
200 - application/json
Wallet token balances data
Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
Value and holding count per network, listing only networks holding a matching balance
Hide child attributes
Hide child attributes
Token holdings, one entry per token
Hide child attributes
Hide child attributes
Was this page helpful?

