Balances

profiler/address/balances

post

Token balances for a given set of addresses. For each token balance, it provides details like which chain the token is on, the current price in USD, the token balance value in USD and the token's logo URL.

Authorizations
Body
Responses
200
Successful response
application/json
post
POST /api/beta/profiler/address/balances HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 169

{
  "parameters": {
    "chain": "ethereum",
    "walletAddresses": [
      "0x28c6c06298d514db089934071355e5743bf21d60"
    ],
    "suspiciousFilter": "on"
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}
[
  {
    "chain": "text",
    "tokenAddress": "text",
    "symbol": "text",
    "name": "text",
    "tokenAmount": 1,
    "priceUsd": 1,
    "usdValue": 1
  }
]

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
Body
Responses
200
Successful response
application/json
post
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",
PreviousProfilerNextTransactions

Last updated

Was this helpful?