Address Historical Balances

Deprecation Notice: The ‎/beta API endpoints will be deprecated on 01 October 2025. Please migrate your integrations to the ‎/v1 endpoints before this date to ensure uninterrupted service.

profiler/address/historical-balances

post

Historical native coin & token balances of specific group of addresses. For each date within a defined timeframe, it ranks tokens by their approximate USD balance, consolidating those not in the top 10 or below a 2% total daily balance threshold into an 'Other' category. It also offers functionality to exclude tokens labeled as suspicious. The final view provides a daily breakdown of top tokens, aiding in understanding the historical distribution and significance of token balances by their USD value.

Authorizations

ApiKeyAuth

Body

application/json

Responses

200

Successful response

application/json

400

Bad request

application/json

401

Authentication error

application/json

403

Forbidden - Subscription tier required

application/json

500

Internal server error

application/json

post

/api/beta/profiler/address/historical-balances

HTTPcURLJavaScriptPython

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

{
  "parameters": {
    "walletAddresses": [
      "0x28c6c06298d514db089934071355e5743bf21d60"
    ],
    "chain": "ethereum",
    "suspiciousFilter": "on",
    "timeFrame": 1
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

[
  {
    "blockTimestamp": "text",
    "tokenAddress": "text",
    "chain": "text",
    "usdBalance": "text",
    "symbol": "text"
  }
]

Usage Tips

Querying Entity Balances

You can also pull balances for any labeled entity (e.g., Binance, Paradigm Fund) instead of raw wallet addresses.

• Provide exactly one of:

  • walletAddresses – array of addresses or

  • entityId – string name or UUID of the entity

• Leave the other field empty / omitted.

• All other parameters work exactly the same.

Example request of entity lookup

POST /api/beta/profiler/address/balances
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json

{
  "parameters": {
    "chain": "all",
    "walletAddresses": [],
    "entityId": "Binance,
    "suspiciousFilter": "on"
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Querying Balances across all chains

You can also query balances across all chains using this

"chain": "all",