Address Historical Balances

Get historical token balance information for any blockchain address or entity

Common Scenarios

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., Coinbase)

entity_name = "Coinbase", chain = "all"

hide_spam_token = true

Aggregated balances for entity across all wallets, showing holdings per chain

Get Address Historical Balances Data

post

Track token and native coin balance changes over time for addresses or entities. Provides snapshots at configurable intervals to analyze holding patterns, transaction activity, and portfolio evolution across multiple blockchains.

What it helps to answer:

  • Portfolio value changes across different time periods

  • Token accumulation and distribution patterns over selected timeframes

  • New positions entered and exited during specific periods

Authorizations
Body
addressany ofOptional

Address to get historical balances for

Example: 0x28c6c06298d514db089934071355e5743bf21d60
stringOptional
entity_nameany ofOptional

Entity name to get historical balances for

Example: Vitalik Buterin
stringOptional
chainstring · enumRequired

Blockchain chain for the historical balances

Example: ethereumPossible values:
filtersany ofOptional

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

Example: {"hide_spam_tokens":true,"token_symbol":"USDC","value_usd":{"min":10}}
order_byany ofOptional

Custom sort order to override the endpoint's default ordering

Responses
200

Address historical balances data

application/json
post
/api/v1/profiler/address/historical-balances
POST /api/v1/profiler/address/historical-balances HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 180

{
  "address": "0x28c6c06298d514db089934071355e5743bf21d60",
  "chain": "ethereum",
  "date": {
    "from": "2025-05-01T00:00:00Z",
    "to": "2025-05-03T23:59:59Z"
  },
  "pagination": {
    "page": 1,
    "per_page": 10
  }
}
{
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  },
  "data": [
    {
      "block_timestamp": "text",
      "token_address": "text",
      "chain": "text",
      "token_amount": 1,
      "value_usd": 1,
      "token_symbol": "text"
    }
  ]
}
PreviousAddress Current BalancesNextAddress Transactions

Last updated

Was this helpful?