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"
        }
      ]
    }
  }
}

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_usd and total_holdings are scoped to the request, not to the wallet’s whole portfolio:
- Only the networks named in networks are counted.
- token_type, value_usd_min and reserve_in_usd_min filters are applied first.
price_usd and value_usd come back null rather than omitted when a token has no price.
balance is full precision and never rounded, but comes back null when the token cannot be resolved. balance_raw is always present, so fall back to it and convert with decimals: balance_raw / 10^decimals.
Filtering by token_type returns these balances.token_type values:
token_type param balances.token_type field
native native
non_native erc20, spl
omitted all of the above

`token_type` param	`balances.token_type` field
`native`	`native`
`non_native`	`erc20`, `spl`
omitted	all of the above

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`

Every network in one request must belong to the same VM family, or the request returns a 400.

For example, networks=eth,base,arbitrum is valid because all three are EVM.
Networks from different VM families must be queried in separate calls.

SDK Examples

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

x-cg-pro-api-key

string

header

required

Learn how to set up your API key

Path Parameters

address

string

default:0x9642b23ed1e01df1092b92641051881a322f5d4e

required

Wallet address.

Query Parameters

networks

string

default:eth,base

required

Query balances by networks, comma-separated if more than one. *refers to supported networks.

sort

enum<string>

Sort the holdings by field. Default: value_usd_desc

Available options:

value_usd_desc,

value_usd_asc

token_type

enum<string>

Filter holdings by token type. Omit to return both.

Available options:

native,

non_native

value_usd_min

number

Minimum holding value in USD.

reserve_in_usd_min

number

Minimum total reserve in USD of the holding's token.

page

integer

Page through results. Default value: 1

per_page

integer

Total results per page. Default value: 50 Valid values: 1...100

Response

200 - application/json

Wallet token balances data

data

object

required

Hide child attributes

data.id

string

required

Wallet address

data.type

string

required

Response type

data.attributes

object

required

Hide child attributes

data.attributes.wallet_address

string

required

Wallet address queried

data.attributes.total_value_usd

string

required

Total value of matching holdings in USD, across the requested networks only

data.attributes.total_holdings

integer

required

Number of matching holdings across the requested networks only

data.attributes.networks

object[]

required

Value and holding count per network, listing only networks holding a matching balance

Hide child attributes

data.attributes.networks.network

string

required

Network ID

data.attributes.networks.value_usd

string

required

Total value of matching holdings on this network in USD

data.attributes.networks.holdings

integer

required

Number of matching holdings on this network

data.attributes.networks.last_updated_at

string<date-time>

required

Last updated timestamp

data.attributes.balances

object[]

required

Token holdings, one entry per token

Hide child attributes

data.attributes.balances.network

string

required

Network ID

data.attributes.balances.address

string

required

Token contract address

data.attributes.balances.token_type

string

required

Token type, such as native, erc20 or spl

data.attributes.balances.name

string

required

Token name

data.attributes.balances.symbol

string

required

Token symbol

data.attributes.balances.decimals

integer

required

Token decimals

data.attributes.balances.coingecko_coin_id

string | null

required

CoinGecko coin ID

data.attributes.balances.balance_raw

string

required

Token balance in the smallest unit, before decimals are applied

data.attributes.balances.balance

string | null

required

Token balance at full precision

data.attributes.balances.price_usd

string | null

required

Token price in USD

data.attributes.balances.value_usd

string | null

required

Value of the holding in USD

data.attributes.balances.h24_price_change_percentage

string | null

required

24hr price change percentage

data.attributes.balances.total_reserve_in_usd

string | null

required

Total reserve in USD across all pools of the token

CoinGecko API

Onchain API

Token Balances by Wallet Address

Notes

SDK Examples

Authorizations

Path Parameters

Query Parameters

Response

​Notes

​SDK Examples

Authorizations

Path Parameters

Query Parameters

Response

Notes

SDK Examples