Historical Positions

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.

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 (MVP: Ethereum only, 6-12 months 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

ApiKeyAuth

Body

application/json

Request model for smart money historical holdings endpoint.

filtersany ofOptional

Additional filters to apply

order_byany ofOptional

Custom sort order. Defaults to sorting by date DESC, then value_usd DESC.

Responses

200

Smart money historical holdings data

application/json

400

Bad Request

application/json

401

Unauthorized

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

post

/api/v1/smart-money/historical-holdings

HTTPcURLJavaScriptPython

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: 750

{
  "date_range": {
    "from": "2024-01-01",
    "to": "2024-12-31"
  },
  "chains": [
    "ethereum"
  ],
  "filters": {
    "include_smart_money_labels": [
      "Fund",
      "Smart Trader"
    ],
    "exclude_smart_money_labels": [
      "30D Smart Trader"
    ],
    "include_stablecoins": false,
    "include_native_tokens": false,
    "balance": {
      "max": 10000,
      "min": 100
    },
    "value_usd": {
      "max": 100000,
      "min": 1000
    },
    "balance_24h_percent_change": {
      "max": 0.5,
      "min": -0.5
    },
    "holders_count": {
      "max": 1000,
      "min": 10
    },
    "share_of_holdings_percent": {
      "max": 0.1,
      "min": 0.01
    },
    "token_age_days": {
      "max": 365,
      "min": 1
    },
    "market_cap_usd": {
      "max": 10000000,
      "min": 1000000
    },
    "token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "token_symbol": "USDC",
    "token_sectors": [
      "DeFi",
      "Gaming"
    ]
  },
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "order_by": [
    {
      "field": "date",
      "direction": "ASC"
    }
  ]
}

{
  "data": [
    {
      "date": "text",
      "chain": "all",
      "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
  }
}