Data Methodology & Technical Reference

This page provides detailed technical specifications about how data is calculated, returned, and timed across Nansen API endpoints. This information is essential for quantitative analysis, backtesting

Date Range Behaviour

All date range parameters across Nansen API endpoints use closed brackets on both sides [from, to], meaning both the from_date and to_date are inclusive. For example, requesting from=2024-11-04, to=2024-11-05 will return data for both November 4th and November 5th.

Historical Data Calculation Method (Smart Money Historical Holdings)

The Smart Money Historical Holdings API returns daily holding snapshots over a date range. Completed days use values from the actual date requested, not recalculated future values. This avoids look-ahead bias for settled historical rows, making the data suitable for backtesting and predictive models.

The current UTC day is the exception: when the requested range includes today, today's row is live and still settling. It can change on repeated calls as balances continue to accumulate and live market data updates.

Field-Level Details

• value_usd: Historical USD value using the median price from that day for completed days; current-day values are partial until the day settles

• market_cap_usd: Historical market cap snapshot for completed days; current-day rows use live market data

• balance_24h_percent_change: Historical percentage calculated using that day's balance and the previous day's balance (with each day using its respective price)

Snapshot Timing & Data Availability

Snapshot Time

Daily snapshots represent end-of-day UTC values for completed days. The current UTC day is returned as a live partial row when requested.

Data Availability (Smart Money Historical Holdings)

Completed-day data processing begins at 05:00 AM UTC. Data is typically available by 07:00 AM UTC, though exact timing may vary. Today's row is included when requested, but it is live, partial, and can change until the day has settled.

Do not confuse this endpoint with Historical Smart Money Positions, which is keyed by as_of_date and excludes the current day until its daily snapshot is produced.

Historical Depth

The Smart Money Historical Holdings endpoint provides a 4-year rolling window of historical data. The earliest available date moves forward daily.