# Nansen Current Balance

> Nansen Current Balance is a paid API for AI agents from Nansen at api.nansen.ai, paid per call via MPP, $0.01/call, status unknown (last checked 2026-10-09).

Retrieve current token holdings and USD valuations for a blockchain address or named entity across one or more chains.

## Facts

- Endpoint: POST https://api.nansen.ai/api/v1/profiler/address/current-balance?utm_source=zero.xyz
- Price: $0.01/call
- Payment: MPP
- Status: unknown
- Last checked: 2026-10-09
- Activations on Zero: 0
- Provider: Nansen
- Docs: https://docs.nansen.ai
- Website: https://nansen.ai
- Tags: blockchain, smart-money, wallet, tokens, defi, analytics, profiler, dex, pnl, onchain, prediction-market, data
- Canonical page: https://www.zero.xyz/c/nansen-current-balance-54366e1a
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_kqqvqnMTY7ROVu4xLkAKb

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability nansen-current-balance-54366e1a -d '<json body>'
```

Example prompt: Using Nansen, pull the current token balances for Ethereum address 0x28c6c06298d514db089934071355e5743bf21d60 — show me all holdings worth more than $100, hide spam tokens, and give me the first page of 10 results.

## When to prefer this

Use this endpoint when you need a real-time snapshot of what tokens a specific wallet address or named entity (e.g. a known fund or public figure) currently holds, including USD valuations. Prefer this over historical or trade-based endpoints when the question is about present holdings rather than past activity. Ideal for portfolio composition analysis, smart money monitoring, and cross-chain asset distribution queries.

## Known failure modes

- Missing required 'chain' field returns 422 validation error
- Invalid chain enum value returns validation error
- Address not found on specified chain returns empty data array
- Both address and entity_name omitted may return empty or error response
- Pagination page beyond last page returns empty data with is_last_page=true
- Rate limit or payment failure returns 402 or 429 error
- Invalid address format may return empty results or validation error

## How this service works

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.

## Output

A paginated list of token balance records, each containing the chain, wallet address, token symbol, token name, token contract address, raw token amount, current USD price per token, and total USD value held. Also includes pagination metadata (current page, per_page, is_last_page). If queried by entity name, the address field in each record will be empty.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "ProfilerAddressBalancesRequest",
 "examples": [
  {
   "chain": "ethereum",
   "address": "0x28c6c06298d514db089934071355e5743bf21d60",
   "pagination": {
    "page": 1,
    "per_page": 10
   },
   "hide_spam_token": true
  },
  {
   "chain": "ethereum",
   "pagination": {
    "page": 1,
    "per_page": 10
   },
   "entity_name": "Vitalik Buterin",
   "hide_spam_token": true
  }
 ],
 "required": [
  "chain"
 ],
 "properties": {
  "chain": {
   "enum": [
    "all",
    "arbitrum",
    "arc",
    "avalanche",
    "base",
    "bitcoin",
    "bnb",
    "ethereum",
    "hyperevm",
    "injective",
    "iotaevm",
    "linea",
    "mantle",
    "mantra",
    "monad",
    "near",
    "optimism",
    "plasma",
    "polygon",
    "robinhood",
    "sei",
    "solana",
    "sonic",
    "starknet",
    "sui",
    "ton",
    "tron"
   ],
   "type": "string",
   "title": "ProfilerChain",
   "description": "Chains supported in profiler analysis."
  },
  "address": {
   "anyOf": [
    {
     "type": "string"
    }
   ],
   "title": "Address",
   "examples": [
    "0x28c6c06298d514db089934071355e5743bf21d60",
    "8zFZHuSRuDpuAR7J6FzwyF3vKNx4CVW3DFHJerQhc7Zd"
   ],
   "description": "Address to get balances for"
  },
  "filters": {
   "anyOf": [
    {
     "type": "object",
     "title": "ProfilerAddressBalancesFilters",
     "properties": {
      "price_usd": {
       "anyOf": [
        {
         "type": "object",
         "title": "NumericRangeFilter",
         "properties": {
          "max": {
           "anyOf": [
            {
             "type": "number"
            }
           ],
           "title": "Max",
           "examples": [
            50000,
            10000000,
            100
           ],
           "description": "Maximum value (inclusive)"
          },
          "min": {
           "anyOf": [
            {
             "type": "number"
            }
           ],
           "title": "Min",
           "examples": [
            1000,
            1000000,
            -50,
            0
           ],
           "description": "Minimum value (inclusive)"
          }
         },
         "description": "Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"
        }
       ],
       "examples": [
        {
         "max": 1000,
         "min": 0.01
        }
       ],
       "description": "Token price range filter in U
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "ProfilerAddressBalancesResponse",
 "required": [
  "pagination",
  "data"
 ],
 "properties": {
  "data": {
   "type": "array",
   "items": {
    "type": "object",
    "title": "ProfilerBalance",
    "required": [
     "chain",
     "address",
     "token_address",
     "token_symbol"
    ],
    "properties": {
     "chain": {
      "type": "string",
      "title": "Chain",
      "description": "Chain"
     },
     "address": {
      "type": "string",
      "title": "Address",
      "description": "Address of the wallet. Empty if entity_name is provided. EVM addresses are returned in lowercase."
     },
     "price_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Price Usd",
      "description": "Price of the token"
     },
     "value_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Value Usd",
      "description": "Token balance value in USD"
     },
     "token_name": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Token Name",
      "description": "Token name"
     },
     "token_amount": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Token Amount",
      "description": "Token balance"
     },
     "token_symbol": {
      "type": "string",
      "title": "Token Symbol",
      "description": "Token symbol"
     },
     "token_address": {
      "type": "string",
      "title": "Token Address",
      "description": "Address of token"
     }
    },
    "description": "Individual profiler balance record.\n\nRepresents a single token balance from the wallet profiler."
   },
   "title": "Data",
   "description": "List of balance records"
  },
  "pagination": {
   "type": "object",
   "title": "PaginationInfo",
   "properties": {
    "page": {
     "type": "integer",
     "title": "Page",
     "default": 1,
     "minimum": 1,
     "description": "Current page number"
    },
    "per_page": {
     "type": "integer",
     "title": "Per Page",
     "default": 10,
     "maximum": 1000,
     "minimum": 1,
     "description": "Number of records per page"
    },
    "is_last_page": {
     "type": "boolean",
     "title": "Is Last Page",
     "default": true,
     "description": "Whether this is the last page"
    }
   },
   "description": "Pagination information for API responses."
  }
 },
 "description": "Response model for profiler address current-balance endpoint.\n\nCo
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-current-balance-54366e1a/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.nansen.ai](https://www.zero.xyz/host/api.nansen.ai/llms.txt)