Address Current Balances

Get real-time token balance information for any blockchain address or entity

Common Scenarios

You can use this endpoint to find correct entity name format to use in this Profiler Endpoint: Click Here

Usecase	Required Parameters	Optional Filters	Expected Output
Check current holdings for a single address	address = "0x28c6c06298d514db089934071355e5743bf21d60", chain = "ethereum"	hide_spam_token = true,	List of tokens with amounts, USD values, and chain info for the address
View entity-wide portfolio (e.g., Vitalik Buterin)	entity_name = "Vitalik Buterin", chain = "all"	hide_spam_token = true	Aggregated balances for entity across all wallets, showing holdings per chain

Data Freshness & Historical Coverage

For data freshness and historical coverage, see Data Coverage by Chain; this endpoint follows it except where noted below.

• Returns a current, point-in-time snapshot of holdings — there is no date-range parameter or historical look-back; balances update continuously off on-chain activity and reflect within the standard live latency.

Get Address Current Balance Data

post

Retrieve current token holdings for addresses or entities. Returns detailed balance information across specified chains.

What it helps to answer:

• Current token holdings with quantities and USD valuations

• Asset distribution across different blockchain networks

• Native token versus token balances

• Stablecoin holdings and percentages

• Cross-chain portfolio composition

Note: The address field in the response will be empty if entity_name is provided.

Authorizations

apikeystringRequired

API key for authentication

Body

addressany ofOptional

Address to get balances for

Example: 0x28c6c06298d514db089934071355e5743bf21d60

stringOptional

entity_nameany ofOptional

Entity name to get balances for

Example: Vitalik Buterin

stringOptional

chainstring · enumRequired

Blockchain chain for the balances

Example: ethereumPossible values:

hide_spam_tokenbooleanOptional

Removes suspicious tokens from the balance list

Default: trueExample: true

filtersany ofOptional

Additional filters to apply. Only filters for columns that are being selected will be applied.

Example: {"token_symbol":"USDC","value_usd":{"min":10}}

order_byany ofOptional

Custom sort order to override the endpoint's default ordering

Responses

200

Address current balance data

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

402

Payment Required

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

502

Bad Gateway

application/json

503

Service Unavailable

application/json

504

Gateway Timeout

application/json

post/api/v1/profiler/address/current-balance

POST /api/v1/profiler/address/current-balance HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 136

{
  "address": "0x28c6c06298d514db089934071355e5743bf21d60",
  "chain": "ethereum",
  "hide_spam_token": true,
  "pagination": {
    "page": 1,
    "per_page": 10
  }
}

{
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  },
  "data": [
    {
      "chain": "text",
      "address": "text",
      "token_address": "text",
      "token_symbol": "text",
      "token_name": "text",
      "token_amount": 1,
      "price_usd": 1,
      "value_usd": 1
    }
  ]
}