| Status Code | Meaning | What to Do |
|---|---|---|
| 400 | Bad Request: Malformed request, invalid parameters or format | Check your request syntax and parameters |
| 401 | Unauthorized: Authentication failed (missing, invalid, or expired token) | Obtain or refresh your API Key |
| 402 | x402: Payment Required | Please make the payment for API request and try again |
| 403 | Forbidden: Auth succeeded, but no permission for resource | Ensure your account has access rights |
| 404 | Not Found: Resource or endpoint does not exist | Verify the endpoint path and resource identifiers |
| 422 | Unprocessable Content | Please verify your parameters |
| 429 | Too Many Requests: Rate limit exceeded | Slow down requests; respect rate limits |
| 500 | Internal Server Error: Unexpected server issue | Try again later; contact support if persistent |
| 504 | Gateway Timeout: Backend server did not respond in time | Retry after a short wait; check for heavy queries |
# Agentic Payments Call the Nansen API without an account, subscription, or API key. Pay per request in USDC and get data back. Agentic payments let machines: AI agents, scripts, bots access Nansen data on demand, settling each call on-chain. No provisioning, no key management, no long-lived credentials. Sign a payment, make the request, get the response. Nansen supports two agentic payment rails on the same `/api/v1/*` endpoints: * **x402:** The open HTTP payment standard. USDC on Base or Solana. Broad client-side tooling and SDK support. Best for agents already operating on Base or Solana. * **MPP on Tempo:** Machine Payments Protocol settlement on Tempo mainnet. Sub-cent per-call pricing. Best for agents already settling on Tempo or optimising for per-call cost. Both rails hit the same endpoints and return identical response bodies. An agent can mix and match x402 for some calls, MPP for others. ### Supported endpoints All Pro-tier endpoints accept agentic payments, except: * `/api/v1/labels/*` — Pro subscription only (proprietary entity data). Pricing is tiered by endpoint: | Tier | Price | Examples | | ----------- | ---------- | --------------------------------------------------------------------- | | Basic | $0.01/call | Token Screener, Wallet Balances, Transactions, PnL, DEX Trades, Flows | | Premium | $0.05/call | Counterparties, Holders, PnL Leaderboard, Perp Leaderboard | | Smart Money | $0.05/call | SM Net Flow, SM Inflows, SM Holdings, SM DEX Trades | The full endpoint list and tier breakdown is on the [x402](https://claude.ai/chat/x402#pricing) page. MPP uses the same tiers and prices. ### Discovery Fetch `/.well-known/x402` to see every priced endpoint, its cost, and which payment protocols it supports: ```bash curl -s https://api.nansen.ai/.well-known/x402 | jq ``` The `paymentProtocols` field lists the rails available for each endpoint (`x402`, `mpp`, or both). # MPP (Tempo) Pay-per-call access to the Nansen API using USDC on Tempo, via the Machine Payments Protocol (MPP). Any `/api/v1/*` endpoint that supports pay-per-call can be invoked anonymously by signing a Tempo payment instead of presenting an API key — no account, no subscription, no bearer token. MPP is one of two agentic payment rails supported by Nansen; the other is x402. The same endpoints accept both. ### When to use MPP * Agents or machines that need ad-hoc access to a handful of calls without provisioning an API key. * Integrations that already settle on Tempo and want sub-cent per-call pricing on the same rail. * Environments where storing a long-lived API key is undesirable. ### Quick start Install the Tempo CLI and log in to a funded mainnet wallet: ```bash curl -fsSL https://tempo.xyz/install | bash tempo wallet login tempo wallet whoami # expect "ready": true ``` Then call any priced endpoint with `Authorization: Payment`: ```bash tempo request -X POST https://api.nansen.ai/api/v1/tgm/indicators \ -H 'Content-Type: application/json' \ -H 'Authorization: Payment' \ --json '{"chain":"ethereum","token_address":"0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9"}' ``` The CLI handles the challenge/sign/retry loop for you. On success you get the endpoint's JSON response plus a `Payment-Receipt` header. ### How it works ``` Client Nansen API | | | POST /api/v1/... | | Authorization: Payment | | (no signed credential yet) | |------------------------------------>| | | | 402 Payment Required | | WWW-Authenticate: Payment ... | |<------------------------------------| | | | Sign challenge with Tempo wallet | | | | POST /api/v1/... | | Authorization: Payment
Base: Coinbase CDP
Solana: Payai
| Endpoint | Credit | Description |
|---|---|---|
| smart-money/netflows | 5 | Provides net flow of tokens bought/sold by Smart Money addresses |
| smart-money/holdings | 5 | Holdings of tokens by Smart Money addresses. |
| smart-money/historical-holdings | 5 | All Historical Holdings of Smart Money Wallets |
| smart-money/dex-trades | 5 | All dex trades of smart money traders in the last 24h |
| smart-money/dcas | 5 | All Jupiter DCAs started by Smart Money Wallets on Solana |
| smart-money/perp-trades | 5 | Track what smart money wallets are trading on Hyperliquid |
| Endpoint | Credit | Description |
|---|---|---|
| agent/fast | 200 | Ask Nansen Agent any question in fast mode |
| agent/expert | 750 | Ask Nansen Agent any question in expert mode |
| Endpoint | Credit | Description |
|---|---|---|
| address/current-balance | 1 | Current Token balances of an address |
| profiler/address/historical-balances | 1 | Historical holdings of a wallet address |
| profiler/perp-positions | 1 | Fetch current positions, PnL and account health of a wallet |
| profiler/address/transactions | 1 | List of transactions made by an address |
| profiler/perp-trades | 1 | Get all Hyperliquid trades of a wallet |
| profiler/address/related-wallets | 1 | List of related wallets and its first degree relation |
| profiler/address/pnl-summary | 1 | Trade summary including top 5 trades |
| profiler/address/pnl | 1 | List of Past Trades and their performance made by the address |
| profiler/address/counterparties | 5 | Top Counterparties a wallet has interacted with |
| perp-leaderboard | 5 | Get a list of most profitable Hyperliquid addresses |
| /profiler/address/labels (Common labels) | 100 | Address and list of all its labels |
| /profiler/address/labels (Premium labels) | 500 | Address and list of all its labels |
| Endpoint | Credits | Description |
|---|---|---|
| tgm/token-screener | 1 | A token screening endpoint that provides real-time analytics and insights across multiple blockchain networks. |
| tgm/perp-screener | 1 | Discover and screen tokens on Hyperliquid with the highest volume and smart money activity. |
| tgm/flow-intelligence | 1 | Summary of token flows across Smart Money, exchanges, Top PnL Traders, Public Figures, Whales, Fresh Wallets |
| tgm/holders (Premium labels: 150) | 5 / 150 | Balance of top addresses, smart money, exchanges, public figures and whales that can be queried by address or by entity. |
| tgm/perp-positions (Premium labels: 150) | 5 / 150 | See all open positions for a specific perp token including leverage, PnL, and liquidation prices |
| tgm/flows | 1 | Total Inflow and outflow of a token from smart money, exchanges, public figures or whales. |
| tgm/who-bought-sold | 1 | Recent buyers and sellers of a token summarised |
| tgm/perp-trades | 1 | View trading history for a specific perp token over a time period |
| tgm/dex-trades | 1 | All DEX Trades of a Token |
| tgm/transfers | 1 | Top Token Transfers of a token |
| tgm/jup-dca | 1 | List of all Jupiter DCA orders of a token on Solana |
| tgm/pnl-leaderboard (Premium labels: 150) | 5 / 150 | List of addresses and their total realised and unrealised PnL |
| tgm/perp-pnl-leaderboard (Premium labels: 150) | 5 / 150 | List of addresses and their PnL for a specific token on Hyperliquid |
| tgm/token-information | 1 | Get stats about Token Marketcap, Volume, Holders, Traders, etc |
| tgm/indicators | 5 | Get risk and reward indicators for a specific token. |
| tgm/token-ohlcv | 1 | Get unified OHLCVdata for tokens |
| Endpoint | Credits | Description |
|---|---|---|
| prediction-market/categories | 1 | Aggregated stats for all categories |
| prediction-market/market-screener | 1 | Browse and all Polymarket prediction markets. |
| prediction-market/event-screener | 1 | Browse and filter Polymarket events |
| prediction-market/orderbook | 1 | Get bid/ask orderbook for a market |
| prediction-market/ohlcv | 1 | Get 1-hour OHLCV for a market |
| prediction-market/trades-by-market | 1 | Get recent trades for a market |
| prediction-market/trades-by-address | 1 | Trades for a wallet across all markets |
| prediction-market/pnl-by-address | 1 | PnL for a wallet across all markets |
| prediction-market/address-summary | 1 | Get PnL, win rate and age of a wallet active on Polymarket |
| prediction-market/top-holders | 5 | Get the largest position holders for market |
| prediction-market/position-detail | 5 | Get per-token position data for all holders in a specific market |
| prediction-market/pnl-by-market | 5 | PnL for all traders in a specific market |
| Endpoint | Credits | Description |
|---|---|---|
| portfolio/defi-holdings | 1 | Track DeFi positions of all addresses |
| Usecase | Required Parameters | Optional Filters | Sorting Logic | Expected Output |
|---|---|---|---|---|
| Find what funds are buying on Solana | chains: ["Solana"] | include_smart_money_labels: ["Fund"] | [{"field":"net_flow_7d_usd", "direction":"DESC"}] | Returns top tokens by funds, sorted by 7D inflow |
| Top DeFi tokens that Smart Money are selling | chains: ["ethereum"] | token_sectors: ["DeFi"] | [{"field":"net_flow_7d_usd", "direction":"ASC"}] | Returns tokens with highest net outflow in DeFi sector |
| Usecase | Required Parameters | Filters | Sorting Logic | Expected Output |
|---|---|---|---|---|
| View smart trader token holdings across chains | chains = ["ethereum", "solana"] | N/A | order_by = [{field: "value_usd", direction: "DESC"}] | Aggregated list of tokens held by smart traders on specified chains |
| Monitor top accumulating tokens this week | chains = "all", | filters = {balance_24h_percent_change: {min: 10}}, | order_by = [{field: "balance_24h_percent_change", direction: "DESC"}] | Tokens showing largest recent increases in smart trader holdings |
| Screen for newly held tokens with threshold value | chains = "all", | filters = {token_age_days: {max: 30}, value_usd: {min: 10000}} | order_by = [{field: "token_age_days", direction: "ASC"}] | Newly acquired tokens by smart money, filtered by age and min USD value |
| Usecase | Required Parameters | Optional Filters | Expected Output |
|---|---|---|---|
| Check current holdings for a single address | address = "0x28c6c06298d514db089934071355e5743bf21d60", chain = "ethereum" | hide_spam_token = true, | List of tokens with amounts, USD values, and chain info for the address |
| View entity-wide portfolio (e.g., Vitalik Buterin) | entity_name = "Vitalik Buterin", chain = "all" | hide_spam_token = true | Aggregated balances for entity across all wallets, showing holdings per chain |
| Usecase | Required Parameters | Optional Filters | Expected Output |
|---|---|---|---|
| Check current holdings for a single address | address = "0x28c6c06298d514db089934071355e5743bf21d60", chain = "ethereum" | hide_spam_token = true, | List of tokens with amounts, USD values, and chain info for the address |
| View entity-wide portfolio (e.g., Coinbase) | entity_name = "Coinbase", chain = "all" | hide_spam_token = true | Aggregated balances for entity across all wallets, showing holdings per chain |
| Usecase | Required Parameters | Expected Output |
|---|---|---|
| Get counterparties for a single address | address = "0x28c6c06298d514db089934071355e5743bf21d60", chain = "ethereum", group_by: "address" | List of counterparties with interaction stats (volume, frequency, timing) |
| Get counterparties for an entity (e.g., Coinbase) | entity_name = "Coinbase", chain = "all", group_by: "entity" | Aggregated counterparties across all entity wallets with interaction stats |
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| tier | string | No | all tiers | Filter by tier: green, ice, north, star |
| page | integer | No | 1 | Page number (min: 1) |
| recordsPerPage | integer | No | 10 | Results per page (min: 1, max: 10,000) |
| Name | Type | Required | Description |
|---|---|---|---|
| address | string | Yes | EVM or Solana wallet address. Case-insensitive. |
Tier name determined by points thresholds.
Valid tier values are: "none," "green," "ice," "north," or "star." Addresses not on the leaderboard return "none."
| Usecase | Required Parameters | Optional Filters | Expected Output |
|---|---|---|---|
| Check current perp positions for a single address | address ="0xa312114b5795dff9b8db50474dd57701aa78ad1e" | filters ={"position_value_usd": {"min": 1000}} | List of open perpetual positions with entry price, mark price, leverage, PnL, and margin info for the address |
| Get all perp positions with negative PnL for an address | address ="0xa312114b5795dff9b8db50474dd57701aa78ad1e" | filters ={"unrealized_pnl_usd": {"max": 0}} | List of positions with negative unrealized PnL |
| Usecase | Required Parameters | Optional Filters | Expected Output |
|---|---|---|---|
| Fetch all perp trades for an address within a specific date range | address ="0x45d26f28196d226497130c4bac709d808fed4029" date ={ "from": "2025-10-01", "to": "2025-10-10" } | (none needed for basic usage) | List of trades with timestamps, price, size, token, direction (Long/Short), action (Open/Close), and fees for the address |
| Analyze high-value trades with closed PnL details | address ="0x45d26f28196d226497130c4bac709d808fed4029" date ={ "from": "2025-10-01", "to": "2025-10-10" } | filters ={"value_usd": {"min": 1000}} | List of trades above $1,000 with closed PnL, fees paid, order IDs, and asset symbols |
| Track all short trades and compare performance by token | address ="0x45d26f28196d226497130c4bac709d808fed4029" date ={ "from": "2025-10-01", "to": "2025-10-10" } | filters ={"type": "Short"} order_by =[{"direction": "DESC", "field": "closed_pnl"}] | All short trades, sorted by closed profit, allowing analysis of which tokens and trades delivered the best results |
| Usecase | Required Parameters | Optional Filters | Expected Output |
|---|---|---|---|
| Find top perpetual traders in a specific date range | date ={ "from": "2025-10-14", "to": "2025-10-15" } | pagination ={ "page": 1, "per_page": 10 } | List of the most profitable perpetual traders (addresses and labels) with their total PnL, ROI (%), and account values in the date range |
| Filter leaderboard for high-value profitable accounts | date ={ "from": "2025-10-14", "to": "2025-10-15" } | filters ={ "account_value": { "min": 10000 }, "total_pnl": { "min": 1000 } } | Leaderboard limited to traders with $10k+ account value and $1k+ profit, for easier benchmarking |
| Show only smart money leaders (filtered by trader address label) | date ={ "from": "2025-10-14", "to": "2025-10-15" } | filters ={ "trader_address_label": "Smart Money" } | Leaderboard showing only traders identified as Smart Money, with PnL, ROI, and account value for each |
| Usecase | Required Parameters | Optional Filters | Expected Output |
|---|---|---|---|
| Screen for perps with net buy/sell pressure and strong fundamentals | date ={ "from": "2025-10-01T00:00:00Z", "to": "2025-10-06T23:59:59Z" } | filters ={ "buy_sell_pressure": { "min": 100000 }, "open_interest": { "min": 500000 } } | Perps showing high buy/sell pressure and strong open interest, returned with mark price, volume, and trader details |
| Discover perps favored by smart money | date ={ "from": "2025-10-01T00:00:00Z", "to": "2025-10-06T23:59:59Z" } | only_smart_money =true filters ={ "smart_money_volume": { "min": 100000 } } | Perps with the highest smart money volume, including smart money long/short counts, USD position sizes, and assets |
| Usecase | Required Parameters | Optional Filters | Expected Output |
|---|---|---|---|
| Filter for high-profit and high-balance addresses | token_symbol ="ETH" date ={ "from": "2025-10-14", "to": "2025-10-15" } | filters ={ "pnl_usd_realised": { "min": 100000 }, "position_value_usd": { "min": 100000 } } | Only addresses with at least $100k realized PnL and $100k+ in position value are shown |
| Surface only smart money traders for a specific contract | token_symbol ="SOL" date ={ "from": "2025-10-14", "to": "2025-10-15" } | filters ={ "trader_address_label": "Smart Money" } | Leaderboard limited to traders labeled as Smart Money |
| Value | Behavior | Credits Used |
|---|---|---|
true | Returns dbt-sourced premium labels (Smart Money, Fund, etc.) | 150 |
false | Returns free-tier labels only | 5 |
| Tool | Description | Credits |
|---|---|---|
smart_traders_and_funds_token_balances | Smart money holdings & 24h changes | 5 |
smart_traders_and_funds_perp_trades | Smart money perpetual trades (HyperLiquid) | 5 |
token_current_top_holders | Top token holders with labels | 5 |
token_dex_trades | DEX trading activity for a token | 1 |
token_transfers | Token transfer history | 1 |
token_flows | Hourly aggregated token flows by segment | 1 |
token_pnl_leaderboard | Trader PnL rankings for a token | 5 |
token_who_bought_sold | Total bought/sold by address (DEX) | 1 |
token_recent_flows_summary | Flow summary by segment (Smart Money, Whales, etc.) | 1 |
token_discovery_screener | Multi-chain token screening with filters | 1 |
token_ohlcv | OHLCV price data with auto interval | 1 |
token_quant_scores | Quantitative scores for a token | 2 |
nansen_score_top_tokens | Top tokens ranked by Nansen score | 1 |
address_historical_balances | Historical token & native coin balances | 1 |
address_related_addresses | First funders, signers, deployed contracts | 1 |
address_counterparties | Most interacted addresses/entities | 5 |
address_transactions | Recent transactions for an address | 1 |
wallet_pnl_for_token | PnL for a specific token by wallet | 1 |
wallet_pnl_summary | Overall realized PnL for a wallet | 1 |
address_portfolio | Full portfolio overview & DeFi positions | 1 |
general_search | Search tokens, entities, addresses (free) | 0 |
growth_chain_rank | Chain growth rankings by key metrics | 1 |
hyperliquid_leaderboard | Top HyperLiquid traders leaderboard | 9 |
transaction_lookup | Transaction details with transfers (EVM) | 1 |
| Tool Name | Redistribution Status | Notes |
|---|---|---|
smart_traders_and_funds_netflows | ⚠️ Restricted | Approval + Significant Modification |
smart_traders_and_funds_token_balances | 🚫 Prohibited | Not permitted |