canonical: https://jentic.com/apis/nansen.ai/nansen

# Nansen API

Nansen is an on-chain analytics platform that surfaces wallet behaviour, smart-money flows, and token-level intelligence across major EVM and non-EVM blockchains. Its API exposes 54 endpoints covering smart-money trades and holdings, address profiling and PnL, Token God Mode (TGM) flows and holders, perpetual positions, prediction markets, and a token screener. This page describes a curated, agent-optimized Jentic specification of those 54 operations; Nansen also publishes its own OpenAPI document, which the FAQ below cites. Agents can classify wallets, track flows in and out of specific tokens, and assemble dashboards or alerts grounded in labelled wallet data.

## For AI agents

Query labelled on-chain wallet data, smart-money flows, address PnL, and token holders across major chains. POST-based with API key auth.

## Scope

Does not handle order execution, custody, or off-chain market data - use for on-chain wallet analytics, smart-money tracking, and token holder intelligence only.

## Capabilities

- Track smart-money inflows and outflows for a token across DEX, perpetual, and DCA venues
- Profile any wallet address with PnL summary, current and historical balances, and counterparties
- Retrieve labelled wallet identities (CEXs, MEV bots, fund desks, smart money) for an address
- Surface Token God Mode flows, holder distributions, and PnL leaderboards for a specific token
- Screen tokens by performance, holder behaviour, and smart-money activity
- Pull perpetual positions and trades for an address across major perp venues

## Use cases

### On-Chain Smart-Money Tracking

Crypto research desks and trading agents follow Nansen's labelled smart-money cohorts to spot accumulation and distribution before price action follows. The `/api/v1/smart-money/netflow` and `/api/v1/smart-money/dex-trades` endpoints return aggregated and per-trade data so a strategy can detect when a labelled cohort is rotating into a token. Combined with the labels endpoint this turns raw on-chain data into actionable signals.

Example prompt: POST `/api/v1/smart-money/netflow` with token=USDC and a 24h window, then alert if netflow exceeds $5M positive.

### Wallet Profiling and Risk Checks

Compliance and trading platforms profile counterparty wallets before approving transfers or fills. The `/api/v1/profiler/address`/* family of endpoints returns the address's PnL, current balance, related wallets, counterparties, and labels - including Nansen's premium labels - letting an agent quickly answer 'who is this address and how do they trade'. PnL summary alone often determines whether a wallet is treated as a sophisticated counterparty.

Example prompt: POST `/api/v1/profiler/address/labels` with an address and reject the transfer if any label includes 'sanctioned' or 'mixer'.

### Token God Mode Holder Analytics

Token issuers and analysts use Token God Mode to understand the holder base of a specific asset - flows in and out, top buyers and sellers, PnL leaderboard, and DEX trade activity. Calling `/api/v1/tgm/flows` and `/api/v1/tgm/holders` together gives a single report combining net token movement, holder concentration, and best-performing wallets, which can drive treasury and tokenomics decisions.

Example prompt: POST `/api/v1/tgm/holders` for a target token and surface the top 25 holders with their historical balance trend.

### AI Agent Crypto Intelligence

An AI trading or research assistant invoked through Jentic asks open questions like 'is smart money buying this token?' Jentic translates the intent into a Nansen operation, calls it with the API key from the vault, and returns structured data the agent can summarise, chart, or feed into trading logic. The agent never sees the raw apiKey header value.

Example prompt: Search Jentic for 'smart money netflow for token', load POST `/api/v1/smart-money/netflow`, and execute it for a target token over a 7-day window.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/smart-money/netflow` | Smart-money net inflow and outflow for a token |
| POST | `/api/v1/smart-money/dex-trades` | Smart-money DEX trade activity for a token |
| POST | `/api/v1/profiler/address/pnl-summary` | PnL summary for an address |
| POST | `/api/v1/profiler/address/labels` | Labels attached to an address |
| POST | `/api/v1/profiler/address/premium-labels` | Premium labels for an address |
| POST | `/api/v1/tgm/flows` | Token God Mode flow analytics for a token |
| POST | `/api/v1/tgm/holders` | Top holders for a token |
| GET | `/api/v1/account` | Read API key account info |

## Key resources

- **Smart Money** — Netflow, DEX trades, perp trades, DCAs, holdings, and historical holdings for labelled smart-money cohorts
- **Profiler** — Address PnL, balances, counterparties, labels, premium labels, related wallets, and perp activity
- **Token God Mode** — Flows, who-bought-sold, DEX trades, transfers, holders, and PnL leaderboards for a specific token
- **Account** — Account info and API key usage details

## Why Jentic

- **Setup:** Wiring Nansen by hand means holding its apiKey header, setting it on every call against api.nansen.ai, and mapping the smart-money, profiler, and token-holder calls yourself. Through Jentic you install once, import the Nansen API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Nansen sends the wallet or token address in the request body rather than a resource id in the URL path, so scope the agent to the operations it needs, such as reading smart-money netflow or an address PnL summary, and leave others out of the allowed set unless you include them.
- **Credential handling:** Your Nansen apiKey is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'smart money netflow' or 'address pnl summary', and Jentic returns the matching Nansen operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **CoinGecko API** — Token price, market data, and metadata across thousands of crypto assets
- **CoinMarketCap API** — Crypto market data and rankings
- **ComplyAdvantage API** — AML and sanctions screening for counterparties

## FAQ

### Which OpenAPI specification does this Nansen API page describe?

A curated, agent-optimized Jentic specification covering 54 Nansen operations. Nansen also publishes its own OpenAPI documentation at https://api.nansen.ai/openapi.json, which covers a broader surface of the API than the 54 operations described here. Jentic keeps this narrower variant validated against the live API and agent-ready, so it is a scoped subset rather than a replacement for the vendor document. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Nansen API use?

Nansen uses an API key passed in the apiKey HTTP header on every request. When called through Jentic the key is encrypted in your Jentic One instance and the agent receives only a scoped execution token; the raw apiKey value never enters the agent's context.

### Can I retrieve a wallet's PnL with the Nansen API?

Yes. POST `/api/v1/profiler/address/pnl-summary` returns an aggregate PnL view for an address, and POST `/api/v1/profiler/address/pnl` returns the granular trade-level PnL. Combine with `/api/v1/profiler/address/historical-balances` to chart a wallet's portfolio value over time.

### What are the rate limits for the Nansen API?

Rate limits are tier-dependent and are not declared in the OpenAPI spec. Use GET `/api/v1/account` to read your current account configuration and stay within the per-minute and per-day quotas reported there. Cache analytics responses where possible - flow and holder data is expensive to compute server-side.

### How do I track smart-money flows for a token through Jentic?

Run jentic.search('smart money netflow for token'), select POST `/api/v1/smart-money/netflow`, then jentic.execute with the token symbol or contract and a time window. Jentic returns the structured netflow object so the agent can compare inflow vs outflow and decide whether to alert or rebalance.

### Does the Nansen API support perpetual position data?

Yes. POST `/api/v1/profiler/perp-positions` and POST `/api/v1/profiler/perp-trades` return open perp positions and historical perp trades for an address, useful for monitoring leveraged exposure of tracked wallets. The `/api/v1/smart-money/perp-trades` endpoint covers the full smart-money cohort.

### Can I limit what my agent is allowed to do with the Nansen API?

Yes. Because you run Jentic One yourself, your own rules decide which Nansen operations and credentials the agent may use. Since Nansen passes the wallet or token address in the request body rather than as a resource id in the URL path, you scope the agent to only the operations it needs, such as POST `/api/v1/smart-money/netflow` or POST `/api/v1/profiler/address/pnl-summary`, and leave everything else out of the allowed set. The stored apiKey is injected at execution time, so the agent can call only the operations you permitted and never sees the raw key.