# Backtesting Data

The Nansen API  introduces a new family of **historical endpoints:** point-in-time versions of our most-used endpoints. Pass any past date, and the API reconstructs holders, flows, PnL, screener results, and wallet state exactly as they appeared on that day, with the labels and prices that were valid at the time.

In short: you can now backtest. No look-ahead bias, no manual snapshotting, no rebuilding label history.

### Why it matters

* **Validate strategies before deploying capital.** Replay any thesis, "buy when Smart Money accumulates," "exit when top holders concentrate", against real history.
* **Audit and attribution.** Show stakeholders, auditors, or LPs what a wallet, token, or cohort looked like on a specific date.
* **Train and evaluate models.** Generate clean training sets and out-of-sample test windows without leaking future information.
* **Research and reporting.** Quote on-chain facts as of any date, with full reproducibility.

### What's available

> ⚠️ **Beta notice.** These are historical endpoints released under V1 Beta (`/api/v1beta1/`). Request shapes, response fields, and pricing may change as we iterate based on feedback.

All historical endpoints live under `/api/v1beta1/` and follow the same conventions as the rest of the Nansen API.

<table><thead><tr><th width="190.49609375">Category</th><th width="368.64453125">Endpoints</th><th>Use case</th></tr></thead><tbody><tr><td><strong>Token God Mode</strong></td><td><code>tgm/historical-top-holders</code>, <code>tgm/historical-dex-trades</code>, <code>tgm/historical-who-bought-sold</code>, <code>tgm/historical-token-flow-summary</code>, <code>tgm/historical-pnl-leaderboard</code>, <code>tgm/historical-token-ohlcv</code>, <code>tgm/historical-token-quant-scores</code>, <code>tgm/historical-x-twitter-posts</code></td><td>Reconstruct a token's market structure, holder base, and trading activity on any past date.</td></tr><tr><td><strong>Token Screener</strong></td><td><code>token-screener/historical</code>, <code>token-screener/historical-perps</code></td><td>Re-run screeners as of a past date to test signal quality and ranking stability.</td></tr><tr><td><strong>Smart Money</strong></td><td><code>smart-money/historical-token-balances</code></td><td>See what Smart Money wallets held on any given day.</td></tr><tr><td><strong>Profiler (Wallets)</strong></td><td><code>profiler/address/historical-token-balances</code>, <code>profiler/address/historical-transactions</code>, <code>profiler/historical-transaction-lookup</code></td><td>Inspect any wallet's balances and transactions as they stood at a point in time.</td></tr></tbody></table>

### Pricing

Historical endpoints cost **5× the credits of their real-time counterpart**, reflecting the additional indexing required to serve point-in-time data.

<table><thead><tr><th width="523.8203125">Endpoint</th><th align="right">Credits per call</th></tr></thead><tbody><tr><td><code>tgm/historical-dex-trades</code></td><td align="right">5</td></tr><tr><td><code>tgm/historical-who-bought-sold</code></td><td align="right">5</td></tr><tr><td><code>tgm/historical-token-flow-summary</code></td><td align="right">5</td></tr><tr><td><code>token-screener/historical</code></td><td align="right">5</td></tr><tr><td><code>token-screener/historical-perps</code></td><td align="right">5</td></tr><tr><td><code>profiler/address/historical-token-balances</code></td><td align="right">5</td></tr><tr><td><code>profiler/address/historical-transactions</code></td><td align="right">5</td></tr><tr><td><code>profiler/historical-transaction-lookup</code></td><td align="right">5</td></tr><tr><td><code>tgm/historical-top-holders</code></td><td align="right">25</td></tr><tr><td><code>tgm/historical-pnl-leaderboard</code></td><td align="right">25</td></tr><tr><td><code>tgm/historical-token-quant-scores</code></td><td align="right">25</td></tr><tr><td><code>smart-money/historical-token-balances</code></td><td align="right">25</td></tr></tbody></table>

### How to use them

All endpoints are `POST`, JSON-bodied, and authenticated with your API key in the `apikey` header — identical to every other Nansen API endpoint.

Each request carries a date "anchor":

* **Snapshot endpoints** take a single `as_of_date` (`YYYY-MM-DD`) — "show me the state on this day."
* **Window endpoints** take a `date_from` + `as_of_date` pair — "show me everything that happened between these two dates." ISO timestamps are accepted; date-only values are treated as UTC midnight.

#### Example: Top holders on a specific date

```bash
curl -X POST "https://api.nansen.ai/api/v1beta1/tgm/historical-top-holders" \
  -H "Content-Type: application/json" \
  -H "apikey: $NANSEN_API_KEY" \
  -d '{
    "chain": "ethereum",
    "token_address": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599",
    "as_of_date": "2024-12-31",
    "label_type": "all",
    "pagination": {"page": 1, "per_page": 100}
  }'
```

### Get started

* **Base URL:** `https://api.nansen.ai`
* **Auth:** `apikey` header
* **Docs & schemas:** the full OpenAPI specification covers every request and response field
* **Beta status:** these endpoints are in V1 Beta — schemas are stable, but we welcome feedback as we iterate

Already a Nansen API customer? Your existing key works against `/api/v1beta1/` today. Reach out to your account contact for example notebooks, backtesting templates, and volume pricing.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nansen.ai/api/backtesting-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.