Historical Holdings

Set filters.include_native_tokens to true to include native assets; the default is false. See Native Tokens for coverage limitations.

Note: This is a beta endpoint. The data provided may be subject to changes, corrections, or improvements as we continue to refine our Smart Money analytics.

Data Freshness & Historical Coverage

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

• Data is provided as daily snapshots, so a given day's holdings become available once per day rather than updating continuously.

• History is limited to a rolling ~4-year window (roughly the last four years up to today) — shorter than the full chain-level history on older chains.

• Today's row is live, not settled: for block_date = today(), market cap is computed from a live price/FDV lookup rather than the frozen daily snapshot, and the underlying balance figures are still accumulating for the partial day — so today's row can change on repeated calls. Any day before today is immutable once written.

• Results are server-cached keyed on the requested range: 5 minutes if the range includes today or ends within the last 2 days, 7 days once the range is fully settled.

• For point-in-time Smart Money snapshots keyed by as_of_date, use Historical Smart Money Positions; that endpoint excludes the current day until its daily snapshot is produced.

Get Smart Money Historical Holdings Data

post

Retrieve historical snapshots of aggregated token balances held by smart traders and funds. This endpoint provides time-series data for trend analysis, backtesting, and performance attribution.

Key Features:

• Daily snapshots of smart money holdings

• Date range filtering (max 4 years lookback)

• Point-in-time pricing and market cap data

• Balance change tracking between snapshots

• Same filtering options as current holdings endpoint

Use Cases:

• Trend Analysis: Track how smart money rotates between assets over time

• Performance Attribution: Combine with price data to estimate ROI

• Backtesting: Validate trading strategies based on historical smart money behavior

Authorizations

apikeystringRequired

API key for authentication

Body

Request model for smart money historical holdings endpoint.

filtersany ofOptional

Additional filters to apply

Example: {"balance_24h_percent_change":{"max":0.1,"min":-0.1},"exclude_smart_money_labels":["30D Smart Trader"],"include_native_tokens":false,"include_smart_money_labels":["Fund","Smart Trader"],"include_stablecoins":false,"token_age_days":{"max":30},"value_usd":{"max":100000,"min":1000}}

order_byany ofOptional

Custom sort order. Defaults to sorting by date DESC, value_usd DESC, token_address ASC, chain ASC for stable pagination.

Responses

200

Smart money historical holdings 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/smart-money/historical-holdings

POST /api/v1/smart-money/historical-holdings HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 453

{
  "date_range": {
    "from": "2025-10-01",
    "to": "2025-10-31"
  },
  "chains": [
    "ethereum"
  ],
  "filters": {
    "balance_24h_percent_change": {
      "max": 0.1,
      "min": -0.1
    },
    "exclude_smart_money_labels": [
      "30D Smart Trader"
    ],
    "include_native_tokens": false,
    "include_smart_money_labels": [
      "Fund",
      "Smart Trader"
    ],
    "include_stablecoins": false,
    "token_age_days": {
      "max": 30
    },
    "value_usd": {
      "max": 100000,
      "min": 1000
    }
  },
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "order_by": [
    {
      "field": "date",
      "direction": "ASC"
    }
  ]
}

{
  "data": [
    {
      "date": "text",
      "chain": "arc",
      "token_address": "text",
      "token_symbol": "text",
      "token_sectors": [
        "text"
      ],
      "smart_money_labels": [
        "text"
      ],
      "balance": 1,
      "value_usd": 1,
      "balance_24h_percent_change": 1,
      "holders_count": 1,
      "share_of_holdings_percent": 1,
      "token_age_days": 1,
      "market_cap_usd": 1
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  }
}