> This is part 1 of 2 of the full documentation (pages 1–100 of 148). > The content is paginated: fetch every part to see all of it. > Next part: https://docs.nansen.ai/llms-full.txt/1 > Page index: https://docs.nansen.ai/llms.txt # Introduction Nansen API offers programmatic access to high-quality onchain data and advanced blockchain analytics across numerous networks. The API aims to equip users with the necessary data to gain a competitive edge, identify opportunities, perform due diligence, and make informed decisions within the dynamic crypto market. It effectively translates the complexity of raw blockchain data into actionable intelligence, accessible through a structured API interface. #### Key Capabilities * **Proprietary Data Labeling:** Nansen applies unique, human-readable labels to hundreds of millions of blockchain addresses. These labels identify specific entities such as exchanges, funds, market makers, notable individual investors that allows users to understand who is behind onchain activities, providing crucial context that raw, pseudonymous data lacks. Accessing this labelled data via the API is a core component of Nansen's offering. * **Unique Datasets and Insights:** The API provides access to data points and analytics not readily available elsewhere, such as Smart Money analytics. * **Comprehensive Multi-Chain Coverage:** The API consolidates data from multiple blockchain networks, allowing users to track assets and activities across different ecosystems through a single integration point. These features collectively enable the API to deliver not just data, but contextualized intelligence, transforming raw onchain events into a clearer picture of market dynamics and participant behavior. *** ### Quick Links | Need | Go To | | ------------------ | ---------------------------------------------------------------------------------------- | | API authentication | [/getting-started/authentication](https://docs.nansen.ai/getting-started/authentication) | | Rate limits | [/getting-started/rate-limits](https://docs.nansen.ai/getting-started/rate-limits) | | Error handling | [/getting-started/error-handling](https://docs.nansen.ai/getting-started/error-handling) | | Supported chains | [/reference/chains](https://docs.nansen.ai/reference/chains) | | Filter types | [/reference/filters](https://docs.nansen.ai/reference/filters) | | AI Agent Access | [/getting-started/agents](https://docs.nansen.ai/getting-started/agents) | #### API Endpoints | Category | Path | | ------------------ | ------------------------------------------------------------------------- | | Overview | [/api/overview](https://docs.nansen.ai/api/overview) | | Smart Money | [/api/smart-money](https://docs.nansen.ai/api/smart-money) | | Profiler | [/api/profiler](https://docs.nansen.ai/api/profiler) | | Token Screener | [/api/token-god-mode](https://docs.nansen.ai/api/token-god-mode) | | Portfolio | [/api/portfolio](https://docs.nansen.ai/api/portfolio) | | Points | [/api/points](https://docs.nansen.ai/api/points) | | Hyperliquid | [/api/hyperliquid](https://docs.nansen.ai/api/hyperliquid) | | Agent | [/api/v1/agent](https://docs.nansen.ai/api/agent) | | Prediction Markets | [/api/v1/prediction-market](https://docs.nansen.ai/api/prediction-market) | #### Connectors & MCP | Category | Path | | ---------------------------------- | -------------------------------------------------------------------- | | Overview | [/mcp/overview](https://docs.nansen.ai/mcp/overview) | | Connectors (ChatGPT, Claude, Grok) | [/mcp/connectors](https://docs.nansen.ai/mcp/connectors) | | Manually Connecting to MCP | [/mcp/connecting](https://docs.nansen.ai/mcp/connecting) | | Full Tool Catalog | [/mcp/connecting/tools](https://docs.nansen.ai/mcp/connecting/tools) | #### Guides | Tutorial | Path | | -------------------------- | ---------------------------------------------------------------------------------- | | Use case Templates | [/guides/templates](https://docs.nansen.ai/guides/templates) | | Data Redistribution Guides | [/guides/redistribution-guide](https://docs.nansen.ai/guides/redistribution-guide) | # Getting Started Welcome to the Nansen API. This guide will help you get up and running quickly. ### Prerequisites * A Nansen account with API access * An API key from your [Nansen Dashboard](https://app.nansen.ai) or through [Agent Setup Link](https://app.nansen.ai/auth/agent-setup) ### Quick Start #### 1. Set Up Authentication All API requests require your API key in the `apikey` header: ```bash curl -X POST 'https://api.nansen.ai/api/v1/smart-money/holdings' \ -H 'Content-Type: application/json' \ -H 'apikey: YOUR_API_KEY' \ -d '{"chains": ["ethereum"]}' ``` #### 2. Make Your First Request ```python import httpx response = httpx.post( "https://api.nansen.ai/api/v1/smart-money/holdings", headers={ "Content-Type": "application/json", "apikey": "YOUR_API_KEY" }, json={ "chains": ["ethereum"], "pagination": {"page": 1, "per_page": 10} } ) print(response.json()) ``` #### 3. Understand the Response ```json { "data": [ { "chain": "ethereum", "token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933", "token_symbol": "PEPE", "value_usd": 15000000.50, "holders_count": 1250, "balance_24h_percent_change": 5.25 } ], "pagination": { "page": 1, "per_page": 10, "is_last_page": false } } ``` ### Next Steps * Authentication - Detailed auth setup * Rate Limits - Understand API limits * Credits System - How credits work * Pagination - Handle large datasets * Error Handling - Handle errors gracefully * Best Practices - Optimize your integration # Authentication ### Overview The Nansen API uses API key authentication. All requests must include your API key in the `apikey` header, unless you pay per request with [Agentic Payments](/getting-started/agentic-payments) (x402 or MPP). The OpenAPI specification lists those payment rails as security alternatives on each eligible operation. ### Getting Your API Key 1. Log in to your [Nansen Account](https://app.nansen.ai/auth/agent-setup) 2. Generate a new API key ### Using Your API Key #### Header Format ``` apikey: YOUR_API_KEY ``` HTTP header names are case-insensitive, but Nansen docs use lowercase `apikey` as the canonical form. #### curl Example ```bash curl -X POST 'https://api.nansen.ai/api/v1/smart-money/holdings' \ -H 'Content-Type: application/json' \ -H 'apikey: YOUR_API_KEY' \ -d '{"chains": ["ethereum"]}' ``` #### Python Example ```python import httpx headers = { "Content-Type": "application/json", "apikey": "YOUR_API_KEY" } response = httpx.post( "https://api.nansen.ai/api/v1/smart-money/holdings", headers=headers, json={"chains": ["ethereum"]} ) ``` #### Python with Environment Variable ```python import os import httpx API_KEY = os.environ.get("NANSEN_API_KEY") headers = { "Content-Type": "application/json", "apikey": API_KEY } response = httpx.post( "https://api.nansen.ai/api/v1/smart-money/holdings", headers=headers, json={"chains": ["ethereum"]} ) ``` ### Authentication Errors Authentication failures handled by the API use the standard error envelope described in [Error Handling](/getting-started/error-handling). A key rejected by the gateway is the exception described below. #### 401 Unauthorized Returned when the API key is missing, invalid, or revoked. There are two bodies to expect. A keyless request to an API-key-only endpoint returns the full envelope, with `code` set to `unauthenticated`: ```json { "error": "Unauthorized", "message": "API key required. This endpoint does not support paid access.", "code": "unauthenticated", "status": 401, "request_id": "ea100706f73d3b63e4451a38ece4014f", "doc_url": "https://docs.nansen.ai/getting-started/error-handling#unauthenticated" } ``` A key that is present but not recognised is rejected up front, before the request is processed, so that response carries a `message` only and no `code`: ```json { "message": "Invalid API key. Manage your keys at https://app.nansen.ai/api?tab=api" } ``` Branch on the HTTP status first — a 401 always means authentication failed — and read `code` only when it is present. Endpoints that accept [Agentic Payments](/getting-started/agentic-payments) answer a keyless request with `402 Payment Required` and a payment challenge rather than a 401. **Solutions:** * Verify your API key is correct * Ensure the header name is `apikey` (lowercase) * Check that the key hasn't been revoked #### 403 Forbidden Returned when the API key is valid but not permitted to call the endpoint. The body is the same envelope shown above with `"status": 403`; the `code` field names the specific reason — `forbidden`, `plan_upgrade_required`, or `insufficient_credits`. See [Error Handling](/getting-started/error-handling) for what each one means. **Solutions:** * Verify your subscription tier includes access to this endpoint * Contact support to upgrade your plan ### Key Management If your key is compromised: 1. Immediately revoke it in your dashboard 2. Generate a new key 3. Update all applications using the old key # AI Agent Access Connect your AI agent to Nansen's blockchain data API in under a minute. ### Get Started [**Setup URL**](https://app.nansen.ai/auth/agent-setup) 1\. Your agent will ask you to visit the setup page 2\. Sign in with your Nansen account 3\. Copy the message shown 4\. Paste it back to your agent \ Your agent saves the key and handles everything else automatically.
# Rate Limits ### Overview The Nansen API applies rate limits per API key. Limits vary by subscription tier and are measured over both short and sustained windows. ### Plan limits | Plan | Per second | Per minute | | -------------------- | ----------: | -------------: | | Free | 15 requests | 300 requests | | Pro (all paid plans) | 75 requests | 1,500 requests | ### Per-endpoint limits These endpoints have an additional per-minute limit for both Free and Pro plans: | Endpoint | Limit | | ----------------------------------- | -----------------: | | `GET /api/v1/search/token-sectors` | 60 requests/minute | | `POST /api/v1/tgm/perp-trades` | 60 requests/minute | | `POST /api/v1/profiler/perp-trades` | 5 requests/minute | | `POST /api/v1/search/web-search` | 15 requests/minute | | `POST /api/v1/search/web-fetch` | 15 requests/minute | ### Rate-limit response headers Responses may include two layers of rate-limit headers: * `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`, together with `X-RateLimit-Limit-Second`, `X-RateLimit-Remaining-Second`, `X-RateLimit-Limit-Minute`, and `X-RateLimit-Remaining-Minute`, describe overall limits. * Bare `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` describe the most constrained app-enforced window, which may be plan-wide or endpoint-specific. * Enforced `429` responses include `X-Nansen-RateLimit-Scope`. Its current values are `second` for a global per-second window, `minute` for a global per-minute window, and `endpoint` for an endpoint-specific window. Treat these values as an open set: do not reject unknown future values; use the generic `429` behavior and honor `Retry-After`. When both layers are present, self-throttle using the smaller of `RateLimit-Remaining` and `X-RateLimit-Remaining`. If the API returns a **429 Too Many Requests** response, honor `Retry-After` before retrying. ### Exceeding rate limits If you exceed a limit, the API returns a **429 Too Many Requests** response. # Credits & Pricing Guide Welcome to our updated API pricing and credit system. We’ve made it easier to get started, scale up, and pay only for what you need. ## Available API Plans We offer two main API plans to fit your needs:
PlanCredits IncludedTop UpsIntended Use
Pro2,000 credits to start,
then a monthly top-up of your included credits back up to 2,000		✅Professional, production, and high volume integrations
Free100 trial credits, then a daily top-up of your included credits to a 10-credit balance✅Brief experimentation and testing
For more information on plan features, visit [our pricing page](https://app.nansen.ai/account/switch-plans). ### Pro Plan Details * Subscription: $49/month (annual) or $69/month (monthly) * Included Credits: a one-time grant of 2,000 credits when you subscribe, then a monthly top-up that brings your included credit balance back up to 2,000 **only if it has fallen below 2,000**. See [How Pro credits are granted and refreshed](#how-pro-credits-are-granted-and-refreshed). * Flexi-Credits: Purchase as many credits as you want, at discounted rates. * Expiry: Purchased credits expire 1 year from purchase. Included plan credits have no expiry date of their own. ### Free Plan Details * 100 one-time credits to try the API. After those are used, a daily top-up brings your included credit balance back up to 10 credits if it has fallen below 10. * Ability to purchase credits * Access all API endpoints available in Pro ## How Pro Credits Are Granted and Refreshed Pro credits work the same way as the Free plan's daily top-up, just monthly and at a higher figure: the Free plan tops your included credit balance back up to 10 credits each day, and the Pro plan tops it back up to 2,000 credits each month. **1. A one-time grant when you subscribe.** Subscribing to Pro grants you 2,000 credits immediately, so you can start building before making your first purchase. **2. A monthly top-up, applied only if your included credits are below 2,000.** On the 1st of each calendar month (shortly after 00:00 UTC) your included credit balance is checked. If it is **below** 2,000, it is raised back up to 2,000. If it is already **at or above** 2,000, nothing is added that month. This is a top-up to a floor, not a recurring grant of 2,000 more credits. Unused credits do not roll over into an ever-growing balance, and the monthly top-up never reduces a balance that is already above the floor. The 2,000 floor is measured against your **included** plan credits only. Purchased top-up credits are held separately: they are never counted toward the floor and never reduce or delay the monthly top-up. If your included balance is below 2,000 on the 1st, it is raised to 2,000 however many purchased credits you are holding, and your purchased balance is left untouched. **3. The refresh date is the calendar month, not your billing date.** The top-up runs on the 1st of the month for everyone. It is not tied to your subscription start date or billing anniversary — if you subscribe on the 20th, your first monthly top-up is on the 1st of the following month (and it will only add credits if your included balance is below 2,000 by then). **4. Included credits are spent before purchased credits.** Every request draws down your included plan credits first. Purchased top-up credits are only used once your included credits reach zero. Among purchased credits, the batch expiring soonest is used first, so credits are not left to expire while newer ones are spent. ### Worked Examples Each row shows a Pro account on the 1st of the month, immediately before and after the monthly top-up. Only the included-credits column decides whether a top-up happens. | Included credits left | Purchased credits left | Top-up adds | Included after | Total after | | --------------------- | ---------------------- | ----------- | -------------- | ----------- | | 0 | 0 | 2,000 | 2,000 | 2,000 | | 500 | 0 | 1,500 | 2,000 | 2,000 | | 2,000 | 0 | 0 | 2,000 | 2,000 | | 0 | 1,200 | 2,000 | 2,000 | 3,200 | | 0 | 5,000 | 2,000 | 2,000 | 7,000 | | 2,000 | 3,000 | 0 | 2,000 | 5,000 | ## Endpoint Credit Cost Credit costs are structured to reflect the value of the data you’re accessing. Foundational data is inexpensive to encourage frequent use, while our proprietary, alpha-generating data costs more. The endpoint names below omit the common `/api/v1/` prefix. For example, `prediction-market/pnl-by-market` refers to `POST /api/v1/prediction-market/pnl-by-market`. A cost of `0` means the request does not use plan credits. The endpoint is still subject to the plan’s access and usage limits.
EndpointFreePro
account00
search/general00
search/entity-name00
search/token-sectors10
profiler/address/current-balance11
profiler/address/historical-balances11
profiler/address/transactions11
profiler/address/related-wallets11
profiler/address/pnl-summary11
profiler/address/pnl11
profiler/address/first-funder11
profiler/perp-pnl-summary11
profiler/perp-positions11
profiler/perp-trades11
profiler/dex-trades11
portfolio/defi-holdings11
tgm/transfers11
tgm/jup-dca11
tgm/flow-intelligence11
tgm/who-bought-sold11
tgm/dex-trades11
tgm/flows11
tgm/token-information11
tgm/token-ohlcv11
tgm/perp-trades11
tgm/position-intelligence11
perp-screener11
token-screener11
transaction-with-token-transfer-lookup11
chains/chain-rank11
smart-money/historical-holdings11
nansen-score/top-tokens11
prediction-market/ohlcv11
prediction-market/orderbook11
prediction-market/trades-by-market11
prediction-market/trades-by-address11
prediction-market/market-screener11
prediction-market/event-screener11
prediction-market/pnl-by-address11
prediction-market/address-summary11
prediction-market/categories11
smart-money/netflow55
smart-money/holdings55
smart-money/dex-trades55
smart-money/dcas55
smart-money/pnl-leaderboard55
smart-money/perp-trades55
profiler/address/counterparties55
profiler/address/counterparties/batch55
tgm/holders †55
tgm/pnl-leaderboard †55
tgm/indicators55
tgm/perp-positions55
tgm/perp-pnl-leaderboard †55
perp-leaderboard †55
prediction-market/top-holders55
prediction-market/pnl-by-market55
prediction-market/position-detail55
ra-agent/posts-by-token55
ra-agent/posts-by-user55
search/web-search55
search/web-fetch2020
profiler/address/labels (common labels)100 (0 if data is empty)100 (0 if data is empty)
profiler/address/premium-labels500 (0 if data is empty)500 (0 if data is empty)
agent/fast200200
agent/expert750750
tgm/historical-dex-trades55
tgm/historical-who-bought-sold55
tgm/historical-token-flow-summary55
tgm/historical-token-ohlcv55
token-screener/historical55
profiler/address/historical-token-balances55
profiler/address/historical-transactions55
profiler/historical-transaction-lookup55
tgm/historical-top-holders2525
tgm/historical-pnl-leaderboard2525
tgm/historical-token-quant-scores2525
smart-money/historical-token-balances2525
tgm/historical-token-recent-flows-summary-perps55
† Costs 150 credits per call when `premium_labels=true` is passed. ## FAQs **Do my 2,000 Pro credits refresh every month, or is it a one-time grant?** Both, in a sense. You get a one-time grant of 2,000 credits when you subscribe. After that, a monthly top-up on the 1st of each calendar month (UTC) brings your included credit balance back up to 2,000 — but only if it has fallen below 2,000. It is not an extra 2,000 credits every month. See [How Pro credits are granted and refreshed](#how-pro-credits-are-granted-and-refreshed). **Do unused credits carry over to the next month?** Included plan credits do not accumulate above the 2,000 floor: the monthly top-up raises a below-floor balance up to 2,000 rather than adding to it, so months of light usage do not build up a larger allowance. An unused balance is never taken away either — the top-up only ever raises it. Purchased credits are different: they persist until spent, or until they expire 1 year after purchase, and they have no effect on whether your included credits are topped up. **Which credits are used first: my included plan credits or my purchased top-ups?** Included plan credits are always spent first. Purchased top-ups are only drawn on once your included credits reach zero, and the batch expiring soonest is used first. **What happens if I run out of credits?** You can purchase additional credit blocks at any time to ensure your service is not interrupted. **How do I track my credit usage?** You can track your credit usage by visiting this link: # Error Handling API responses are delivered in JSON format. The client applications must parse this JSON to extract the required data. Equally important is handling the HTTP status code returned with each response to determine success or failure. **Common HTTP Status Codes:**
Status CodeMeaningWhat to Do
400Bad Request: Malformed request, invalid parameters or formatCheck your request syntax and parameters
401Unauthorized: Authentication failed (missing, invalid, or expired token)Obtain or refresh your API Key
402x402: Payment RequiredPlease make the payment for API request and try again
403Forbidden: Auth succeeded, but no permission for resourceEnsure your account has access rights
404Not Found: Resource or endpoint does not existVerify the endpoint path and resource identifiers
422Unprocessable ContentPlease verify your parameters
429Too Many Requests: Rate limit exceededSlow down requests; respect rate limits
500Internal Server Error: Unexpected server issueTry again later; contact support if persistent
504Gateway Timeout: Backend server did not respond in timeRetry after a short wait; check for heavy queries
## Error Codes Except for HTTP 402 payment challenges, error responses carry a structured JSON body with a stable, machine-readable `code` field: ```json { "error": "Missing field", "message": "Required field 'body -> chain' is missing. Must be a valid chain name, e.g., 'ethereum', 'solana', 'bnb'", "code": "missing_field", "status": 422, "request_id": "req-6b1f6f3f2b724e4bb8b2f6d0a9e4c1aa", "doc_url": "https://docs.nansen.ai/getting-started/error-handling#missing_field", "param": "chain" } ``` * `code` — a stable identifier for the error; safe to branch on in client code. * `status` — the HTTP status code, repeated in the body. * `request_id` — include this when contacting support. * `doc_url` — links back to this page, anchored to the specific code. * `param` — only present when the error relates to a specific request field. * `retry_after` — only present when the request can be retried after a delay, in seconds. The same value is sent in the `Retry-After` response header. **All error codes:**
CodeMeaningTypical causeRetryable
missing_fieldA required field is missing from the requestA required body field (e.g. chain, date) was not providedNo — add the field
unknown_fieldThe request contains a field the endpoint does not recognizeA typo, a camelCase name (the API uses snake_case), or page/per_page outside the pagination objectNo — fix the field name
invalid_field_valueA field value is invalid for this endpointWrong type, or a value outside the allowed options (e.g. an unsupported chain name)No — fix the value
invalid_address_formatA wallet or token address is not valid for the specified chainMissing 0x prefix, wrong length, non-hex characters, or an address from a different chainNo — fix the address
invalid_date_formatA date is not in the expected formatDates must be {"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}No — fix the date format
invalid_date_rangeThe requested date range is not allowedRange longer than one year, or beyond the per-address limit for high-volume addressesNo — narrow the range
mutually_exclusive_fieldsTwo fields that cannot be combined were both providedSending both of a pair of alternative parameters in the same requestNo — remove one of the fields
value_out_of_rangeA value is outside the allowed boundsA number above or below the documented limit, or a string that is too short or too longNo — adjust the value
too_many_itemsA list contains more items than allowedMore entries than the field's maximum lengthNo — split into smaller batches
unauthenticatedAuthentication failedMissing, invalid, or expired API keyNo — obtain or refresh your API key
forbiddenAuthenticated, but no permission for this resourceYour account lacks access rights for the endpoint or dataNo — check your account's access
geo_blockedAccess is blocked in your regionRequest originates from a restricted jurisdictionNo
plan_upgrade_requiredThe feature requires a higher subscription planUsing a paid feature (e.g. premium_labels=true) on a Free planNo — upgrade your plan
insufficient_creditsNot enough API credits remain to call this endpointCredit balance is below the endpoint's credit costNo — add credits or upgrade your plan
rate_limit_exceededToo many requestsRequest rate above your plan's rate limitYes — wait Retry-After seconds, then retry
not_foundThe endpoint or resource does not exist, or is no longer availableWrong endpoint path or resource identifierNo — verify the path
method_not_allowedThe HTTP method is not allowed for this endpointUsing GET on a POST-only endpointNo — use the documented method
conflictThe request conflicts with the current stateA duplicate or contradictory operationNo — check your data
payload_too_largeThe request body is too largePayload exceeds the size limitNo — reduce the payload
query_timeoutThe query took too long to completeA very wide date range or an expensive, unfiltered queryYes — retry with backoff; wait Retry-After seconds when present; consider narrowing the query
query_too_largeThe query exceeds system limitsThe time range or parameter set would produce too much dataNo — reduce the time range or add filters
upstream_unavailableAn upstream service is temporarily unavailableMaintenance or overload of a backend serviceYes — retry with backoff; wait Retry-After seconds when present
internal_errorUnexpected server-side errorA fault on our side, not your requestYes — retry with backoff; contact support with your request_id if it persists
{% hint style="info" %} The set of error codes may expand over time. Clients must tolerate unknown codes: when you receive a `code` you don't recognize, fall back to handling the response by its HTTP status. {% endhint %}
# 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, Solana, or Monad. Broad client-side tooling and SDK support. Best for agents already operating on those networks. * **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 `POST` endpoints accept agentic payments, except: * `/api/v1/profiler/address/labels` and `/api/v1/profiler/address/premium-labels` — API key only, on any plan (proprietary entity data). * `/api/v1/smart-alert*` and `/api/v1/portfolio/defi-holdings` — tied to a Nansen account. Endpoints that are free on every plan (for example `/api/v1/account`, `/api/v1/search/general`, `/api/v1/search/entity-name`, and the DEX and perp trading endpoints) and all `GET` endpoints are not priced and require an API key. The [OpenAPI specification](https://api.nansen.ai/openapi.json) is the machine-readable source: every pay-per-request operation carries an `x-payment-info` extension and lists `X402Payment` and `MppPayment` as security alternatives to `ApiKeyAuth`. Operations that list only `ApiKeyAuth` require an API key. 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). ### Inspect the response before paying An unpaid x402 request returns a `402 Payment Required` response whose `PAYMENT-REQUIRED` header includes Bazaar discovery metadata. The Bazaar `output` schema describes the paid response before you sign or submit a payment, including: * the top-level response envelope; * the fields and JSON types returned in list items; and * pagination fields where the endpoint is paginated. To keep the discovery header bounded, nested output schemas are summarized to three levels. Objects below that depth remain identified as objects, but their deeper fields are intentionally omitted. The output metadata is derived from the same response contract used by the endpoint, so it stays aligned with the documented API response rather than being maintained as a separate schema. For example, Token Screener advertises a response object containing a `data` array of token result fields and a `pagination` object. Buyer agents can use this contract to decide whether the response is useful before making the paid retry. # 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 | |------------------------------------>| | | | 200 OK | | Payment-Receipt: | |<------------------------------------| ``` 1. Client sends the request with `Authorization: Payment`. 2. Server returns `402 Payment Required` with a `WWW-Authenticate: Payment` header advertising a fresh challenge (amount, currency, chain, recipient, expiry). 3. Client signs the challenge with a wallet funded on Tempo mainnet. 4. Client retries the same request with the signed credential. 5. Server verifies the on-chain settlement, runs the endpoint, and returns the response plus a `Payment-Receipt` header referencing the tx hash. ### Discovery Fetch `/.well-known/x402` to see every priced endpoint and its cost, along with which payment protocols are advertised: ```bash curl -s https://api.nansen.ai/.well-known/x402 | jq ``` Look for `paymentProtocols` containing `"mpp"` to confirm the rail is live. ### Troubleshooting **I signed the challenge but still got 402.** Challenges expire \~30 seconds after issue. If your signing + retry takes longer, the server issues a fresh challenge in the next 402. Sign that one instead. **402 says my signature is invalid.** Check that your wallet is on Tempo mainnet (`chainId 4217`), not a testnet. Testnet signatures are rejected by the prod API. **I got 200 but no `Payment-Receipt` header.** The response went through a proxy that stripped it. Confirm `Access-Control-Expose-Headers` includes `Payment-Receipt` on the response — if so, adjust your client to read exposed headers explicitly (relevant for browsers reading cross-origin responses). **`Payment-Receipt.status` is not `success`.** The payment was accepted but the downstream endpoint failed. Re-examine the HTTP status and body — your wallet was charged, but you may need to retry against a different payload. **Insufficient balance.** Fund your Tempo mainnet wallet via `tempo wallet fund` (which walks you through bridges: LayerZero/Stargate, Squid, Relay, Across, Bungee). ### Limits and known behaviour * **Per-call latency.** MPP settlement adds roughly one Tempo block-time to each request. For latency-sensitive workloads, an API key is faster. * **No session reuse yet.** Each request signs a fresh challenge; there is no open-channel / prefunded-session mode today. * **Idempotency across pods.** Replaying an identical signed challenge is guarded in-memory per pod. Under extremely high concurrency, a replay across pods is theoretically possible; the on-chain settlement layer still prevents double-charging. Please report any anomalies. # x402 Payments ### Overview x402 enables pay-per-call access to the Nansen API using cryptocurrency. No subscription or API key required. Send a request, pay with USDC on Base, Solana, or Monad, and get data back. {% hint style="warning" %} Nansen supports **x402 V2 only**. Deprecated V1 clients and the legacy `X-PAYMENT` request header are not supported. If your client reports `invalid_x402_version`, upgrade it to V2 and send the payment using the `PAYMENT-SIGNATURE` header. See the [official V1-to-V2 migration guide](https://docs.x402.org/guides/migration-v1-to-v2). {% endhint %} ### How It Works x402 is an open HTTP payment protocol. When you make a request to a supported endpoint without an API key, the server returns a `402 Payment Required` response with payment instructions. Your client pays the specified amount in USDC, then retries the request with a payment receipt. #### Request Flow ``` 1. Client sends request (no API key) 2. Server returns 402 with payment details 3. Client pays USDC on Base, Solana, or Monad 4. Client retries with payment receipt in header 5. Server verifies payment and returns data ``` #### Example ```bash # 1. Initial request returns 402 with payment instructions curl -X POST 'https://api.nansen.ai/api/v1/smart-money/holdings' \ -H 'Content-Type: application/json' \ -d '{"chains": ["ethereum"]}' # Response: 402 Payment Required # Headers include payment details (amount, recipient, network) ``` With an x402-compatible client, payment and retry happen automatically: ```python from eth_account import Account from x402 import x402ClientSync from x402.http.clients import x402_requests from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client # Sign payments with a wallet funded with USDC on Base account = Account.from_key("YOUR_PRIVATE_KEY") client = x402ClientSync() register_exact_evm_client(client, EthAccountSigner(account)) # requests-style session that pays and retries on 402 automatically session = x402_requests(client) response = session.post( "https://api.nansen.ai/api/v1/smart-money/holdings", json={"chains": ["ethereum"]}, ) # Payment handled automatically — response contains data ``` ### Pricing All Pro-tier endpoints are available via x402 (except labels endpoint). Pricing is based on endpoint tier. | Tier | Price Per Call | Endpoints | | --------------- | -------------- | ------------------------------------------------------------------------------- | | **Basic** | $0.01 | Token Screener, Wallet Balances, Transactions, PnL, DEX Trades, Flows, and more | | **Premium** | $0.05 | Counterparties, Holders, PnL Leaderboard, Perp Leaderboard | | **Smart Money** | $0.05 | SM Net Flow, SM Inflows, SM Holdings, SM DEX Trades | #### First 100 calls promotion (when enabled) When advertised in `/.well-known/x402`, each wallet can receive **50% off its first 100 successfully settled x402 calls** in this promotion. A $0.01 call costs $0.005 and a $0.05 call costs $0.025. Existing and new wallets start at zero when the promotion launches; earlier payments do not use the allowance. The allowance applies once per wallet across endpoints, with the same EVM wallet sharing its allowance across payment networks. Solana wallets have a separate allowance and their addresses are case-sensitive. Send `X-Payer-Address` with the wallet that will sign the payment on the **initial unpaid request**: ```bash curl -i -X POST 'https://api.nansen.ai/api/v1/smart-money/holdings' \ -H 'Content-Type: application/json' \ -H 'X-Payer-Address: YOUR_PAYING_WALLET_ADDRESS' \ -d '{"chains": ["ethereum"]}' ``` Configure your x402 V2 client's initial request with the same header. For an existing `fetch` wrapper that handles x402 signing and retries, the request options are: ```javascript const response = await fetchWithPayment( "https://api.nansen.ai/api/v1/smart-money/holdings", { method: "POST", headers: { "Content-Type": "application/json", "X-Payer-Address": payingWalletAddress, }, body: JSON.stringify({ chains: ["ethereum"] }), }, ); ``` The address header requests a quote; it does not prove ownership. On the paid retry, the signed payment determines the wallet and eligibility. Always sign the amount offered by the current `402` response, including fractional-cent prices. A quote does not reserve a discounted call: concurrent payments can use the remaining allowance before your retry, in which case request a fresh quote and confirm its price before paying again. Once the allowance is used, requests return to standard pricing automatically. Clients that omit the header continue to receive standard-price quotes. Successfully settled standard-price x402 calls during the promotion also count toward the first 100 calls, so send the header from your first request to use the discount. A promotion may also return a standard-price quote when availability cannot be checked. Failed requests without a successful settlement do not consume the allowance; a payment with an uncertain outcome may temporarily hold an allowance slot while it is reconciled. API credit pricing and MPP payments are unchanged. #### Basic Endpoints — $0.01/call | Endpoint | Path | | ------------------- | ---------------------------------------------- | | Current Balances | `/api/v1/profiler/address/current-balance` | | Historical Balances | `/api/v1/profiler/address/historical-balances` | | Perp Positions | `/api/v1/profiler/perp-positions` | | Transactions | `/api/v1/profiler/address/transactions` | | Perp Trades | `/api/v1/profiler/perp-trades` | | Related Wallets | `/api/v1/profiler/address/related-wallets` | | PnL Summary | `/api/v1/profiler/address/pnl-summary` | | PnL | `/api/v1/profiler/address/pnl` | | Token Screener | `/api/v1/token-screener` | | Perp Screener | `/api/v1/perp-screener` | | Transfers | `/api/v1/tgm/transfers` | | DCAs | `/api/v1/tgm/jup-dca` | | Flow Intel | `/api/v1/tgm/flow-intelligence` | | Who Bought/Sold | `/api/v1/tgm/who-bought-sold` | | DEX Trades | `/api/v1/tgm/dex-trades` | | DeFi Holdings | `/api/v1/portfolio/defi-holdings` | | Flows | `/api/v1/tgm/flows` | #### Premium Endpoints — $0.05/call | Endpoint | Path | | -------------------- | ----------------------------------------- | | Counterparties | `/api/v1/profiler/address/counterparties` | | Holders | `/api/v1/tgm/holders` | | PnL Leaderboard | `/api/v1/tgm/pnl-leaderboard` | | Perp PnL Leaderboard | `/api/v1/tgm/perp-pnl-leaderboard` | | Perp Leaderboard | `/api/v1/perp-leaderboard` | #### Smart Money Endpoints — $0.05/call | Endpoint | Path | | ---------------------- | -------------------------------- | | Net Flow | `/api/v1/smart-money/netflow` | | Holdings | `/api/v1/smart-money/holdings` | | DEX Trades | `/api/v1/smart-money/dex-trades` | | All other SM endpoints | `/api/v1/smart-money/*` | #### Excluded Endpoints * `/api/v1/profiler/address/labels` and `/api/v1/profiler/address/premium-labels`; these require an API key, on any plan. * `/api/v1/portfolio/defi-holdings` ### Payment Details | Parameter | Value | | --------------- | ------------------------------------------------------------- | | **Network** | Base, Solana & Monad | | **Currency** | USDC | | **Settlement** | Instant (onchain verification) | | **Facilitator** |

Base: Coinbase CDP
Solana: Payai
Monad: Molandak

| ### Rate Limits x402 requests have separate rate limits from API key authenticated requests. | Limit | Value | | ----------------------- | ----------- | | Per second (per wallet) | 5 requests | | Per minute (per wallet) | 60 requests | If you exceed rate limits, you'll receive a `429 Too Many Requests` response. Payments are not charged for rate-limited requests. ### FAQ **Q: Do I need a Nansen account?** No. x402 is fully permissionless. You only need a wallet with USDC on Base, Solana, or Monad. **Q: What happens if payment fails?** You'll receive a `402 Payment Required` response again. No data is returned until payment succeeds. **Q: Can I use x402 and an API key together?** If you include a valid API key, it takes precedence and no x402 payment is required. **Q: Which networks are supported for payment?** Currently Base, Solana, and Monad. More networks may be added in the future. **Q: Is there a minimum balance required?** No minimum. You just need enough USDC to cover the call price plus gas fees (typically < $0.01). # Make Your First API Call Welcome! In the next 2 minutes, you’ll make your first API call and unlock real-time blockchain insights. ### **Step 1: Get your API key** * Log in at Nansen [(Click here)](https://app.nansen.ai/api) * Navigate to the API tab in the left sidebar. * Click **Create API Key** (See screenshot below for where to find this button) * Copy your API Key
### **Step 2: Run this cURL Command** ```bash curl -L \ --request POST \ --url 'https://api.nansen.ai/api/v1/token-screener' \ --header 'apikey: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "chains": [ "ethereum", "solana", "base" ], "date": { "from": "2025-01-01T00:00:00Z", "to": "2025-01-31T23:59:59Z" }, "pagination": { "page": 1, "per_page": 10 }, "filters": { "only_smart_money": true, "token_age_days": { "max": 365, "min": 1 } }, "order_by": [ { "field": "chain", "direction": "ASC" } ] }' ``` ### Step 3: Now try this in API Explorer * Click on Test It button on the API codeblock below * Paste your API Key under the value section (As shown in the screenshot)
* Click on "Send" or press CMD + Enter. ## Retrieve token screener data > Discover and screen tokens across multiple blockchains with advanced filtering capabilities. This endpoint helps identify trending tokens, new launches, and smart money movements by combining metrics like volume, liquidity, market cap, and trading activity.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*Which tokens are experiencing significant smart money activity across different chains?\*\*\ > 2\. \*\*How do market metrics (price, volume, liquidity) correlate with holder behavior and smart money movements?\*\*\ > 3\. \*\*What tokens show strong fundamentals in terms of holder distribution and trading patterns?\*\*\ > 4\. \*\*Which emerging tokens are attracting fresh wallet inflows while maintaining healthy smart money participation?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TokenScreenerRequest":{"properties":{"chains":{"items":{"$ref":"#/components/schemas/TokenScreenerChain"},"type":"array","maxItems":5,"minItems":1,"title":"Chains","description":"List of blockchain chains to filter by"},"timeframe":{"anyOf":[{"$ref":"#/components/schemas/TokenScreenerTimeframe"}],"description":"**Required** (unless using deprecated 'date' parameter).\n\nTime window for token screening data.\n\nAvailable timeframes and their data characteristics:\n- 5m: Last 5 minutes (minute-level granularity, 2-hour retention)\n- 10m: Last 10 minutes (minute-level granularity, 2-hour retention)\n- 1h: Last 1 hour (minute-level granularity, 2-hour retention)\n- 6h: Last 6 hours (hourly granularity, 2-day retention)\n- 24h: Last 24 hours (hourly granularity, 2-day retention)\n- 7d: Last 7 days (daily granularity, 2-month retention)\n- 30d: Last 30 days (daily granularity, 2-month retention)\n\nCannot be used together with 'date'."},"date":{"anyOf":[{"$ref":"#/components/schemas/DateRange"}],"description":"**DEPRECATED**: Use 'timeframe' instead. It offers better reliability and performance.\n\nRequired only if 'timeframe' is not provided.\n\nCustom date range for the token screener. The granularity is automatically determined from the date range:\n- ≤ 1 hour: minute-level data (limited to last 2 hours)\n- > 1 hour to 1 day: hourly data (limited to last 2 days)\n- > 1 day: daily data (limited to last 2 months)\n\nCannot be used together with 'timeframe'.","deprecated":true},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TokenScreenerFilters"}],"description":"Additional filters to apply"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TokenScreenerSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"buy_volume\", \"direction\": \"DESC\"}] - Sort by buy volume descending\n- [{\"field\": \"price_change\", \"direction\": \"DESC\"}] - Sort by price change descending"}},"additionalProperties":false,"type":"object","required":["chains"],"title":"TokenScreenerRequest","description":"Request model for Token Screener endpoint.\n\nEither 'timeframe' (recommended) or 'date' (deprecated) must be provided."},"TokenScreenerChain":{"type":"string","enum":["arbitrum","arc","avalanche","base","bitcoin","bnb","citrea","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"TokenScreenerChain","description":"Chains supported for Token Screener endpoint."},"TokenScreenerTimeframe":{"type":"string","enum":["5m","10m","1h","6h","24h","7d","30d"],"title":"TokenScreenerTimeframe","description":"Token screener timeframe options.\n\nDefines the time window for token screening data.\nEach timeframe corresponds to different data granularity and retention periods.\nMatches the timeframe options in the Nansen token-screener widget."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TokenScreenerFilters":{"properties":{"token_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Address","description":"Token address or symbol filter"},"token_symbol":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Symbol","description":"Token symbol filter"},"only_smart_money":{"anyOf":[{"type":"boolean"}],"title":"Only Smart Money","description":"Deprecated: Use 'trader_type' instead. Whether to only include smart money tokens","deprecated":true},"trader_type":{"anyOf":[{"$ref":"#/components/schemas/TraderType"}],"description":"Filter by trader type. Overrides only_smart_money when provided. Supported values: `all`, `sm`, `whale`, `public_figure`, `trending`."},"sectors":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Sectors","description":"Token sectors to include, as bare sector names (e.g. DeFi, Gaming). Note: this differs from the perp screener's sectors_filter, which uses category:subcategory values."},"exclude_sectors":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Exclude Sectors","description":"Token sectors to exclude, as bare sector names."},"token_age_days":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token age range filter in days"},"market_cap_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Market cap range filter"},"liquidity":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Liquidity range filter"},"price_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Current price range filter in USD"},"price_change":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Price change percentage range filter"},"fdv":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Fully Diluted Valuation range filter"},"fdv_mc_ratio":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"FDV to Market Cap ratio range filter"},"nof_buyers":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of unique buyers range filter"},"nof_traders":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of unique traders range filter"},"nof_sellers":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of unique sellers range filter"},"nof_buys":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of buy transactions range filter"},"nof_sells":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of sell transactions range filter"},"buy_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Buy volume range filter in USD"},"sell_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Sell volume range filter in USD"},"volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total trading volume range filter in USD"},"netflow":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Net flow range filter in USD"},"inflow_fdv_ratio":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Inflow to FDV ratio range filter"},"outflow_fdv_ratio":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Outflow to FDV ratio range filter"},"include_stablecoins":{"type":"boolean","title":"Include Stablecoins","description":"Whether to include stablecoins in token screener results. Default true preserves current behavior. Set to false to exclude USDC, USDT, DAI, and other major stablecoins.","default":true},"include_native_tokens":{"type":"boolean","title":"Include Native Tokens","description":"Whether to include native tokens (e.g. ETH, SOL) and wrapped-native / LST / LRT derivatives in results. Default false preserves current behavior.","default":false},"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Include smart money labels"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels"}},"additionalProperties":false,"type":"object","title":"TokenScreenerFilters","description":"Filters for token screener endpoints.\n\nThese filters control which tokens are included in the screening\nresults based on various criteria."},"TraderType":{"type":"string","enum":["all","sm","whale","public_figure","trending","consistent_perps_winner","high_winrate_hl_perps_trader","predicted_winner"],"title":"TraderType","description":"Trader type filter for token screener."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Filter by smart money label type."},"TokenScreenerSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TokenScreenerSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TokenScreenerSortOrder"},"TokenScreenerSortField":{"type":"string","enum":["chain","token_address","token_symbol","market_cap_usd","volume","liquidity","nof_traders","nof_buyers","nof_sellers","nof_buys","nof_sells","price_change","price_usd","netflow","buy_volume","sell_volume","fdv","fdv_mc_ratio","inflow_fdv_ratio","outflow_fdv_ratio","token_age_days"],"title":"TokenScreenerSortField","description":"Enum for sortable fields in token screener."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TokenScreenerResponse":{"properties":{"data":{"items":{"anyOf":[{"$ref":"#/components/schemas/TokenScreenerDataDefault"},{"$ref":"#/components/schemas/TokenScreenerDataSmartMoneyDefault"},{"$ref":"#/components/schemas/TokenScreenerDataNonDefault"}]},"type":"array","title":"Data","description":"List of token screening results"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TokenScreenerResponse","description":"Response model for token screener endpoint."},"TokenScreenerDataDefault":{"properties":{"chain":{"type":"string","title":"Chain","description":"The blockchain network on which the token is deployed."},"token_address":{"type":"string","title":"Token Address","description":"Address of token"},"token_symbol":{"type":"string","title":"Token Symbol","description":"The symbol of the token."},"token_age_days":{"anyOf":[{"type":"number"}],"title":"Token Age Days","description":"Number of days since token deployment."},"token_age_hours":{"anyOf":[{"type":"number"}],"title":"Token Age Hours","description":"Number of hours since token deployment."},"token_deployment_date":{"anyOf":[{"type":"string"}],"title":"Token Deployment Date","description":"ISO 8601 timestamp of token deployment."},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Market capitalization in USD."},"liquidity":{"anyOf":[{"type":"number"}],"title":"Liquidity","description":"Total on-chain liquidity in USD."},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Price of the token"},"price_change":{"anyOf":[{"type":"number"}],"title":"Price Change","description":"Price change percentage from the previous period."},"fdv":{"anyOf":[{"type":"number"}],"title":"Fdv","description":"Fully Diluted Valuation in USD."},"fdv_mc_ratio":{"anyOf":[{"type":"number"}],"title":"Fdv Mc Ratio","description":"Ratio of Fully Diluted Valuation to Market Cap."},"buy_volume":{"anyOf":[{"type":"number"}],"title":"Buy Volume","description":"Total buy volume in USD."},"inflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Inflow Fdv Ratio","description":"Ratio of inflow to Fully Diluted Valuation."},"outflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Outflow Fdv Ratio","description":"Ratio of outflow to Fully Diluted Valuation."},"sell_volume":{"anyOf":[{"type":"number"}],"title":"Sell Volume","description":"Total sell volume in USD."},"volume":{"anyOf":[{"type":"number"}],"title":"Volume","description":"Total trading volume in USD."},"netflow":{"anyOf":[{"type":"number"}],"title":"Netflow","description":"Net flow (buy_volume - sell_volume) in USD."}},"type":"object","required":["chain","token_address","token_symbol"],"title":"TokenScreenerDataDefault","description":"Data model for token screener results with non-default query (excludes trader-related columns)."},"TokenScreenerDataSmartMoneyDefault":{"properties":{"chain":{"type":"string","title":"Chain","description":"The blockchain network on which the token is deployed."},"token_address":{"type":"string","title":"Token Address","description":"Address of token"},"token_symbol":{"type":"string","title":"Token Symbol","description":"The symbol of the token."},"token_age_days":{"anyOf":[{"type":"number"}],"title":"Token Age Days","description":"Number of days since token deployment."},"token_age_hours":{"anyOf":[{"type":"number"}],"title":"Token Age Hours","description":"Number of hours since token deployment."},"token_deployment_date":{"anyOf":[{"type":"string"}],"title":"Token Deployment Date","description":"ISO 8601 timestamp of token deployment."},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Market capitalization in USD."},"liquidity":{"anyOf":[{"type":"number"}],"title":"Liquidity","description":"Total on-chain liquidity in USD."},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Price of the token"},"price_change":{"anyOf":[{"type":"number"}],"title":"Price Change","description":"Price change percentage from the previous period."},"fdv":{"anyOf":[{"type":"number"}],"title":"Fdv","description":"Fully Diluted Valuation in USD."},"fdv_mc_ratio":{"anyOf":[{"type":"number"}],"title":"Fdv Mc Ratio","description":"Ratio of Fully Diluted Valuation to Market Cap."},"nof_traders":{"anyOf":[{"type":"integer"}],"title":"Nof Traders","description":"Total number of unique traders."},"buy_volume":{"anyOf":[{"type":"number"}],"title":"Buy Volume","description":"Total buy volume in USD."},"inflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Inflow Fdv Ratio","description":"Ratio of inflow to Fully Diluted Valuation."},"outflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Outflow Fdv Ratio","description":"Ratio of outflow to Fully Diluted Valuation."},"sell_volume":{"anyOf":[{"type":"number"}],"title":"Sell Volume","description":"Total sell volume in USD."},"volume":{"anyOf":[{"type":"number"}],"title":"Volume","description":"Total trading volume in USD."},"netflow":{"anyOf":[{"type":"number"}],"title":"Netflow","description":"Net flow (buy_volume - sell_volume) in USD."}},"type":"object","required":["chain","token_address","token_symbol"],"title":"TokenScreenerDataSmartMoneyDefault","description":"Data model for smart money token screener with default query.\n\nIncludes nof_traders but excludes other trader-related columns\n(nof_buyers, nof_sellers, nof_buys, nof_sells)."},"TokenScreenerDataNonDefault":{"properties":{"chain":{"type":"string","title":"Chain","description":"The blockchain network on which the token is deployed."},"token_address":{"type":"string","title":"Token Address","description":"Address of token"},"token_symbol":{"type":"string","title":"Token Symbol","description":"The symbol of the token."},"token_age_days":{"anyOf":[{"type":"number"}],"title":"Token Age Days","description":"Number of days since token deployment."},"token_age_hours":{"anyOf":[{"type":"number"}],"title":"Token Age Hours","description":"Number of hours since token deployment."},"token_deployment_date":{"anyOf":[{"type":"string"}],"title":"Token Deployment Date","description":"ISO 8601 timestamp of token deployment."},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Market capitalization in USD."},"liquidity":{"anyOf":[{"type":"number"}],"title":"Liquidity","description":"Total on-chain liquidity in USD."},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Price of the token"},"price_change":{"anyOf":[{"type":"number"}],"title":"Price Change","description":"Price change percentage from the previous period."},"fdv":{"anyOf":[{"type":"number"}],"title":"Fdv","description":"Fully Diluted Valuation in USD."},"fdv_mc_ratio":{"anyOf":[{"type":"number"}],"title":"Fdv Mc Ratio","description":"Ratio of Fully Diluted Valuation to Market Cap."},"nof_buyers":{"anyOf":[{"type":"integer"}],"title":"Nof Buyers","description":"Number of unique buyers."},"nof_traders":{"anyOf":[{"type":"integer"}],"title":"Nof Traders","description":"Total number of unique traders."},"nof_sellers":{"anyOf":[{"type":"integer"}],"title":"Nof Sellers","description":"Number of unique sellers."},"nof_buys":{"anyOf":[{"type":"integer"}],"title":"Nof Buys","description":"Total number of buy transactions."},"nof_sells":{"anyOf":[{"type":"integer"}],"title":"Nof Sells","description":"Total number of sell transactions."},"buy_volume":{"anyOf":[{"type":"number"}],"title":"Buy Volume","description":"Total buy volume in USD."},"inflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Inflow Fdv Ratio","description":"Ratio of inflow to Fully Diluted Valuation."},"outflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Outflow Fdv Ratio","description":"Ratio of outflow to Fully Diluted Valuation."},"sell_volume":{"anyOf":[{"type":"number"}],"title":"Sell Volume","description":"Total sell volume in USD."},"volume":{"anyOf":[{"type":"number"}],"title":"Volume","description":"Total trading volume in USD."},"netflow":{"anyOf":[{"type":"number"}],"title":"Netflow","description":"Net flow (buy_volume - sell_volume) in USD."}},"type":"object","required":["chain","token_address","token_symbol"],"title":"TokenScreenerDataNonDefault","description":"Data model for token screener results with non-default query (includes all columns)."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/token-screener":{"post":{"tags":["Token Screener"],"summary":"Retrieve token screener data","description":"Discover and screen tokens across multiple blockchains with advanced filtering capabilities. This endpoint helps identify trending tokens, new launches, and smart money movements by combining metrics like volume, liquidity, market cap, and trading activity.\n\n**What it helps to answer:**\n\n1. **Which tokens are experiencing significant smart money activity across different chains?**\n2. **How do market metrics (price, volume, liquidity) correlate with holder behavior and smart money movements?**\n3. **What tokens show strong fundamentals in terms of holder distribution and trading patterns?**\n4. **Which emerging tokens are attracting fresh wallet inflows while maintaining healthy smart money participation?**","operationId":"get_token_screener_api_v1_token_screener_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenScreenerRequest"}}},"required":true},"responses":{"200":{"description":"Token screening data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenScreenerResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` ### Next Steps 1. **Checkout these Usecase Templates** {% content-ref url="/pages/sZ42YbN487lUkqjRYobp" %} [Use case Templates](/guides/templates) {% endcontent-ref %} 2. **Checkout all the available endpoints** {% content-ref url="/pages/ULb0CMVkxzlnFoWOFf6K" %} [Smart Money](/api/smart-money) {% endcontent-ref %} {% content-ref url="/pages/8aOjJs2bpUhoO4SDqcWN" %} [Token God Mode](/api/token-god-mode) {% endcontent-ref %} {% content-ref url="/pages/PnT1uPG4TtdjDFCJAVHV" %} [Profiler](/api/profiler) {% endcontent-ref %} {% content-ref url="/pages/UofenUf9aGszprYk2DzY" %} [Portfolio](/api/portfolio) {% endcontent-ref %} # API Migration When part of the API is scheduled for removal or replacement, we announce it ahead of time and signal it on the wire so your integration never breaks without warning. This page explains each deprecation signal, lists everything that is currently deprecated, and shows how to migrate. New deprecations and removals are announced in the [API Changelog](/api/changelog). Deprecated fields remain accepted during their migration window. For deprecated endpoints, any scheduled sunset is at least 90 days after deprecation begins. ### Deprecated endpoints: `Deprecation`, `Sunset` and `Link` headers Responses from a deprecated endpoint carry a `Deprecation` header and may include other standard lifecycle headers: ```http Deprecation: @1768435200 Sunset: Tue, 30 Jun 2026 00:00:00 GMT Link: ; rel="deprecation" ``` | Header | Meaning | Format | | -------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------- | | `Deprecation` | The endpoint is deprecated, and since when | `@` followed by a Unix timestamp ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) | | `Sunset` | The date after which the endpoint may be removed | HTTP date ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) | | `Link … rel="deprecation"` | Where the deprecation is documented | URL in angle brackets ([RFC 8288](https://www.rfc-editor.org/rfc/rfc8288)) | `Sunset` only appears once a removal date has been decided, and `Link` only appears when migration documentation is configured. An endpoint can be deprecated without either one. All three headers are readable from browser-based clients. {% hint style="info" %} No endpoint is deprecated right now — no live endpoint currently returns these headers. They are documented here so you can build detection before you ever need it. {% endhint %} ### Deprecated request fields: the `Warning` header Some endpoints have individual request fields that were replaced by better alternatives. The old field keeps working, but if your request includes one, the response carries a `Warning: 299` header telling you what to use instead: ```http Warning: 299 - "The 'date_range' parameter is deprecated. Use 'date' instead." ``` The warning only appears when your request actually sends the deprecated field — requests that omit it are unaffected. If a request uses several deprecated fields, the warnings are comma-separated in a single header: ```http Warning: 299 - "The 'date' parameter is deprecated. Use 'timeframe' instead.", 299 - "The 'filters.only_smart_money' parameter is deprecated. Use 'trader_type' instead." ``` Deprecated fields are also marked `deprecated: true` in the OpenAPI specification, so generated clients and API tooling flag them at build time. ### Currently deprecated request fields | Endpoint | Deprecated field | Use instead | | ------------------------------------------------ | -------------------------- | --------------------- | | `POST /api/v1/token-screener` | `date` | `timeframe` | | `POST /api/v1/token-screener` | `filters.only_smart_money` | `filters.trader_type` | | `POST /api/v1/perp-screener` | `filters.only_smart_money` | `filters.trader_type` | | `POST /api/v1/tgm/token-ohlcv` | `date_range` | `date` | | `POST /api/v1/prediction-market/market-screener` | `sort_by` | `order_by` | | `POST /api/v1/prediction-market/event-screener` | `sort_by` | `order_by` | | `POST /api/v1/prediction-market/ohlcv` | `sort` | `order_by` | | `POST /api/v1/prediction-market/top-holders` | `sort` | `order_by` | | `POST /api/v1beta1/token-screener/historical` | `only_smart_money` | `trader_type` | #### `only_smart_money` → `trader_type` Map `only_smart_money: true` to `trader_type: "sm"`; when it is `false`, omit `trader_type` to keep the default behavior. `trader_type` also supports endpoint-specific cohorts such as `whale`, `public_figure`, `trending`, and `high_winrate_hl_perps_trader` — check the endpoint schema for its accepted values. When both fields are sent, `trader_type` wins. **Before:** ```json { "filters": { "only_smart_money": true } } ``` **After:** ```json { "filters": { "trader_type": "sm" } } ``` #### `date` → `timeframe` (Token Screener) Use a named window (`5m`, `10m`, `1h`, `6h`, `24h`, `7d`, `30d`) instead of an explicit date range. The two fields cannot be combined in one request. **Before:** ```json { "chains": ["ethereum"], "date": { "from": "2025-01-01T00:00:00Z", "to": "2025-01-02T00:00:00Z" } } ``` **After:** ```json { "chains": ["ethereum"], "timeframe": "24h" } ``` #### `date_range` → `date` (Token OHLCV) The replacement uses `from`/`to` keys instead of `start`/`end`. Sending both fields is rejected with a validation error. **Before:** ```json { "date_range": { "start": "2025-01-01", "end": "2025-01-31" } } ``` **After:** ```json { "date": { "from": "2025-01-01", "to": "2025-01-31" } } ``` #### `sort` / `sort_by` → `order_by` (Prediction Markets) `order_by` takes a list of sort criteria, each with a field and a direction. For the OHLCV and Top Holders endpoints, `sort` already had this shape — only the name changes. **Before:** ```json { "sort_by": "volume_24hr" } ``` **After:** ```json { "order_by": [{ "field": "volume_24hr", "direction": "DESC" }] } ``` ### Recommended migration process 1. **Watch the** [**API Changelog**](/api/changelog) — new deprecations and removals are announced there. 2. **Log deprecation signals in your client.** Check responses for `Warning`, `Deprecation` and `Sunset` headers and surface them in your logs or monitoring. This turns a future removal into a routine ticket instead of an outage. 3. **Migrate to the replacement** shown in the `Warning` message or the table above. 4. **Confirm the signal is gone.** Once your requests no longer use a deprecated field, the `Warning` header disappears. {% hint style="info" %} Treat the set of deprecation messages as open-ended: parse the header's presence, not its exact wording. After an endpoint passes its sunset date and is removed, calls to it return `404` with the `not_found` error code — see [Error Handling](/getting-started/error-handling). {% endhint %} # Reference This section explains the key concepts and terminology used throughout the Nansen API. ### Guides * Supported Chains - Blockchains supported by the API * Native Tokens - Placeholder addresses, query examples, and coverage limitations * Address Formats - Address formats for each chain type * Smart Money Labels - Understanding smart money classifications * Filter Types - Available filter types and usage * Sorting - How to sort API results ### Quick Reference #### Chains The API supports 37 blockchains: | Type | Examples | | ------- | ------------------------------------------------ | | EVM | Ethereum, Arbitrum, Base, BNB, Polygon, Optimism | | Non-EVM | Solana, Bitcoin, TON, Tron, Starknet, SUI | #### Smart Money Labels | Label | Description | | ------------------------- | ------------------------------- | | Fund | Institutional investment funds | | Smart Trader | Historically profitable traders | | 30D/90D/180D Smart Trader | Time-based performance labels | #### Common Filters | Filter Type | Example | | ------------- | ----------------------------- | | Numeric Range | `{"min": 1000, "max": 50000}` | | Integer Range | `{"min": 10, "max": 100}` | | Address List | `["0x...", "0x..."]` | | Label List | `["Fund", "Smart Trader"]` | #### Sort Order ```json { "order_by": [ {"field": "value_usd", "direction": "DESC"} ] } ``` # Supported Chains ### Overview The Nansen API supports 38 blockchain networks across EVM and non-EVM ecosystems. Chain support varies by endpoint. For native assets such as ETH, BTC, and SOL, see [Native Tokens](/reference/native-tokens) for the placeholder addresses expected by token-based endpoints and their coverage limitations. ### EVM Chains EVM-compatible chains use the standard Ethereum address format (`0x` + 40 hex characters). | Chain | Value | Description | | --------- | ----------- | --------------------- | | Arbitrum | `arbitrum` | Arbitrum One L2 | | Arc | `arc` | Circle L1 (USDC gas) | | Avalanche | `avalanche` | Avalanche C-Chain | | Base | `base` | Coinbase L2 | | Bitlayer | `bitlayer` | Bitcoin L2 | | BNB Chain | `bnb` | BNB Smart Chain | | Chiliz | `chiliz` | Chiliz Chain | | Citrea | `citrea` | Bitcoin ZK rollup | | Ethereum | `ethereum` | Main Ethereum network | | Gravity | `gravity` | Gravity network | | HyperEVM | `hyperevm` | Hyperliquid EVM | | IOTA EVM | `iotaevm` | IOTA EVM | | Katana | `katana` | Katana network | | Linea | `linea` | Linea L2 | | Mantle | `mantle` | Mantle L2 | | Metis | `metis` | Metis L2 | | Monad | `monad` | Monad network | | Optimism | `optimism` | Optimism L2 | | Plasma | `plasma` | Plasma network | | Polygon | `polygon` | Polygon PoS | | Robinhood | `robinhood` | Robinhood Chain | | Sei | `sei` | Sei EVM | | Sonic | `sonic` | Sonic network | | Viction | `viction` | Viction (TomoChain) | ### Non-EVM Chains Non-EVM chains have unique address formats. See Address Formats for details. | Chain | Value | Description | | ----------- | ------------- | --------------------------------- | | Algorand | `algorand` | Algorand network | | Aptos | `aptos` | Aptos network | | Bitcoin | `bitcoin` | Bitcoin network | | Hyperliquid | `hyperliquid` | Hyperliquid DEX (perpetuals only) | | Injective | `injective` | Injective network | | Mantra | `mantra` | Mantra network | | NEAR | `near` | NEAR Protocol | | Solana | `solana` | Solana network | | Stacks | `stacks` | Stacks (Bitcoin L2) | | Starknet | `starknet` | Starknet L2 | | Stellar | `stellar` | Stellar network | | SUI | `sui` | SUI network | | TON | `ton` | The Open Network | | Tron | `tron` | Tron network | ### Using the "all" Chain Some endpoints support `"all"` to query across all supported chains: ```json { "chains": ["all"] } ``` This expands to all chains supported by that specific endpoint. ### Chain Support by Endpoint Not all chains are available on all endpoints. Here's the support matrix: #### Smart Money Endpoints | Chain | Netflow | DEX Trades | Holdings | Historical | | ----------- | ------- | ---------- | -------- | ---------- | | `arbitrum` | Yes | Yes | Yes | No | | `arc` | Yes | Yes | Yes | Yes | | `avalanche` | Yes | Yes | Yes | No | | `base` | Yes | Yes | Yes | Yes | | `bnb` | Yes | Yes | Yes | Yes | | `ethereum` | Yes | Yes | Yes | Yes | | `hyperevm` | Yes | Yes | Yes | No | | `iotaevm` | Yes | Yes | Yes | No | | `linea` | Yes | Yes | Yes | No | | `mantle` | Yes | Yes | Yes | No | | `monad` | Yes | Yes | Yes | Yes | | `optimism` | Yes | Yes | Yes | No | | `plasma` | Yes | Yes | Yes | No | | `polygon` | Yes | Yes | Yes | No | | `robinhood` | Yes | Yes | Yes | Yes | | `sei` | Yes | Yes | Yes | No | | `solana` | Yes | Yes | Yes | Yes | | `sonic` | Yes | Yes | Yes | No | #### Token God Mode Endpoints | Chain | Flows | Transfers | Holders | PnL | | ------------- | ----- | --------- | ------- | --- | | `arbitrum` | Yes | Yes | Yes | Yes | | `arc` | Yes | Yes | Yes | Yes | | `avalanche` | Yes | Yes | Yes | Yes | | `base` | Yes | Yes | Yes | Yes | | `bitcoin` | No | Yes | Yes | No | | `bnb` | Yes | Yes | Yes | Yes | | `ethereum` | Yes | Yes | Yes | Yes | | `hyperevm` | Yes | Yes | Yes | Yes | | `hyperliquid` | Yes | No | No | Yes | | `injective` | Yes | Yes | Yes | No | | `iotaevm` | Yes | Yes | Yes | No | | `linea` | Yes | Yes | Yes | Yes | | `mantle` | Yes | Yes | Yes | Yes | | `mantra` | Yes | Yes | Yes | No | | `monad` | Yes | Yes | Yes | Yes | | `near` | Yes | Yes | Yes | No | | `optimism` | Yes | Yes | Yes | Yes | | `plasma` | Yes | Yes | Yes | Yes | | `polygon` | Yes | Yes | Yes | Yes | | `robinhood` | Yes | Yes | Yes | Yes | | `sei` | Yes | Yes | Yes | Yes | | `solana` | Yes | Yes | Yes | Yes | | `sonic` | Yes | Yes | Yes | Yes | | `starknet` | Yes | Yes | Yes | No | | `sui` | Yes | Yes | Yes | Yes | | `ton` | Yes | Yes | Yes | No | | `tron` | Yes | Yes | Yes | No | #### Profiler Endpoints | Chain | Balance | Transactions | PnL | Related | | ----------- | ------- | ------------ | --- | ------- | | `arbitrum` | Yes | Yes | Yes | Yes | | `arc` | Yes | Yes | Yes | Yes | | `avalanche` | Yes | Yes | Yes | Yes | | `base` | Yes | Yes | Yes | Yes | | `bitcoin` | Yes | Yes | No | Yes | | `bnb` | Yes | Yes | Yes | Yes | | `ethereum` | Yes | Yes | Yes | Yes | | `hyperevm` | Yes | No | No | No | | `injective` | Yes | Yes | No | Yes | | `iotaevm` | Yes | Yes | No | Yes | | `linea` | Yes | Yes | Yes | Yes | | `mantle` | Yes | Yes | Yes | Yes | | `mantra` | Yes | Yes | No | Yes | | `monad` | Yes | Yes | Yes | Yes | | `near` | Yes | Yes | No | Yes | | `optimism` | Yes | Yes | Yes | Yes | | `plasma` | Yes | Yes | Yes | Yes | | `polygon` | Yes | Yes | Yes | Yes | | `robinhood` | Yes | Yes | Yes | Yes | | `sei` | Yes | Yes | Yes | Yes | | `solana` | Yes | Yes | Yes | Yes | | `sonic` | Yes | Yes | Yes | Yes | | `starknet` | Yes | Yes | No | Yes | | `sui` | Yes | Yes | Yes | Yes | | `ton` | Yes | Yes | No | Yes | | `tron` | Yes | Yes | No | Yes | ### Examples #### Single Chain Query ```json { "chains": ["ethereum"] } ``` #### Multi-Chain Query ```json { "chains": ["ethereum", "solana", "base"] } ``` #### All Chains Query ```json { "chains": ["all"] } ``` ### Chain-Specific Considerations #### Solana * Uses base58 addresses * Transaction lookup not supported * Full support for Smart Money and TGM #### Bitcoin * Limited endpoint support (Profiler only) * Supports P2PKH, P2SH, and Bech32 addresses * No Smart Money or TGM support #### TON * Uses EQ.../UQ... address format * Addresses are automatically normalized * No PnL endpoints #### Hyperliquid * Perpetuals platform only * Used for perp-specific endpoints * No standard token endpoints # Native Tokens How to query native tokens (ETH, BTC, SOL, …) and where their coverage is thinner than for contract tokens. A **native token** is the coin a chain issues itself — ETH on Ethereum, BTC on Bitcoin, SOL on Solana, TON on TON. Unlike an ERC-20 or SPL token, a native token has **no contract address**, so there is no real `token_address` to send. The API solves this with a **per-chain placeholder address**. You pass the placeholder as `token_address` and pair it with the `chain` you want. {% hint style="warning" %} Native-token coverage is genuinely **narrower** than contract-token coverage. Several endpoints reject native tokens outright, and others serve them from a different data path — in one case with fewer filter and sort options. Read [Coverage limitations](#coverage-limitations) before assuming parity with an ERC-20 — this is the most common source of confusion in native-token queries. {% endhint %} ### Placeholder addresses | Chain | `chain` value | `token_address` placeholder | | ------------- | --------------------------------- | ------------------------------------------------------------------------------ | | Any EVM chain | `ethereum`, `base`, `arbitrum`, … | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` | | Bitcoin | `bitcoin` | `1111111111111111111114oLvT2` | | NEAR | `near` | `native-token.near` | | Solana | `solana` | `So11111111111111111111111111111111111111112` | | SUI | `sui` | `0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI` | | TON | `ton` | `0:0000000000000000000000000000000000000000000000000000000000000000` | | Tron | `tron` | `TXka46PPwttNPWfFDPtt3GUodbPThyufaV` | | Injective | `injective` | `0x0000000088827d2d103ee2d9a6b781773ae03ffb` | Chains not listed above have no native-token placeholder. See [Supported Chains](/reference/chains) for the full chain list. ### Pairing the EVM placeholder with a chain There is **one** placeholder for all EVM chains. It does not mean "ETH" — it means "whatever this chain's native coin is". The `chain` field decides which coin you get: ```json // ETH on Ethereum {"chain": "ethereum", "token_address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"} // BNB on BNB Chain {"chain": "bnb", "token_address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"} // POL on Polygon {"chain": "polygon", "token_address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"} ``` The placeholder itself is valid on any EVM chain — `arbitrum`, `arc`, `avalanche`, `base`, `bitlayer`, `bnb`, `chiliz`, `citrea`, `ethereum`, `gravity`, `hyperevm`, `iotaevm`, `katana`, `linea`, `mantle`, `metis`, `monad`, `optimism`, `plasma`, `polygon`, `robinhood`, `sei`, `sonic`, `viction`. Passing address validation is not the same as the endpoint supporting that chain, though. Individual endpoints accept narrower chain sets than the list above — TGM Holders, for instance, omits several of them. Treat the placeholder as valid on **any EVM chain the endpoint itself supports**, and check the endpoint's own `chain` values in [Supported Chains](/reference/chains). {% hint style="info" %} **Injective is not an EVM chain here.** Its placeholder looks like a 40-hex EVM address, but Injective is classified as non-EVM by the API. Use `0x0000000088827d2d103ee2d9a6b781773ae03ffb` with `chain: "injective"`. Sending the EVM placeholder `0xeeee…` with `chain: "injective"` is rejected, and sending the Injective placeholder with `chain: "ethereum"` is rejected too. {% endhint %} #### Mismatched chain and placeholder Pairing a placeholder with a chain it doesn't belong to returns **HTTP 422** with error code `invalid_address_format`: ```json // Request — Solana's placeholder on Ethereum {"chain": "ethereum", "token_address": "So11111111111111111111111111111111111111112"} ``` ```json // 422 response — abbreviated to the fields specific to this error { "error": "Invalid address format", "code": "invalid_address_format", "message": "Address 'So11111111111111111111111111111111111111112' appears to be a solana address format but the chain is set to ethereum. Please verify the address is correct for the ethereum chain." } ``` The real response also carries the standard envelope fields (`status`, `request_id`, `doc_url`, and `param` where applicable). See [Error Handling](/getting-started/error-handling) for the full shape. #### Copy each placeholder exactly as listed **Send every placeholder byte-for-byte as it appears in the table above.** Hex-shaped addresses are lowercased for you, but the base58 and type-string placeholders are compared literally, and what happens when you miscase one is not consistent: | Miscased input | Result | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `0xEEEE…` (EVM), `0x…88827D2D…` (Injective) | **Accepted.** Both are hex addresses and are lowercased before the native-token lookup. | | `NATIVE-TOKEN.NEAR` | **Rejected** — fails address-format validation. | | `txka46pp…` (Tron) | **Rejected** — the lowercase form no longer matches the Tron address pattern. | | `so1111…112` (Solana), `0x…::sui::sui` (SUI) | **Silently not native.** Still a structurally valid address, so validation passes, but it is not recognized as the native token and is treated as an ordinary token address instead. | That last row is the dangerous one: the request succeeds, so nothing tells you the placeholder was wrong. If a Solana or SUI native-token query returns results you did not expect, check the placeholder's casing first. In short: case-sensitivity tracks the *address format*, not whether the chain is EVM. That is why Injective, despite being non-EVM, is as forgiving as Ethereum here. ### Example: ETH holders `chain` is what makes the shared EVM placeholder mean ETH rather than BNB or POL: ```bash curl -s -X POST "https://api.nansen.ai/api/v1/tgm/holders" \ -H "Content-Type: application/json" \ -H "apikey: YOUR_API_KEY" \ -d '{ "chain": "ethereum", "token_address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "label_type": "all_holders", "pagination": {"page": 1, "per_page": 10} }' ``` This request lands on the restricted path described in [Token God Mode Holders behaves differently for native tokens](#token-god-mode-holders-behaves-differently-for-native-tokens) — native token, `all_holders`, no entity aggregation, not Bitcoin — so sort by `token_amount` only, and expect sub-$1 holders in the response. ### Coverage limitations Native tokens are held by tens of millions of addresses and move in every gas payment on the chain, so the analytics that work well for a contract token are often either unavailable or computed differently. Concretely: #### Endpoints that reject native tokens These return **HTTP 422** with error code `invalid_field_value` and a message naming the endpoint. There is no workaround — use a different endpoint. | Endpoint | Native tokens rejected on | | ---------------------------------------------------- | ---------------------------------------------------------------------------------- | | `POST /api/v1/tgm/flows` | All chains | | `POST /api/v1/tgm/pnl-leaderboard` | All chains | | `POST /api/v1/tgm/historical-pnl-leaderboard` | All chains | | `POST /api/v1/tgm/jup-dca` | All chains | | `POST /api/v1/tgm/transfers` | All chains **except** `bitcoin` | | `POST /api/v1/tgm/dex-trades` | `solana` only | | `POST /api/v1/tgm/historical-dex-trades` | `solana` only | | `POST /api/v1/tgm/historical-token-flow-summary` | `solana` only | | `POST /api/v1/tgm/holders` | `solana` only | | `POST /api/v1/profiler/address/counterparties` | `solana` only | | `POST /api/v1/profiler/address/counterparties/batch` | `solana` only — checked per address, so one native address rejects the whole batch | Two patterns are worth internalising: * **Per-holder PnL is unavailable for native tokens on every chain.** Both PnL leaderboards reject them outright, as does TGM Flows. A native coin is spent as gas in nearly every transaction on its chain, so a per-holder cost basis does not carry the same meaning it does for a traded contract token. * **Solana is blocked on more endpoints than other chains.** Native SOL appears in almost every Solana transaction, which makes these queries prohibitively expensive to serve. Note that this does **not** mean all flow analytics are off-limits: [Flow Intelligence](#flow-intelligence-uses-a-different-source) does support native tokens, and only serves them from a different source. #### Token God Mode Holders behaves differently for native tokens `POST /api/v1/tgm/holders` **does** support native tokens (except on Solana), but one specific combination is served from a different, purpose-built data path that trades flexibility for the ability to return at all. You are on that path when **all** of the following hold: * the token is a native token (or a major stablecoin), **and** * `label_type` is `"all_holders"`, **and** * `aggregate_by_entity` is `false`, **and** * the chain is **not** `bitcoin` — Bitcoin always uses the entity-based path instead. Change any one of those and the endpoint behaves normally. On that path, unsupported options return **HTTP 400**: | Restriction | Detail | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Filters | Only `include_smart_money_labels`, `exclude_smart_money_labels`, `address`, `token_amount`, `total_inflow`, `total_outflow`. Filters such as `value_usd`, `ownership_percentage`, and balance-change filters are **not** available. | | `address` filter | Accepts a **single** address only, not a list. | | Sorting | Only `token_amount` is sortable (default `DESC`). | {% hint style="info" %} **Dust holders are included.** Elsewhere this endpoint applies a default minimum of $1 in holdings. On the path described above that default is **not** applied, so results include holders worth well under $1. Add a `token_amount` filter if you need a floor. {% endhint %} #### Flow Intelligence uses a different source `POST /api/v1/tgm/flow-intelligence` serves native tokens from an entity-based flow dataset rather than the standard token-transfer dataset. The response shape is the same, but figures are not directly comparable to a contract token's, and segment breakdowns may be coarser. Treat native-token flow figures as directional rather than as an exact match to contract-token methodology. #### Two status codes worth recognising Native tokens cover far more holders and transfers than a typical contract token, so these two responses are worth knowing when you query them: | Status | What the API returns | What it means | | ------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `512` | `Query timed out. Please try adjusting the time range or filtering the data.` | The query exceeded its time budget. Narrow the date range or add filters, as the message says. | | `514` | `Unauthorized. Please try with different parameters or another endpoint.` | Despite the wording, this is **not** an API-key problem — a valid key returns it. It signals that the backend would not serve this particular query. Some Token God Mode analytics on native tokens are a known cause, so try different parameters or another endpoint before treating it as an auth failure. | See [Error Handling](/getting-started/error-handling) for the general error model. ### The `include_native_tokens` filter Some endpoints return a portfolio, flow, or screen across *many* tokens rather than taking a single `token_address`. Because native holdings usually dominate those aggregates in USD terms, these endpoints let you include or exclude native tokens explicitly via a filter: ```json { "filters": { "include_native_tokens": true } } ``` | Endpoint | Default | | --------------------------------------------------------- | ------------------------------------ | | `POST /api/v1/smart-money/holdings` | `false` — native tokens **excluded** | | `POST /api/v1/smart-money/netflow` | `false` — native tokens **excluded** | | `POST /api/v1/smart-money/historical-holdings` | `false` — native tokens **excluded** | | `POST /api/v1/token-screener` | `false` — native tokens **excluded** | | `POST /api/v1beta1/smart-money/historical-token-balances` | `true` — native tokens **included** | On two of these the flag covers more than the native coin itself: * **Token screener** — also admits wrapped-native assets and liquid staking / restaking derivatives (LSTs and LRTs). * **`historical-token-balances`** — also admits LSTs and LRTs. So on those endpoints, toggling the flag moves a broader set of rows than the native coin alone. {% hint style="warning" %} **The default is not the same everywhere.** Most of these endpoints default to *excluding* native tokens, but `historical-token-balances` defaults to *including* them. If you are comparing results across these endpoints, set `include_native_tokens` explicitly rather than relying on the default. {% endhint %} This filter exists only on the endpoints listed above. Sending it elsewhere is not reliably an error: most filter models reject unknown keys with **HTTP 422**, but some accept and silently ignore them, so the request succeeds while the flag does nothing. Don't infer from a `200` that an endpoint honoured `include_native_tokens` — only rely on it where it is documented. ### Quick reference * Native tokens are addressed by a per-chain placeholder, not a contract address. * One placeholder covers every EVM chain; `chain` selects which native coin you mean. * Copy placeholders exactly; miscasing the Solana or SUI placeholder fails silently rather than erroring. * PnL leaderboards and TGM Flows reject native tokens on all chains; DEX trades and transfers are blocked on some chains; holders, balances, and Flow Intelligence work with restrictions. * On multi-token endpoints, set `include_native_tokens` explicitly rather than relying on the default. # Filter Types ### Overview Filters allow you to narrow down API results to specific criteria. Each endpoint supports different filters based on the data it returns. ### Filter Types #### NumericRangeFilter Filter numeric values (floats) with optional min/max bounds. **Schema:** ```json { "min": 1000.0, "max": 50000.0 } ``` **Fields:** | Field | Type | Description | | ----- | ----- | ------------------------- | | `min` | float | Minimum value (inclusive) | | `max` | float | Maximum value (inclusive) | **Examples:** ```json // Minimum only {"min": 1000000} // Maximum only {"max": 50000} // Range {"min": 1000, "max": 1000000} // Negative values allowed {"min": -10.5, "max": 100.75} ``` **Common Uses:** * `value_usd` - Filter by USD value * `price_usd` - Filter by price * `market_cap_usd` - Filter by market cap * `volume_24h_usd` - Filter by volume #### IntegerRangeFilter Filter integer values with optional min/max bounds. **Schema:** ```json { "min": 10, "max": 1000 } ``` **Fields:** | Field | Type | Description | | ----- | ------- | ------------------------- | | `min` | integer | Minimum value (inclusive) | | `max` | integer | Maximum value (inclusive) | **Examples:** ```json // Minimum holders {"min": 100} // Age range {"min": 7, "max": 365} ``` **Common Uses:** * `holder_count` - Filter by number of holders * `token_age_days` - Filter by token age * `trade_count` - Filter by number of trades #### DateRangeFilter Filter by date/time ranges. **Schema:** ```json { "from": "2025-01-01T00:00:00Z", "to": "2025-01-31T23:59:59Z" } ``` **Fields:** | Field | Type | Description | | ------ | ------ | ---------------------------- | | `from` | string | Start date (ISO 8601 format) | | `to` | string | End date (ISO 8601 format) | **Formats:** ```json // Full datetime "2025-01-01T00:00:00Z" // Date only "2025-01-01" ``` **Examples:** ```json // Last 7 days { "from": "2025-01-07T00:00:00Z", "to": "2025-01-14T00:00:00Z" } // Specific month { "from": "2025-01-01", "to": "2025-01-31" } ``` #### TokenAddressFilter Filter by one or more token addresses. **Schema:** ```json "0x..." // or ["0x...", "0x..."] ``` **Examples:** ```json // Single token "token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933" // Multiple tokens "token_addresses": [ "0x6982508145454ce325ddbe47a25d4ec3d2311933", "0xdac17f958d2ee523a2206206994597c13d831ec7" ] ``` #### TraderAddressFilter Filter by one or more trader/wallet addresses. **Schema:** ```json "0x..." // or ["0x...", "0x..."] ``` **Examples:** ```json // Single trader "trader_address": "0x28C6c06298d514Db089934071355E5743bf21d60" // Multiple traders "trader_addresses": [ "0x28C6c06298d514Db089934071355E5743bf21d60", "0x47ac0Fb4F2D84898e4D9E7b4DaB3C24507a6D503" ] ``` #### LabelFilter Filter by smart money or entity labels. **Schema:** ```json ["Fund", "Smart Trader"] ``` **Smart Money Labels:** ```json [ "Fund", "Smart Trader", "30D Smart Trader", "90D Smart Trader", "180D Smart Trader", "Smart HL Perps Trader" ] ``` **Extended Labels:** ```json [ "Public Figure", "Exchange", "Whale", "BananaGun Bot User", "Maestro Bot User" ] ``` **Examples:** ```json // Include funds and smart traders "include_smart_money_labels": ["Fund", "Smart Trader"] // Exclude exchanges "exclude_labels": ["Exchange"] ``` #### SectorsFilter Filter by token sector/category. **Schema:** ```json ["DeFi", "Meme"] ``` **Common Sectors:** ```json [ "DeFi", "Meme", "Gaming", "NFT", "Infrastructure", "Layer 1", "Layer 2", "Stablecoin", "AI", "RWA" ] ``` **Examples:** ```json // DeFi tokens only "sectors": ["DeFi"] // Multiple sectors "sectors": ["Meme", "Gaming"] ``` #### BooleanFilter Simple true/false filter. **Schema:** ```json true // or false ``` **Examples:** ```json // Hide spam tokens "hide_spam_tokens": true // Include only new positions "only_new_positions": true ``` ### Filter Validation Rules #### Range Filters 1. `max` must be greater than `min` if both provided 2. Some fields require positive values only ```json // Invalid - max less than min {"min": 1000, "max": 500} // Invalid for some fields - negative min {"min": -100} ``` #### Date Filters 1. `to` must be after `from` 2. Maximum range is typically 1 year ```json // Invalid - to before from { "from": "2025-12-31", "to": "2025-01-01" } ``` #### Address Filters 1. Must match chain address format 2. Cannot be burn/zero addresses for some endpoints ### Using Filters in Requests #### Basic Filter Usage ```python response = client.post( "https://api.nansen.ai/api/v1/smart-money/holdings", json={ "chains": ["ethereum"], "filters": { "value_usd": {"min": 100000}, "include_smart_money_labels": ["Smart Trader"] } } ) ``` #### Combining Multiple Filters ```python response = client.post( "https://api.nansen.ai/api/v1/token-screener", json={ "chains": ["ethereum"], "filters": { "market_cap_usd": {"min": 1000000, "max": 100000000}, "volume_24h_usd": {"min": 50000}, "holder_count": {"min": 100}, "token_age_days": {"min": 7}, "sectors": ["DeFi", "Meme"], "hide_spam_tokens": true } } ) ``` #### Endpoint-Specific Filters Different endpoints support different filters. Check each endpoint's documentation for available filters. # Sorting ### Overview Most Nansen API endpoints support sorting results using the `order_by` parameter. This allows you to control the order of returned data. ### Sort Order Schema ```json { "order_by": [ { "field": "field_name", "direction": "DESC" } ] } ``` #### Parameters | Parameter | Type | Description | | ----------- | ------ | ---------------------------------------- | | `field` | string | The field to sort by | | `direction` | string | `ASC` (ascending) or `DESC` (descending) | #### Directions | Direction | Description | Example | | --------- | -------------------------- | --------------------------- | | `ASC` | Ascending (smallest first) | 1, 2, 3, ... or A, B, C | | `DESC` | Descending (largest first) | 100, 99, 98, ... or Z, Y, X | ### Examples #### Single Field Sort Sort by USD value, highest first: ```json { "order_by": [ {"field": "value_usd", "direction": "DESC"} ] } ``` #### Multiple Field Sort Sort by volume first, then by price: ```json { "order_by": [ {"field": "volume_24h_usd", "direction": "DESC"}, {"field": "price_usd", "direction": "ASC"} ] } ``` #### Full Request Example ```python response = client.post( "https://api.nansen.ai/api/v1/smart-money/holdings", json={ "chains": ["ethereum"], "pagination": {"page": 1, "per_page": 100}, "order_by": [ {"field": "value_usd", "direction": "DESC"} ] } ) ``` ### Common Sort Fields by Endpoint #### Smart Money Holdings | Field | Description | | ---------------------------- | --------------------------------- | | `value_usd` | Total USD value of holdings | | `balance_24h_percent_change` | 24-hour balance change percentage | | `holders_count` | Number of smart money holders | | `share_of_holdings_percent` | Share of total token supply held | | `market_cap_usd` | Token market capitalization | | `token_age_days` | Days since token creation | ```json { "order_by": [{"field": "value_usd", "direction": "DESC"}] } ``` #### Smart Money Netflow | Field | Description | | ------------------ | ----------------------------- | | `net_flow_1h_usd` | 1-hour net flow in USD | | `net_flow_24h_usd` | 24-hour net flow in USD | | `net_flow_7d_usd` | 7-day net flow in USD | | `net_flow_30d_usd` | 30-day net flow in USD | | `trader_count` | Number of smart money traders | | `market_cap_usd` | Token market capitalization | ```json { "order_by": [{"field": "net_flow_24h_usd", "direction": "DESC"}] } ``` #### Smart Money DEX Trades | Field | Description | | ----------- | ------------------- | | `timestamp` | Trade timestamp | | `value_usd` | Trade value in USD | | `amount` | Token amount traded | ```json { "order_by": [{"field": "timestamp", "direction": "DESC"}] } ``` #### Token Screener | Field | Description | | -------------------------- | ------------------------ | | `market_cap_usd` | Market capitalization | | `volume_24h_usd` | 24-hour trading volume | | `price_change_24h_percent` | 24-hour price change | | `holder_count` | Total holder count | | `smart_money_holder_count` | Smart money holder count | | `liquidity_usd` | Total liquidity | ```json { "order_by": [ {"field": "volume_24h_usd", "direction": "DESC"}, {"field": "market_cap_usd", "direction": "DESC"} ] } ``` #### TGM Holders | Field | Description | | -------------------------- | ---------------------- | | `balance_usd` | Current balance in USD | | `balance_change_24h_usd` | 24-hour balance change | | `first_transfer_timestamp` | First transfer date | | `last_transfer_timestamp` | Last transfer date | ```json { "order_by": [{"field": "balance_usd", "direction": "DESC"}] } ``` #### TGM PnL Leaderboard | Field | Description | | -------------------- | ---------------------- | | `realized_pnl_usd` | Realized profit/loss | | `unrealized_pnl_usd` | Unrealized profit/loss | | `total_pnl_usd` | Total profit/loss | | `roi_percent` | Return on investment | ```json { "order_by": [{"field": "total_pnl_usd", "direction": "DESC"}] } ``` ### Best Practices #### 1. Always Sort When Paginating Ensure consistent ordering across pages: ```python # Good - consistent ordering for page in range(1, 10): response = client.post(url, json={ "pagination": {"page": page, "per_page": 100}, "order_by": [{"field": "value_usd", "direction": "DESC"}] }) # Bad - order may change between pages for page in range(1, 10): response = client.post(url, json={ "pagination": {"page": page, "per_page": 100} }) ``` #### 2. Use Secondary Sort for Ties Add a secondary sort field to break ties: ```json { "order_by": [ {"field": "volume_24h_usd", "direction": "DESC"}, {"field": "token_address", "direction": "ASC"} ] } ``` #### 3. Sort by Timestamp for Recent Data For trade/transaction data, sort by timestamp: ```json { "order_by": [{"field": "timestamp", "direction": "DESC"}] } ``` #### 4. Consider Default Sorts Many endpoints have sensible default sorts. Check the endpoint documentation for defaults. ### Error Handling #### Invalid Sort Field ```json { "detail": [ { "type": "enum", "loc": ["body", "order_by", 0, "field"], "msg": "Input should be 'value_usd', 'balance_24h_percent_change', ..." } ] } ``` #### Invalid Direction ```json { "detail": [ { "type": "enum", "loc": ["body", "order_by", 0, "direction"], "msg": "Input should be 'ASC' or 'DESC'" } ] } ``` ### Python Helper ```python from enum import Enum from typing import Literal class SortDirection(str, Enum): ASC = "ASC" DESC = "DESC" def create_sort_order( field: str, direction: Literal["ASC", "DESC"] = "DESC" ) -> dict: return {"field": field, "direction": direction} # Usage sort = create_sort_order("value_usd", "DESC") ``` # Endpoints Overview ### Overview The Nansen API includes endpoints across different usecases: Spot, Perps, Prediction Markets, Agent and Backtesting data. All endpoints use `POST` requests with JSON bodies. ### Smart Money A curated list of the top 5 000 highest-performing wallets ranked by realised profit, winrate, and strong performance across market cycles.
EndpointCreditDescription
smart-money/netflow5Provides net flow of tokens bought/sold by Smart Money addresses
smart-money/holdings5Holdings of tokens by Smart Money addresses.
smart-money/historical-holdings1All Historical Holdings of Smart Money Wallets
smart-money/dex-trades5All dex trades of smart money traders in the last 24h
smart-money/dcas5All Jupiter DCAs started by Smart Money Wallets on Solana
smart-money/perp-trades5Track what smart money wallets are trading on Hyperliquid
### Agent
EndpointCreditDescription
agent/fast200Ask Nansen Agent any question in fast mode
agent/expert750Ask Nansen Agent any question in expert mode
### Profiler A toolkit for diving deep into address relationships and behaviour, letting you analyse any wallet or entity cluster to uncover flows, counterparties, and behavioural patterns.
EndpointCreditDescription
profiler/address/current-balance1Current Token balances of an address
profiler/address/historical-balances1Historical holdings of a wallet address
profiler/perp-positions1Fetch current positions, PnL and account health of a wallet
profiler/address/transactions1List of transactions made by an address
profiler/perp-trades1Get all Hyperliquid trades of a wallet
profiler/address/related-wallets1List of related wallets and its first degree relation
profiler/address/pnl-summary1Trade summary including top 5 trades
profiler/address/pnl1List of Past Trades and their performance made by the address
profiler/dex-trades1List of all trades made by an address
profiler/address/counterparties5Top Counterparties a wallet has interacted with
perp-leaderboard5Get a list of most profitable Hyperliquid addresses
profiler/address/labels (Common labels)nullAddress and its labels, without premium labels
profiler/address/premium-labels (Premium labels)nullAddress and all its labels, including premium labels
### Token God Mode A comprehensive lens on a token’s on-chain activity, combining Smart Money movements, holder-base analysis, and exchange-flow tracking in one view.
EndpointCreditsDescription
token-screener1A token screening endpoint that provides real-time analytics and insights across multiple blockchain networks.
perp-screener1Discover and screen tokens on Hyperliquid with the highest volume and smart money activity.
tgm/flow-intelligence1Summary of token flows across Smart Money, exchanges, Top PnL Traders, Public Figures, Whales, Fresh Wallets
tgm/holders
(150 credits if premium_labels=true is passed)		5 (150 if premium_labels=true)Balance of top addresses, smart money, exchanges, public figures and whales that can be queried by address or by entity.
tgm/perp-positions5See all open positions for a specific perp token including leverage, PnL, and liquidation prices
tgm/flows1Total Inflow and outflow of a token from smart money, exchanges, public figures or whales.
tgm/who-bought-sold1Recent buyers and sellers of a token summarised
tgm/perp-trades1View trading history for a specific perp token over a time period
tgm/dex-trades1All DEX Trades of a Token
tgm/transfers1Top Token Transfers of a token
tgm/jup-dca1List of all Jupiter DCA orders of a token on Solana
tgm/pnl-leaderboard
(150 credits if premium_labels=true is passed)		5 (150 if premium_labels=true)List of addresses and their total realised and unrealised PnL
tgm/perp-pnl-leaderboard
(150 credits if premium_labels=true is passed)		5 (150 if premium_labels=true)List of addresses and their PnL for a specific token on Hyperliquid
tgm/token-information1Get stats about Token Marketcap, Volume, Holders, Traders, etc
tgm/indicators5Get risk and reward indicators for a specific token.
tgm/token-ohlcv1Get unified OHLCVdata for tokens
### Prediction Market API
EndpointCreditsDescription
prediction-market/categories1Aggregated stats for all categories
prediction-market/market-screener1Browse and all Polymarket prediction markets.
prediction-market/event-screener1Browse and filter Polymarket events
prediction-market/orderbook1Get bid/ask orderbook for a market
prediction-market/ohlcv1Get 1-hour OHLCV for a market
prediction-market/trades-by-market1Get recent trades for a market
prediction-market/trades-by-address1Trades for a wallet across all markets
prediction-market/pnl-by-address1PnL for a wallet across all markets
prediction-market/address-summary1Get PnL, win rate and age of a wallet active on Polymarket
prediction-market/top-holders5Get the largest position holders for market
prediction-market/position-detail5Get per-token position data for all holders in a specific market
prediction-market/pnl-by-market5PnL for all traders in a specific market
### Portfolio API
EndpointCreditsDescription
portfolio/defi-holdings1Track DeFi positions of all addresses
### Backtesting API Backtest your strategies against the same onchain intelligence that powers Nansen at any point in time.
EndpointCredits per call
tgm/historical-dex-trades5
tgm/historical-who-bought-sold5
tgm/historical-token-flow-summary5
token-screener/historical5
profiler/address/historical-token-balances5
profiler/address/historical-transactions5
profiler/historical-transaction-lookup5
tgm/historical-top-holders25
tgm/historical-pnl-leaderboard25
tgm/historical-token-quant-scores25
smart-money/historical-token-balances25
tgm/historical-token-recent-flows-summary-perps5
# Data Coverage by Chain How far back Nansen data goes on each chain, and how fresh live data is. This page is the single source of truth for **how far back Nansen indexes each chain** and **how fresh live data is**. Individual endpoint pages link here for historical coverage; any endpoint that applies its own stricter limit says so on its own page. ### Data freshness * **Live data (queries whose date range includes today):** underlying on-chain activity is indexed in near real time — typically reflected within seconds to a couple of minutes. Some endpoints additionally serve current-day responses from a short cache (up to 5 minutes) to protect performance. * **Historical data (fully past date ranges):** intended for point-in-time analysis after a short settlement period. Historical endpoints avoid look-ahead bias where point-in-time sources are available, but results are not immutable response snapshots. Results may still be revised for late-arriving or backfilled onchain data, data-quality corrections, historical-price fixes, attribution or label-history updates, token metadata changes, sector reclassification, and blacklist updates. Recently-closed windows are served fresh until they settle. ### Historical coverage Each chain is indexed from its genesis (or Nansen's onboarding point for that chain) forward. Earliest available data: | Chain | Data available from | | --------------- | ------------------- | | Ethereum | 30 Jul 2015 | | Tron | 25 Jun 2018 | | TON | 15 Nov 2019 | | Solana | 17 Mar 2020 | | Polygon | 30 May 2020 | | NEAR | 21 Jul 2020 | | BNB Chain (BSC) | 29 Aug 2020 | | Avalanche | 23 Sep 2020 | | Ronin | 25 Jan 2021 | | Arbitrum | 29 May 2021 | | Injective | 30 Jun 2021 | | Optimism | 11 Nov 2021 | | Starknet | 04 Apr 2022 | | Chiliz | 08 Feb 2023 | | Sui | 12 Apr 2023 | | Base | 15 Jun 2023 | | Mantle | 02 Jul 2023 | | Linea | 06 Jul 2023 | | Scroll | 10 Oct 2023 | | IOTA EVM | 15 Mar 2024 | | Sei | 27 May 2024 | | Mantra | 17 Oct 2024 | | Sonic | 01 Dec 2024 | | HyperEVM | 18 Feb 2025 | | Katana | 08 May 2025 | | Monad | 14 May 2025 | | Somnia | 22 May 2025 | | Plasma | 03 Sep 2025 | | Citrea | 25 Nov 2025 | | Robinhood | 30 Apr 2026 | | Arc | 15 Jul 2026 | Chains that onboarded before mid-2023 (Ethereum through Linea above) offer **3+ years** of history; newer chains offer proportionally less. {% hint style="info" %} **Hyperliquid perpetuals** (e.g. the perp PnL leaderboard) are a separate dataset from the chains above, with reliable data from **May 2025** onward. {% endhint %} {% hint style="info" %} **Prediction markets** (Polymarket) are a separate dataset from the chains above. Trade, price, and PnL history is available from **November 2022** onward, and updates live (within the standard latency). {% endhint %} ### How this maps to endpoints Coverage also varies by **token type**, not just by chain: native coins (ETH, BTC, SOL, …) are supported on fewer endpoints than contract tokens, and with restrictions where supported. See [Native Tokens](/reference/native-tokens). For most endpoints, coverage for a given chain equals the start date above. An endpoint returns data as far back as the chain allows, bounded only by your requested date range. Where an endpoint enforces its own limit (for example, a reduced max date range per request for a few extremely high-volume addresses), that limit is documented on the endpoint's own page. # Search ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); these endpoints follow it except where noted below. * Returns **current results from the live search index** — token, entity-name, and sector lookups have no date-range parameter or historical look-back; results always reflect the latest indexed tokens, entities, and sectors. * Any **price, volume, or market-cap figures** shown alongside search results are indicative and may lag live markets — use the dedicated price or OHLCV endpoints when you need up-to-the-moment values. ## Search across all categories > Search for tokens and entities by name, symbol, or contract address. This endpoint provides a unified search experience across all Nansen data.\ > \ > \*\*Use Cases:\*\*\ > 1\. \*\*Find token addresses\*\*: Search by name or symbol to get contract addresses (e.g., "AAVE", "Uniswap")\ > 2\. \*\*Discover entities\*\*: Find known entities like exchanges, funds, and public figures (e.g., "vitalik", "Binance")\ > 3\. \*\*Resolve addresses\*\*: Search by contract address to identify tokens\ > 4\. \*\*Filter by chain\*\*: Narrow down results to specific blockchains\ > \ > \*\*Search Parameters:\*\*\ > \- \`search\_query\`: Token name, symbol, contract address, or entity name\ > \- \`result\_type\`: Filter by "token", "entity", or "any" (default: "any")\ > \- \`chain\`: Optional blockchain filter (e.g., "ethereum", "solana", "base")\ > \- \`limit\`: Maximum results (1-50, default: 25)\ > \ > \*\*Example Request:\*\*\ > \`\`\`json\ > {\ > "search\_query": "AAVE",\ > "result\_type": "token",\ > "chain": "ethereum"\ > }\ > \`\`\`\ > \ > \*\*Example Response:\*\*\ > \`\`\`json\ > {\ > "tokens": \[\ > {\ > "name": "Aave",\ > "symbol": "AAVE",\ > "chain": "ethereum",\ > "address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",\ > "price": 123.45,\ > "volume\_24h": 50000000,\ > "market\_cap": 1500000000,\ > "rank": 25\ > }\ > ],\ > "entities": \[],\ > "total\_results": 1\ > }\ > \`\`\`\ > \ > \*\*Important Notes:\*\*\ > \- Prices may be delayed; use token OHLCV endpoints for real-time prices\ > \- Results are sorted by relevance/popularity rank\ > \- Use the \`chain\` parameter (not the query string) to filter by blockchain ````json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"}},"schemas":{"GeneralSearchRequest":{"properties":{"search_query":{"type":"string","maxLength":200,"minLength":1,"title":"Search Query","description":"Search query - token name, symbol, contract address, or entity name."},"result_type":{"type":"string","enum":["token","entity","any"],"title":"Result Type","description":"Type filter - 'token' for tokens only, 'entity' for entities only, 'any' for both.","default":"any"},"chain":{"anyOf":[{"type":"string"}],"title":"Chain","description":"Optional chain filter to narrow down token results (e.g., 'ethereum', 'solana', 'base')."},"limit":{"type":"integer","maximum":50,"minimum":1,"title":"Limit","description":"Maximum number of results to return (default: 25, max: 50).","default":25}},"additionalProperties":false,"type":"object","required":["search_query"],"title":"GeneralSearchRequest","description":"Request model for general search endpoint.\n\nThis endpoint searches for tokens and entities by name, symbol, or address."},"GeneralSearchResponse":{"properties":{"tokens":{"items":{"$ref":"#/components/schemas/TokenSearchResult"},"type":"array","title":"Tokens","description":"List of matching tokens","default":[]},"entities":{"items":{"$ref":"#/components/schemas/EntitySearchResult"},"type":"array","title":"Entities","description":"List of matching entities","default":[]},"total_results":{"type":"integer","title":"Total Results","description":"Total number of results returned"}},"type":"object","required":["total_results"],"title":"GeneralSearchResponse","description":"Response model for general search endpoint.\n\nReturns separate lists for tokens and entities, allowing clients to handle\neach type appropriately."},"TokenSearchResult":{"properties":{"name":{"type":"string","title":"Name","description":"Token name"},"symbol":{"type":"string","title":"Symbol","description":"Token symbol (ticker)"},"chain":{"type":"string","title":"Chain","description":"Blockchain the token is deployed on"},"address":{"type":"string","title":"Address","description":"Contract address of the token"},"price":{"anyOf":[{"type":"number"}],"title":"Price","description":"Current price in USD (may be delayed)"},"volume_24h":{"anyOf":[{"type":"number"}],"title":"Volume 24H","description":"24-hour trading volume in USD"},"market_cap":{"anyOf":[{"type":"number"}],"title":"Market Cap","description":"Market capitalization in USD"},"rank":{"anyOf":[{"type":"integer"}],"title":"Rank","description":"Popularity/relevance rank (lower is better)"}},"type":"object","required":["name","symbol","chain","address"],"title":"TokenSearchResult","description":"A token result from general search."},"EntitySearchResult":{"properties":{"name":{"type":"string","title":"Name","description":"Entity name"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Category tags for the entity","default":[]},"rank":{"anyOf":[{"type":"integer"}],"title":"Rank","description":"Popularity/relevance rank (lower is better)"}},"type":"object","required":["name"],"title":"EntitySearchResult","description":"An entity result from general search."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/search/general":{"post":{"tags":["Search"],"summary":"Search across all categories","description":"Search for tokens and entities by name, symbol, or contract address. This endpoint provides a unified search experience across all Nansen data.\n\n**Use Cases:**\n1. **Find token addresses**: Search by name or symbol to get contract addresses (e.g., \"AAVE\", \"Uniswap\")\n2. **Discover entities**: Find known entities like exchanges, funds, and public figures (e.g., \"vitalik\", \"Binance\")\n3. **Resolve addresses**: Search by contract address to identify tokens\n4. **Filter by chain**: Narrow down results to specific blockchains\n\n**Search Parameters:**\n- `search_query`: Token name, symbol, contract address, or entity name\n- `result_type`: Filter by \"token\", \"entity\", or \"any\" (default: \"any\")\n- `chain`: Optional blockchain filter (e.g., \"ethereum\", \"solana\", \"base\")\n- `limit`: Maximum results (1-50, default: 25)\n\n**Example Request:**\n```json\n{\n \"search_query\": \"AAVE\",\n \"result_type\": \"token\",\n \"chain\": \"ethereum\"\n}\n```\n\n**Example Response:**\n```json\n{\n \"tokens\": [\n {\n \"name\": \"Aave\",\n \"symbol\": \"AAVE\",\n \"chain\": \"ethereum\",\n \"address\": \"0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9\",\n \"price\": 123.45,\n \"volume_24h\": 50000000,\n \"market_cap\": 1500000000,\n \"rank\": 25\n }\n ],\n \"entities\": [],\n \"total_results\": 1\n}\n```\n\n**Important Notes:**\n- Prices may be delayed; use token OHLCV endpoints for real-time prices\n- Results are sorted by relevance/popularity rank\n- Use the `chain` parameter (not the query string) to filter by blockchain","operationId":"general_search_api_v1_search_general_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneralSearchRequest"}}},"required":true},"responses":{"200":{"description":"Search results with tokens and entities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneralSearchResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ```` ## Search for entity names by query > Search for entity names to use in other v1 endpoints that support \`entity\_name\` parameters.\ > \ > This endpoint helps users find the correct entity name format when they want to query by entity instead of address. Many endpoints accept either \`address\` or \`entity\_name\` as parameters, but entity names must match exactly. This search endpoint makes it easy to find the right entity name.\ > \ > \*\*Key Features:\*\*\ > \- Case-insensitive search that matches anywhere in the entity name\ > \- Returns up to 100 results ordered alphabetically\ > \- Minimum 2 character search query required\ > \- Free endpoint (0 credits)\ > \ > \*\*Use Cases:\*\*\ > 1\. \*\*Find entity names for profiler endpoints\*\*: Search "vitalik" to find "Vitalik Buterin" for use in address balance or transaction queries\ > 2\. \*\*Discover exchange entities\*\*: Search "binance" to find all Binance-related entities\ > 3\. \*\*Locate fund entities\*\*: Search "jump" to find "Jump Trading" and related entities\ > \ > \*\*Example Usage:\*\*\ > \`\`\`json\ > {\ > "search\_query": "vitalik"\ > }\ > \`\`\`\ > \ > \*\*Response:\*\*\ > \`\`\`json\ > {\ > "data": \[\ > {"entity\_name": "Vitalik Buterin"},\ > {"entity\_name": "Vitalik Buterin: Charity"}\ > ]\ > }\ > \`\`\`\ > \ > \*\*Note:\*\* This endpoint does not support pagination as results are capped at 100 items. ````json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"}},"schemas":{"EntityNameSearchRequest":{"properties":{"search_query":{"type":"string","maxLength":100,"minLength":2,"title":"Search Query","description":"Search query for entity names (minimum 2 characters). Search is case-insensitive and matches anywhere in the entity name."}},"additionalProperties":false,"type":"object","required":["search_query"],"title":"EntityNameSearchRequest","description":"Request model for entity name search endpoint.\n\nThis endpoint helps users find the correct entity_name to use in other\nv1 endpoints that accept entity_name as a parameter."},"EntityNameSearchResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/EntityNameSearchItem"},"type":"array","title":"Data","description":"List of matching entity names (max 100 results, ordered alphabetically)"}},"type":"object","required":["data"],"title":"EntityNameSearchResponse","description":"Response model for entity name search endpoint.\n\nReturns up to 100 entity names ordered alphabetically.\nNo pagination is provided as results are limited to 100 items."},"EntityNameSearchItem":{"properties":{"entity_name":{"type":"string","title":"Entity Name","description":"Entity name that can be used in other v1 endpoints"}},"type":"object","required":["entity_name"],"title":"EntityNameSearchItem","description":"Single entity name result."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/search/entity-name":{"post":{"tags":["Search"],"summary":"Search for entity names by query","description":"Search for entity names to use in other v1 endpoints that support `entity_name` parameters.\n\nThis endpoint helps users find the correct entity name format when they want to query by entity instead of address. Many endpoints accept either `address` or `entity_name` as parameters, but entity names must match exactly. This search endpoint makes it easy to find the right entity name.\n\n**Key Features:**\n- Case-insensitive search that matches anywhere in the entity name\n- Returns up to 100 results ordered alphabetically\n- Minimum 2 character search query required\n- Free endpoint (0 credits)\n\n**Use Cases:**\n1. **Find entity names for profiler endpoints**: Search \"vitalik\" to find \"Vitalik Buterin\" for use in address balance or transaction queries\n2. **Discover exchange entities**: Search \"binance\" to find all Binance-related entities\n3. **Locate fund entities**: Search \"jump\" to find \"Jump Trading\" and related entities\n\n**Example Usage:**\n```json\n{\n \"search_query\": \"vitalik\"\n}\n```\n\n**Response:**\n```json\n{\n \"data\": [\n {\"entity_name\": \"Vitalik Buterin\"},\n {\"entity_name\": \"Vitalik Buterin: Charity\"}\n ]\n}\n```\n\n**Note:** This endpoint does not support pagination as results are capped at 100 items.","operationId":"search_entity_names_api_v1_search_entity_name_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNameSearchRequest"}}},"required":true},"responses":{"200":{"description":"List of matching entity names","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNameSearchResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ```` ## Get Available Token Sectors > Get all available token sectors that can be used to filter tokens in the token-screener and other endpoints.\ > \ > This endpoint returns the list of valid sector values that can be used in the \`token\_sector\` filter parameter. Sectors are categories that describe a token's primary use case or market segment (e.g., "Artificial Intelligence", "DeFi Lending", "Memecoin").\ > \ > \*\*Key Features:\*\*\ > \- Returns all sectors with 50+ tokens (filters out niche/one-off AI-generated sectors)\ > \- Results are ordered alphabetically\ > \- No parameters required\ > \- Free endpoint (0 credits)\ > \ > \*\*Example Response:\*\*\ > \`\`\`json\ > {\ > "data": \[\ > {"sector": "AI Agents"},\ > {"sector": "Artificial Intelligence"},\ > {"sector": "DeFi Lending (Money Markets)"},\ > {"sector": "GameFi"},\ > {"sector": "Memecoin"}\ > ]\ > }\ > \`\`\`\ > \ > \*\*Use Cases:\*\*\ > 1\. \*\*Discover filter options\*\*: Get valid sector values before calling token-screener\ > 2\. \*\*Build UI filters\*\*: Populate dropdown menus with available sectors\ > 3\. \*\*Validate input\*\*: Check if a sector value is valid before making API calls ````json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"}},"schemas":{"TokenSectorsResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TokenSectorItem"},"type":"array","title":"Data","description":"List of available token sectors (ordered alphabetically)"}},"type":"object","required":["data"],"title":"TokenSectorsResponse","description":"Response model for token sectors endpoint.\n\nReturns all available token sectors that can be used to filter tokens\nin the token-screener and other endpoints that support sector filtering.\nSectors with fewer than 50 tokens are excluded."},"TokenSectorItem":{"properties":{"sector":{"type":"string","title":"Sector","description":"Token sector name (e.g., 'Artificial Intelligence', 'DeFi Lending (Money Markets)')"}},"type":"object","required":["sector"],"title":"TokenSectorItem","description":"Single token sector result."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/search/token-sectors":{"get":{"tags":["Search"],"summary":"Get Available Token Sectors","description":"Get all available token sectors that can be used to filter tokens in the token-screener and other endpoints.\n\nThis endpoint returns the list of valid sector values that can be used in the `token_sector` filter parameter. Sectors are categories that describe a token's primary use case or market segment (e.g., \"Artificial Intelligence\", \"DeFi Lending\", \"Memecoin\").\n\n**Key Features:**\n- Returns all sectors with 50+ tokens (filters out niche/one-off AI-generated sectors)\n- Results are ordered alphabetically\n- No parameters required\n- Free endpoint (0 credits)\n\n**Example Response:**\n```json\n{\n \"data\": [\n {\"sector\": \"AI Agents\"},\n {\"sector\": \"Artificial Intelligence\"},\n {\"sector\": \"DeFi Lending (Money Markets)\"},\n {\"sector\": \"GameFi\"},\n {\"sector\": \"Memecoin\"}\n ]\n}\n```\n\n**Use Cases:**\n1. **Discover filter options**: Get valid sector values before calling token-screener\n2. **Build UI filters**: Populate dropdown menus with available sectors\n3. **Validate input**: Check if a sector value is valid before making API calls","operationId":"get_token_sectors_api_v1_search_token_sectors_get","responses":{"200":{"description":"List of available token sectors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenSectorsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ```` # Smart Money ### Overview Smart Money endpoints provide insights into the trading and holding activity of sophisticated market participants, including institutional funds and historically profitable traders. ### Endpoints | Endpoint | Path | Description | | ------------------- | ----------------------------------------- | --------------------------------------- | | Netflow | `/api/v1/smart-money/netflow` | Net capital flows (inflows vs outflows) | | DEX Trades | `/api/v1/smart-money/dex-trades` | Real-time DEX trading activity | | Perp Trades | `/api/v1/smart-money/perp-trades` | Perpetual trading on Hyperliquid | | DCAs | `/api/v1/smart-money/dcas` | DCA strategies on Jupiter | | Holdings | `/api/v1/smart-money/holdings` | Aggregated token balances | | Historical Holdings | `/api/v1/smart-money/historical-holdings` | Historical balance snapshots | ### Supported Chains Netflow, DEX Trades, and Holdings support these chains: | Chain | Value | | --------- | ----------- | | Arbitrum | `arbitrum` | | Arc | `arc` | | Avalanche | `avalanche` | | Base | `base` | | BNB Chain | `bnb` | | Ethereum | `ethereum` | | HyperEVM | `hyperevm` | | IOTA EVM | `iotaevm` | | Linea | `linea` | | Mantle | `mantle` | | Monad | `monad` | | Optimism | `optimism` | | Plasma | `plasma` | | Polygon | `polygon` | | Robinhood | `robinhood` | | Sei | `sei` | | Solana | `solana` | | Sonic | `sonic` | Historical Holdings supports `arc`, `base`, `bnb`, `ethereum`, `monad`, `robinhood`, and `solana`. Perp Trades is Hyperliquid-only and does not accept a `chains` field. DCAs is Solana/Jupiter-only and does not accept a `chains` field. ### Smart Money Labels Filter by these smart money labels. Availability is endpoint-specific. `Fund` is deprecated for current Smart Money holdings: including it returns no rows, while excluding it has no effect, because Fund wallets are no longer part of the current Smart Money cohort. Historical snapshots from before September 9, 2026 can still contain Fund-labelled wallets; behavior on other current-data operations is endpoint-specific. | Label | Description | | ----------------------- | ------------------------------- | | `Fund` | Institutional investment funds | | `Smart Trader` | Historically profitable traders | | `30D Smart Trader` | Top performers (30-day window) | | `90D Smart Trader` | Top performers (90-day window) | | `180D Smart Trader` | Top performers (180-day window) | | `Smart HL Perps Trader` | Profitable Hyperliquid traders | ### Common Request Pattern ```json { "chains": ["ethereum", "solana"], "filters": { "include_smart_money_labels": ["Smart Trader"], "value_usd": {"min": 10000} }, "pagination": { "page": 1, "per_page": 100 }, "order_by": [ {"field": "value_usd", "direction": "DESC"} ] } ``` ### Next: {% content-ref url="/pages/aVsWbKbTgy8fbMcKoWq7" %} [Netflows](/api/smart-money/netflows) {% endcontent-ref %} {% content-ref url="/pages/1qo1HJEaDto58QBB7JoO" %} [Holdings](/api/smart-money/holdings) {% endcontent-ref %} {% content-ref url="/pages/rYsYbf9uGhNH2iFjvXis" %} [Historical Holdings](/api/smart-money/historical-holdings) {% endcontent-ref %} {% content-ref url="/pages/LA9mTsMicCD9eBuSA30f" %} [DEX Trades](/api/smart-money/dex-trades) {% endcontent-ref %} {% content-ref url="/pages/SykFfCZRUpWS1ASo0fzF" %} [Perp Trades](/api/smart-money/perp-trades) {% endcontent-ref %} {% content-ref url="/pages/ehDRbgk7yGFsGOVdRagI" %} [Jupiter DCAs](/api/smart-money/jupiter-dcas) {% endcontent-ref %} # Netflows Get aggregated token flow analysis for smart money wallets to see which tokens they're accumulating or distributing. Set `filters.include_native_tokens` to `true` to include native assets; the default is `false`. See [Native Tokens](/reference/native-tokens) for coverage limitations. ### Common Scenarios
UsecaseRequired ParametersOptional FiltersSorting LogicExpected Output
Find what funds are buying on Solanachains: ["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 sellingchains: ["ethereum"]token_sectors: ["DeFi"][{"field":"net_flow_7d_usd",
"direction":"ASC"}]		Returns tokens with highest net outflow in DeFi sector
### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * **Latency:** results are computed over rolling windows (1h, 24h, 7d, 30d) that always end at request time. The most recent 24 hours are served from live CEX and DEX activity, so recent flows show up within minutes; hours beyond that come from an hourly batch job and lag up to about an hour behind the chain. This endpoint takes no custom date range and applies no response cache. * **History:** coverage is a rolling **30 days** — the underlying flows table retains only the trailing 30 days. There is no older history and no backfill mode, so this endpoint is not suited to long-range historical analysis. ## Get Smart Money Netflow Data > Analyze net capital flows (inflows vs outflows) from smart traders and funds across different time periods. This endpoint helps identify which tokens are experiencing net accumulation or distribution by smart money.\ > \ > What are Net Flows?\ > Net flows represent the difference between smart money inflows and outflows for a token. This includes:\ > \ > \- DEX Trading Activity: Tokens bought vs sold on decentralized exchanges\ > \- CEX Transfers: Tokens sent to or received from centralized exchanges\ > \- Positive Net Flow: Smart money is accumulating (buying more than selling, or withdrawing from CEXs)\ > \- Negative Net Flow: Smart money is distributing (selling more than buying, or depositing to CEXs)\ > \ > Key Features:\ > \ > \- Aggregated net flow calculations across all smart money activity\ > \- Multiple time period analysis (1h, 24h, 7d, 30d)\ > \- Sortable results by volume metrics\ > \- Includes both DEX trades and CEX transfers ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"SmartMoneyNetflowRequest":{"properties":{"chains":{"items":{"$ref":"#/components/schemas/SmartMoneyChain"},"type":"array","title":"Chains","description":"Chains to include in the analysis (only smart money supported chains). Use 'all' to include all available chains."},"filters":{"anyOf":[{"$ref":"#/components/schemas/SmartMoneyNetflowFilters"}],"description":"Additional filters to apply. Only filters for columns that are being selected will be applied."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyNetflowSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"market_cap_usd\", \"direction\": \"DESC\"}] - Sort by market cap descending\n- [{\"field\": \"net_flow_24h_usd\", \"direction\": \"ASC\"}] - Sort by 24h flow ascending\n- [{\"field\": \"market_cap_usd\", \"direction\": \"DESC\"}, {\"field\": \"net_flow_24h_usd\", \"direction\": \"ASC\"}] - Sort by market cap descending, then 24h flow ascending"}},"additionalProperties":false,"type":"object","required":["chains"],"title":"SmartMoneyNetflowRequest","description":""},"SmartMoneyChain":{"type":"string","enum":["all","arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","iotaevm","linea","mantle","monad","optimism","plasma","polygon","robinhood","sei","solana","sonic"],"title":"SmartMoneyChain","description":"Chains supported in smart money analysis."},"SmartMoneyNetflowFilters":{"properties":{"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Smart money category filters"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Smart money category filters"},"token_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Address","description":"Token address or symbol filter"},"include_stablecoins":{"anyOf":[{"type":"boolean"}],"title":"Include Stablecoins","description":"Whether to include stablecoins in the results","default":false},"include_native_tokens":{"anyOf":[{"type":"boolean"}],"title":"Include Native Tokens","description":"Whether to include native tokens (e.g., ETH, SOL) in the results","default":false},"token_sector":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Token Sector","description":"Token sector filter"},"trader_count":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Trader count range filter"},"token_age_days":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token age range filter in days"},"market_cap_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Market cap range filter in USD"}},"additionalProperties":false,"type":"object","title":"SmartMoneyNetflowFilters","description":"Filters for smart money netflow endpoint.\n\nThese filters control which smart money categories, tokens, and data\nare included in the netflow analysis."},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Filter by smart money label type."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"SmartMoneyNetflowSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/SmartMoneyNetflowSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"SmartMoneyNetflowSortOrder"},"SmartMoneyNetflowSortField":{"type":"string","enum":["chain","token_address","token_symbol","net_flow_1h_usd","net_flow_24h_usd","net_flow_7d_usd","net_flow_30d_usd","token_sectors","trader_count","token_age_days","market_cap_usd"],"title":"SmartMoneyNetflowSortField","description":"Enum for sortable fields in smart money netflow."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"SmartMoneyNetflowResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SmartMoneyNetflow"},"type":"array","title":"Data","description":"List of smart money netflow records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"SmartMoneyNetflowResponse","description":"Response model for smart money netflow endpoint.\n\nContains the filtered smart money netflow data with metadata."},"SmartMoneyNetflow":{"properties":{"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"net_flow_1h_usd":{"type":"number","title":"Net Flow 1H Usd","description":"Net flow bought/sold of token by Smart Money in the past 1 hour."},"net_flow_24h_usd":{"type":"number","title":"Net Flow 24H Usd","description":"Net flow bought/sold of token by Smart Money in the past 24 hours."},"net_flow_7d_usd":{"type":"number","title":"Net Flow 7D Usd","description":"Net flow bought/sold of token by Smart Money in the past 7 days."},"net_flow_30d_usd":{"type":"number","title":"Net Flow 30D Usd","description":"Net flow bought/sold of token by Smart Money in the past 30 days."},"chain":{"type":"string","title":"Chain","description":"Blockchain chain"},"token_sectors":{"items":{"type":"string"},"type":"array","title":"Token Sectors","description":"Token sectors"},"trader_count":{"type":"integer","title":"Trader Count","description":"Number of Smart Money traders of token in the past 30 days."},"token_age_days":{"type":"integer","title":"Token Age Days","description":"Number of days since token was deployed."},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Market cap of token."}},"type":"object","required":["token_address","token_symbol","net_flow_1h_usd","net_flow_24h_usd","net_flow_7d_usd","net_flow_30d_usd","chain","token_sectors","trader_count","token_age_days"],"title":"SmartMoneyNetflow","description":"Individual smart money netflow record.\n\nRepresents a single token's smart money netflow data."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/smart-money/netflow":{"post":{"tags":["Smart Money"],"summary":"Get Smart Money Netflow Data","description":"Analyze net capital flows (inflows vs outflows) from smart traders and funds across different time periods. This endpoint helps identify which tokens are experiencing net accumulation or distribution by smart money.\n\nWhat are Net Flows?\nNet flows represent the difference between smart money inflows and outflows for a token. This includes:\n\n- DEX Trading Activity: Tokens bought vs sold on decentralized exchanges\n- CEX Transfers: Tokens sent to or received from centralized exchanges\n- Positive Net Flow: Smart money is accumulating (buying more than selling, or withdrawing from CEXs)\n- Negative Net Flow: Smart money is distributing (selling more than buying, or depositing to CEXs)\n\nKey Features:\n\n- Aggregated net flow calculations across all smart money activity\n- Multiple time period analysis (1h, 24h, 7d, 30d)\n- Sortable results by volume metrics\n- Includes both DEX trades and CEX transfers","operationId":"get_smart_money_netflow_api_v1_smart_money_netflow_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyNetflowRequest"}}},"required":true},"responses":{"200":{"description":"Smart money netflow data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyNetflowResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Holdings Aggregated token holdings data for smart money wallets. Set `filters.include_native_tokens` to `true` to include native assets; the default is `false`. See [Native Tokens](/reference/native-tokens) for coverage limitations. ### Common Scenarios
UsecaseRequired ParametersFiltersSorting LogicExpected Output
View smart trader token holdings across chainschains = ["ethereum", "solana"]N/Aorder_by = [{field: "value_usd",
direction: "DESC"}]		Aggregated list of tokens held by smart traders on specified chains
Monitor top accumulating tokens this weekchains = "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 valuechains = "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
### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Returns a **current, point-in-time snapshot** of aggregated holdings — there is no date-range parameter or historical look-back; balances and their 24-hour change reflect within the standard live latency. * On September 9, 2026, Fund wallets stopped being part of the upstream Smart Money cohort used by this endpoint. Current unfiltered totals can therefore be substantially lower than before that date. * `Fund` is still accepted temporarily for backward compatibility. Including it returns no rows; excluding it has no effect. Stop using it in either filter. We may begin rejecting it after December 22, 2026. ## Get Smart Money Holdings Data > Retrieve aggregated token balances held by smart traders and funds across multiple blockchains. This endpoint provides insights into what tokens are being accumulated by sophisticated market participants, excluding whales, large holders, and influencers to focus specifically on trading expertise.\ > \ > Key Features:\ > \ > \- Aggregated balances (not per-wallet breakdowns)\ > \- 24-hour balance change tracking updated in realtime\ > \- Sector categorization for tokens ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"SmartMoneyHoldingsRequest":{"properties":{"chains":{"items":{"$ref":"#/components/schemas/SmartMoneyChain"},"type":"array","title":"Chains","description":"Chains to include in the analysis (only smart money supported chains). Use 'all' to include all available chains."},"filters":{"anyOf":[{"$ref":"#/components/schemas/SmartMoneyHoldingsFilters"}],"description":"Additional filters to apply. Only filters for columns that are being selected will be applied."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyHoldingsSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"value_usd\", \"direction\": \"DESC\"}] - Sort by value USD descending\n- [{\"field\": \"holders_count\", \"direction\": \"ASC\"}] - Sort by number of holders ascending\n- [{\"field\": \"value_usd\", \"direction\": \"DESC\"}, {\"field\": \"holders_count\", \"direction\": \"ASC\"}] - Sort by value USD descending, then number of holders ascending"}},"additionalProperties":false,"type":"object","required":["chains"],"title":"SmartMoneyHoldingsRequest","description":""},"SmartMoneyChain":{"type":"string","enum":["all","arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","iotaevm","linea","mantle","monad","optimism","plasma","polygon","robinhood","sei","solana","sonic"],"title":"SmartMoneyChain","description":"Chains supported in smart money analysis."},"SmartMoneyHoldingsFilters":{"properties":{"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Smart money category filters. `Fund` is deprecated for this endpoint. Including `Fund` returns no rows because Fund wallets are no longer part of the current Smart Money cohort; use another current smart money label instead."},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Smart money category filters. `Fund` is deprecated for this endpoint. Excluding `Fund` has no effect because Fund wallets are no longer part of the current Smart Money cohort."},"include_stablecoins":{"anyOf":[{"type":"boolean"}],"title":"Include Stablecoins","description":"Whether to include stablecoins in the results","default":false},"include_native_tokens":{"anyOf":[{"type":"boolean"}],"title":"Include Native Tokens","description":"Whether to include native tokens (e.g., ETH, SOL) in the results","default":false},"value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Value range filter in USD"},"balance_24h_percent_change":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"24-hour balance change percentage range filter"},"holders_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of holders range filter"},"share_of_holdings_percent":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Share of holdings percentage range filter"},"token_age_days":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token age range filter in days"},"market_cap_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Market cap range filter in USD"},"token_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Address","description":"Token address filter"},"token_symbol":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Symbol","description":"Token symbol filter"},"token_sectors":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Token Sectors","description":"Token sectors filter"}},"additionalProperties":false,"type":"object","title":"SmartMoneyHoldingsFilters","description":"Filters for smart money holdings endpoint.\n\nThese filters control which token holdings, smart money categories,\nand data are included in the holdings analysis."},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Filter by smart money label type."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"SmartMoneyHoldingsSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/SmartMoneyHoldingsSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"SmartMoneyHoldingsSortOrder"},"SmartMoneyHoldingsSortField":{"type":"string","enum":["chain","token_address","token_symbol","value_usd","balance_24h_percent_change","holders_count","share_of_holdings_percent","token_age_days","market_cap_usd"],"title":"SmartMoneyHoldingsSortField","description":"Enum for sortable fields in smart money holdings."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"SmartMoneyHoldingsResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SmartMoneyHolding"},"type":"array","title":"Data","description":"List of smart money holding records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"SmartMoneyHoldingsResponse","description":"Response model for smart money holdings endpoint.\n\nContains the filtered smart money holdings data with metadata."},"SmartMoneyHolding":{"properties":{"chain":{"$ref":"#/components/schemas/SmartMoneyChain","description":"Chain name"},"token_address":{"type":"string","title":"Token Address","description":"Address of token"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"token_sectors":{"items":{"type":"string"},"type":"array","title":"Token Sectors","description":"Token sectors"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Value of token held by Smart Money."},"balance_24h_percent_change":{"anyOf":[{"type":"number"}],"title":"Balance 24H Percent Change","description":"Balance change of Smart Money for token during the last 24 hours"},"holders_count":{"type":"integer","title":"Holders Count","description":"Number of Smart Money holders of token."},"share_of_holdings_percent":{"anyOf":[{"type":"number"}],"title":"Share Of Holdings Percent","description":"Share of Smart Money total USD balance."},"token_age_days":{"type":"integer","title":"Token Age Days","description":"Number of days since token was deployed."},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Market cap of token."}},"type":"object","required":["chain","token_address","token_symbol","token_sectors","holders_count","token_age_days"],"title":"SmartMoneyHolding","description":"Individual smart money holding record.\n\nRepresents a single token's smart money holding data."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/smart-money/holdings":{"post":{"tags":["Smart Money"],"summary":"Get Smart Money Holdings Data","description":"Retrieve aggregated token balances held by smart traders and funds across multiple blockchains. This endpoint provides insights into what tokens are being accumulated by sophisticated market participants, excluding whales, large holders, and influencers to focus specifically on trading expertise.\n\nKey Features:\n\n- Aggregated balances (not per-wallet breakdowns)\n- 24-hour balance change tracking updated in realtime\n- Sector categorization for tokens","operationId":"get_smart_money_holdings_api_v1_smart_money_holdings_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyHoldingsRequest"}}},"required":true},"responses":{"200":{"description":"Smart money holdings data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyHoldingsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Historical Holdings Set `filters.include_native_tokens` to `true` to include native assets; the default is `false`. See [Native Tokens](/reference/native-tokens) for coverage limitations. {% hint style="info" %} **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. {% endhint %} ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Data is provided as **daily snapshots**, so a given day's holdings become available once per day rather than updating continuously. * History is limited to a rolling **\~4-year window** (roughly the last four years up to today) — shorter than the full chain-level history on older chains. * **Today's row is live, not settled:** for `block_date = today()`, market cap is computed from a live price/FDV lookup rather than the frozen daily snapshot, and the underlying balance figures are still accumulating for the partial day — so today's row can change on repeated calls. Any day before today is immutable once written. * Results are server-cached keyed on the requested range: **5 minutes** if the range includes today or ends within the last 2 days, **7 days** once the range is fully settled. * For point-in-time Smart Money snapshots keyed by `as_of_date`, use [Historical Smart Money Positions](/api/backtesting-data/historical-smart-money-positions); that endpoint excludes the current day until its daily snapshot is produced. ## Get Smart Money Historical Holdings Data > 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 (max 4 years 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 ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"SmartMoneyHistoricalHoldingsRequest":{"properties":{"date_range":{"$ref":"#/components/schemas/DateOnlyRange","description":"Date range for historical data (YYYY-MM-DD format). If 'to' is omitted, defaults to today. Maximum lookback is 4 years."},"chains":{"items":{"$ref":"#/components/schemas/SmartMoneyHistoricalHoldingsChain"},"type":"array","title":"Chains","description":"Chains to include in the analysis. Supports ethereum, base, bnb, monad, robinhood, arc, and solana."},"filters":{"anyOf":[{"$ref":"#/components/schemas/SmartMoneyHistoricalHoldingsFilters"}],"description":"Additional filters to apply"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyHistoricalHoldingsSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order. Defaults to sorting by date DESC, value_usd DESC, token_address ASC, chain ASC for stable pagination."}},"additionalProperties":false,"type":"object","required":["date_range","chains"],"title":"SmartMoneyHistoricalHoldingsRequest","description":"Request model for smart money historical holdings endpoint."},"DateOnlyRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in YYYY-MM-DD format"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in YYYY-MM-DD format"}},"type":"object","title":"DateOnlyRange","description":"Date range model that only accepts YYYY-MM-DD format (no time components)."},"SmartMoneyHistoricalHoldingsChain":{"type":"string","enum":["arc","base","bnb","ethereum","monad","robinhood","solana"],"title":"SmartMoneyHistoricalHoldingsChain","description":"Chains supported for smart money historical holdings endpoint."},"SmartMoneyHistoricalHoldingsFilters":{"properties":{"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/HistoricalSmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Smart money category filters"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/HistoricalSmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Smart money category filters"},"include_stablecoins":{"anyOf":[{"type":"boolean"}],"title":"Include Stablecoins","description":"Whether to include stablecoins in the results","default":false},"include_native_tokens":{"anyOf":[{"type":"boolean"}],"title":"Include Native Tokens","description":"Whether to include native tokens (e.g., ETH, SOL) in the results","default":false},"balance":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token balance range filter in human-readable units"},"value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Value range filter in USD"},"balance_24h_percent_change":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"24-hour balance change percentage range filter"},"holders_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of holders range filter"},"share_of_holdings_percent":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Share of holdings percentage range filter"},"token_age_days":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token age range filter in days"},"market_cap_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Market cap range filter in USD"},"token_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Address","description":"Token address filter"},"token_symbol":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Symbol","description":"Token symbol filter"}},"additionalProperties":false,"type":"object","title":"SmartMoneyHistoricalHoldingsFilters","description":"Filters for smart money historical holdings endpoint."},"HistoricalSmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart Dex Trader","30D Smart Dex Trader","90D Smart Dex Trader","180D Smart Dex Trader","Smart HL Perps Trader"],"title":"HistoricalSmartMoneyFilterType","description":"Filter by smart money label type. Includes legacy label classes (e.g. Smart Dex Trader) that appear in historical data."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"SmartMoneyHistoricalHoldingsSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/SmartMoneyHistoricalHoldingsSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"SmartMoneyHistoricalHoldingsSortOrder"},"SmartMoneyHistoricalHoldingsSortField":{"type":"string","enum":["date","chain","token_address","token_symbol","balance","value_usd","balance_24h_percent_change","holders_count","share_of_holdings_percent","token_age_days","market_cap_usd"],"title":"SmartMoneyHistoricalHoldingsSortField","description":"Enum for sortable fields in smart money historical holdings."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"SmartMoneyHistoricalHoldingsResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SmartMoneyHistoricalHolding"},"type":"array","title":"Data","description":"List of smart money historical holding records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"SmartMoneyHistoricalHoldingsResponse","description":"Response model for smart money historical holdings endpoint."},"SmartMoneyHistoricalHolding":{"properties":{"date":{"type":"string","title":"Date","description":"Snapshot date (YYYY-MM-DD)"},"chain":{"$ref":"#/components/schemas/SmartMoneyHistoricalHoldingsChain","description":"Chain name"},"token_address":{"type":"string","title":"Token Address","description":"Address of token"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"token_sectors":{"items":{"type":"string"},"type":"array","title":"Token Sectors","description":"Token sectors"},"smart_money_labels":{"items":{"type":"string"},"type":"array","title":"Smart Money Labels","description":"Array of unique smart money labels present in the aggregated holdings for this token"},"balance":{"anyOf":[{"type":"number"}],"title":"Balance","description":"Token balance in human-readable units (accounting for decimals)"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Value of token held by Smart Money at snapshot date"},"balance_24h_percent_change":{"anyOf":[{"type":"number"}],"title":"Balance 24H Percent Change","description":"Balance change of Smart Money for token during the 24 hours prior to snapshot"},"holders_count":{"type":"integer","title":"Holders Count","description":"Number of Smart Money holders of token at snapshot date"},"share_of_holdings_percent":{"anyOf":[{"type":"number"}],"title":"Share Of Holdings Percent","description":"Share of Smart Money total USD balance at snapshot date"},"token_age_days":{"type":"integer","title":"Token Age Days","description":"Number of days since token was deployed, relative to snapshot date"},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Market cap of token at snapshot date"}},"type":"object","required":["date","chain","token_address","token_symbol","token_sectors","smart_money_labels","holders_count","token_age_days"],"title":"SmartMoneyHistoricalHolding","description":"Individual smart money historical holding record."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/smart-money/historical-holdings":{"post":{"tags":["Smart Money"],"summary":"Get Smart Money Historical Holdings Data","description":"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.\n\nKey Features:\n\n- Daily snapshots of smart money holdings\n- Date range filtering (max 4 years lookback)\n- Point-in-time pricing and market cap data\n- Balance change tracking between snapshots\n- Same filtering options as current holdings endpoint\n\nUse Cases:\n\n- Trend Analysis: Track how smart money rotates between assets over time\n- Performance Attribution: Combine with price data to estimate ROI\n- Backtesting: Validate trading strategies based on historical smart money behavior","operationId":"get_smart_money_historical_holdings_api_v1_smart_money_historical_holdings_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyHistoricalHoldingsRequest"}}},"required":true},"responses":{"200":{"description":"Smart money historical holdings data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyHistoricalHoldingsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # DEX Trades ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Only the **trailing 24 hours** of DEX trades is queryable — far shorter than the chain-level history — and there is no date-range parameter. ## Get Smart Money DEX Trades Data > Access real-time DEX trading activity from smart traders and funds over the last 24 hours. This endpoint provides granular transaction-level data showing exactly what sophisticated traders are buying and selling on decentralized exchanges. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"SmartMoneyDexTradesRequest":{"properties":{"chains":{"items":{"$ref":"#/components/schemas/SmartMoneyChain"},"type":"array","title":"Chains","description":"Chains to include in the analysis (only smart money supported chains). Use 'all' to include all available chains."},"filters":{"anyOf":[{"$ref":"#/components/schemas/SmartMoneyDexTradesFilters"}],"description":"Additional filters to apply. Only filters for columns that are being selected will be applied."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyDexTradesSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"trade_value_in_usd\", \"direction\": \"DESC\"}] - Sort by trade value descending\n- [{\"field\": \"block_timestamp\", \"direction\": \"ASC\"}] - Sort by timestamp ascending\n- [{\"field\": \"token_bought_amount\", \"direction\": \"DESC\"}, {\"field\": \"block_timestamp\", \"direction\": \"ASC\"}] - Sort by bought amount descending, then timestamp ascending"}},"additionalProperties":false,"type":"object","required":["chains"],"title":"SmartMoneyDexTradesRequest","description":""},"SmartMoneyChain":{"type":"string","enum":["all","arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","iotaevm","linea","mantle","monad","optimism","plasma","polygon","robinhood","sei","solana","sonic"],"title":"SmartMoneyChain","description":"Chains supported in smart money analysis."},"SmartMoneyDexTradesFilters":{"properties":{"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Smart money category filters"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Smart money category filters"},"chain":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Chain","description":"Blockchain network filter"},"transaction_hash":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Transaction Hash","description":"Transaction hash filter"},"trader_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address","description":"Trader address filter"},"trader_address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address Label","description":"Trader name or label filter"},"token_bought_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Bought Address","description":"Token address filter for bought tokens"},"token_sold_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Sold Address","description":"Token address filter for sold tokens"},"token_bought_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Amount range filter for bought tokens"},"token_sold_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Amount range filter for sold tokens"},"token_bought_symbol":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Bought Symbol","description":"Symbol filter for bought tokens"},"token_sold_symbol":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Sold Symbol","description":"Symbol filter for sold tokens"},"token_bought_age_days":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Age range filter for bought tokens in days"},"token_sold_age_days":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Age range filter for sold tokens in days"},"token_bought_market_cap":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Market cap range filter for bought tokens"},"token_sold_market_cap":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Market cap range filter for sold tokens"},"token_bought_fdv":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"FDV range filter for bought tokens"},"token_sold_fdv":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"FDV range filter for sold tokens"},"trade_value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Trade value range filter in USD"}},"additionalProperties":false,"type":"object","title":"SmartMoneyDexTradesFilters","description":"Filters for smart money DEX trades endpoint.\n\nThese filters control which DEX trades, tokens, and traders\nare included in the trades analysis."},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Filter by smart money label type."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"SmartMoneyDexTradesSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/SmartMoneyDexTradesSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"SmartMoneyDexTradesSortOrder"},"SmartMoneyDexTradesSortField":{"type":"string","enum":["chain","block_timestamp","transaction_hash","trader_address","trader_address_label","token_bought_address","token_sold_address","token_bought_amount","token_sold_amount","token_bought_symbol","token_sold_symbol","token_bought_age_days","token_sold_age_days","token_bought_market_cap","token_sold_market_cap","token_bought_fdv","token_sold_fdv","trade_value_usd"],"title":"SmartMoneyDexTradesSortField","description":"Enum for sortable fields in smart money dex trades."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"SmartMoneyDexTradesResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SmartMoneyDexTrade"},"type":"array","title":"Data","description":"List of smart money dex trade records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"SmartMoneyDexTradesResponse","description":"Response model for smart money dex trades endpoint.\n\nContains the filtered smart money dex trades data with metadata."},"SmartMoneyDexTrade":{"properties":{"chain":{"type":"string","title":"Chain","description":"Blockchain chain"},"block_timestamp":{"type":"string","title":"Block Timestamp","description":"Block timestamp of the trade"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Transaction hash"},"trader_address":{"type":"string","title":"Trader Address","description":"Hexadecimal representation of the trader's address, i.e. the signer of the transaction"},"trader_address_label":{"type":"string","title":"Trader Address Label","description":"Name of the trader, based on nansen_label"},"token_bought_address":{"type":"string","title":"Token Bought Address","description":"Hexadecimal representation of the bought token's address"},"token_sold_address":{"type":"string","title":"Token Sold Address","description":"Hexadecimal representation of the sold token's address"},"token_bought_amount":{"anyOf":[{"type":"number"}],"title":"Token Bought Amount","description":"Amount of token bought in decimal amount"},"token_sold_amount":{"anyOf":[{"type":"number"}],"title":"Token Sold Amount","description":"Amount of token sold in decimal amount"},"token_bought_symbol":{"type":"string","title":"Token Bought Symbol","description":"Symbol of the bought token"},"token_sold_symbol":{"type":"string","title":"Token Sold Symbol","description":"Symbol of the sold token"},"token_bought_age_days":{"type":"integer","title":"Token Bought Age Days","description":"Age of bought token's address in days"},"token_sold_age_days":{"type":"integer","title":"Token Sold Age Days","description":"Age of sold token's address in days"},"token_bought_market_cap":{"anyOf":[{"type":"number"}],"title":"Token Bought Market Cap","description":"Circulating market cap of bought token in USD. Returns NULL when circulating supply data is unavailable."},"token_sold_market_cap":{"anyOf":[{"type":"number"}],"title":"Token Sold Market Cap","description":"Circulating market cap of sold token in USD. Returns NULL when circulating supply data is unavailable."},"token_bought_fdv":{"anyOf":[{"type":"number"}],"title":"Token Bought Fdv","description":"Fully Diluted Valuation of bought token in USD (total_supply x price). May be very large for tokens with no circulating supply data."},"token_sold_fdv":{"anyOf":[{"type":"number"}],"title":"Token Sold Fdv","description":"Fully Diluted Valuation of sold token in USD (total_supply x price). May be very large for tokens with no circulating supply data."},"trade_value_usd":{"anyOf":[{"type":"number"}],"title":"Trade Value Usd","description":"Either token_bought_in_usd or token_sold_in_usd, if token_bought_in_usd is 0"}},"type":"object","required":["chain","block_timestamp","transaction_hash","trader_address","trader_address_label","token_bought_address","token_sold_address","token_bought_symbol","token_sold_symbol","token_bought_age_days","token_sold_age_days"],"title":"SmartMoneyDexTrade","description":"Individual smart money dex trade record.\n\nRepresents a single DEX trade made by smart money wallets."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/smart-money/dex-trades":{"post":{"tags":["Smart Money"],"summary":"Get Smart Money DEX Trades Data","description":"Access real-time DEX trading activity from smart traders and funds over the last 24 hours. This endpoint provides granular transaction-level data showing exactly what sophisticated traders are buying and selling on decentralized exchanges.","operationId":"get_smart_money_dex_trades_api_v1_smart_money_dex_trades_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyDexTradesRequest"}}},"required":true},"responses":{"200":{"description":"Smart money DEX trades data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyDexTradesResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Perp Trades ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Only the **trailing 7 days** of Hyperliquid perpetuals activity is queryable — far shorter than the available history — and there is no date-range parameter. ## Get Smart Money Perpetual Trades Data > Access real-time perpetual trading activity from smart traders and funds on Hyperliquid. This endpoint provides granular transaction-level data showing exactly what sophisticated traders are trading on perpetual contracts.\ > \ > Key Features:\ > \- Hyperliquid perpetual contracts only (no chain field needed)\ > \- Real-time trading data from smart money wallets\ > \- Detailed trade information including coin, amount, price, action, and type\ > \- Smart money filtering capabilities\ > \- Type filtering (Market/Limit)\ > \- Only new positions filter to show only position opening trades (defaults to false - shows all trades) ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"SmartMoneyPerpTradesRequest":{"properties":{"filters":{"anyOf":[{"$ref":"#/components/schemas/SmartMoneyPerpTradesFilters"}],"description":"Additional filters to apply. Only filters for columns that are being selected will be applied."},"lookback_hours":{"type":"integer","maximum":168,"minimum":1,"title":"Lookback Hours","description":"Length of the recent trade window in hours. Defaults to 168 hours to preserve the endpoint's existing seven-day behavior.","default":168},"only_new_positions":{"anyOf":[{"type":"boolean"}],"title":"Only New Positions","description":"When True, includes 'Open' position actions (Open Long, Open Short). Can be combined with other action filters using OR logic (union). When False (default), returns all trades.","default":false},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyPerpTradesSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"value_usd\", \"direction\": \"DESC\"}] - Sort by trade value descending\n- [{\"field\": \"block_timestamp\", \"direction\": \"ASC\"}] - Sort by timestamp ascending\n- [{\"field\": \"token_amount\", \"direction\": \"DESC\"}, {\"field\": \"block_timestamp\", \"direction\": \"ASC\"}] - Sort by token amount descending, then timestamp ascending"}},"additionalProperties":false,"type":"object","title":"SmartMoneyPerpTradesRequest","description":""},"SmartMoneyPerpTradesFilters":{"properties":{"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Narrow the fixed Smart HL Perps Trader cohort to traders that also carry any selected label. Empty or omitted keeps the full cohort."},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Remove members of the fixed Smart HL Perps Trader cohort that carry any selected label. Empty or omitted removes no traders."},"trader_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address","description":"Trader address filter"},"trader_address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address Label","description":"Trader name or label filter"},"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","description":"Token symbol filter"},"type":{"anyOf":[{"$ref":"#/components/schemas/TradeType"}],"description":"Trade type filter - Market or Limit"},"token_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token amount range filter"},"price_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Price range filter in USD"},"value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Trade value range filter in USD"},"side":{"anyOf":[{"$ref":"#/components/schemas/PositionSide"},{"items":{"$ref":"#/components/schemas/PositionSide"},"type":"array"},{"type":"null"}],"title":"Side","description":"Position side filter - Long or Short"},"action":{"anyOf":[{"$ref":"#/components/schemas/PerpActionType"},{"items":{"$ref":"#/components/schemas/PerpActionType"},"type":"array"},{"type":"null"}],"title":"Action","description":"Action filter - combined buy/sell with position action (e.g., 'Buy - Add Long', 'Sell - Open Short')"}},"additionalProperties":false,"type":"object","title":"SmartMoneyPerpTradesFilters","description":"Filters for smart money perpetual trades endpoint.\n\nThese filters control which perpetual trades and traders\nare included in the trades analysis."},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Filter by smart money label type."},"TradeType":{"type":"string","enum":["Market","Limit"],"title":"TradeType","description":"Enum for trade types."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"PositionSide":{"type":"string","enum":["Long","Short"],"title":"PositionSide","description":"Shared enum for position side direction."},"PerpActionType":{"type":"string","enum":["Buy - Add Long","Buy - Reduce Short","Buy - Open Long","Buy - Close Short","Sell - Add Short","Sell - Reduce Long","Sell - Open Short","Sell - Close Long"],"title":"PerpActionType","description":"Shared enum for perpetual trade action types (combined buy/sell with position actions)."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"SmartMoneyPerpTradesSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/SmartMoneyPerpTradesSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"SmartMoneyPerpTradesSortOrder"},"SmartMoneyPerpTradesSortField":{"type":"string","enum":["block_timestamp","token_amount","price_usd","value_usd"],"title":"SmartMoneyPerpTradesSortField","description":"Enum for sortable fields in smart money perp trades."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"SmartMoneyPerpTradesResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SmartMoneyPerpTrade"},"type":"array","title":"Data","description":"List of smart money perpetual trade records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"SmartMoneyPerpTradesResponse","description":"Response model for smart money perpetual trades endpoint.\n\nContains the filtered smart money perpetual trades data with metadata."},"SmartMoneyPerpTrade":{"properties":{"trader_address_label":{"type":"string","title":"Trader Address Label","description":"Name of the trader, based on Nansen labels"},"trader_address":{"type":"string","title":"Trader Address","description":"Hexadecimal representation of the trader's address, i.e. the signer of the transaction"},"token_symbol":{"type":"string","title":"Token Symbol","description":"The token symbol"},"side":{"anyOf":[{"$ref":"#/components/schemas/PositionSide"}],"description":"The side of the position (Long or Short)"},"action":{"type":"string","title":"Action","description":"The action taken by the trader (Add, Reduce, Open, Close)"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"Trade size in contract units"},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Trade price in USD"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Notional trade value in USD"},"type":{"$ref":"#/components/schemas/TradeType","description":"The trade type (Market or Limit)"},"block_timestamp":{"type":"string","title":"Block Timestamp","description":"The timestamp of the block"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Hexadecimal representation of the transaction hash"}},"type":"object","required":["trader_address_label","trader_address","token_symbol","action","type","block_timestamp","transaction_hash"],"title":"SmartMoneyPerpTrade","description":"Individual smart money perpetual trade record.\n\nRepresents a single perpetual trade made by smart money wallets on Hyperliquid."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/smart-money/perp-trades":{"post":{"tags":["Smart Money"],"summary":"Get Smart Money Perpetual Trades Data","description":"Access real-time perpetual trading activity from smart traders and funds on Hyperliquid. This endpoint provides granular transaction-level data showing exactly what sophisticated traders are trading on perpetual contracts.\n\nKey Features:\n- Hyperliquid perpetual contracts only (no chain field needed)\n- Real-time trading data from smart money wallets\n- Detailed trade information including coin, amount, price, action, and type\n- Smart money filtering capabilities\n- Type filtering (Market/Limit)\n- Only new positions filter to show only position opening trades (defaults to false - shows all trades)","operationId":"get_smart_money_perp_trades_api_v1_smart_money_perp_trades_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyPerpTradesRequest"}}},"required":true},"responses":{"200":{"description":"Smart money perpetual trades data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyPerpTradesResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Jupiter DCAs ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Only the **trailing 7 days** of DCA activity is queryable — shorter than the chain-level history — and there is no date-range parameter. ## Get Smart Money DCAs Data > Monitor DCA strategies employed by smart money on Solana through Jupiter DCA. This endpoint reveals systematic accumulation strategies used by smart money. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"SmartMoneyDcasRequest":{"properties":{"filters":{"anyOf":[{"$ref":"#/components/schemas/SmartMoneyDcasFilters"}],"description":"Additional filters to apply. Only filters for columns that are being selected will be applied."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyDcasSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"dca_created_at\", \"direction\": \"DESC\"}] - Sort by DCA created timestamp descending\n- [{\"field\": \"dca_updated_at\", \"direction\": \"ASC\"}] - Sort by DCA updated timestamp ascending\n- [{\"field\": \"deposit_token_amount\", \"direction\": \"DESC\"}, {\"field\": \"token_spent_amount\", \"direction\": \"ASC\"}] - Sort by deposit token amount descending, then token spent amount ascending"}},"additionalProperties":false,"type":"object","title":"SmartMoneyDcasRequest","description":""},"SmartMoneyDcasFilters":{"properties":{"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Smart money category filters"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Smart money category filters"},"dca_created_at":{"anyOf":[{"$ref":"#/components/schemas/DateRangeFilter"}],"description":"Date range filter for DCA creation timestamps"},"transaction_hash":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Transaction Hash","description":"Transaction hash filter"},"trader_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address","description":"Trader address filter"},"trader_address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address Label","description":"Trader name or label filter"},"input_token_symbol":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Input Token Symbol","description":"Symbol filter for input tokens"},"output_token_symbol":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Output Token Symbol","description":"Symbol filter for output tokens"},"deposit_token_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Deposit amount range filter"},"token_spent_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token spent amount range filter"},"output_token_redeemed_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Output token redeemed amount range filter"}},"additionalProperties":false,"type":"object","title":"SmartMoneyDcasFilters","description":"Filters for smart money DCAs endpoint.\n\nThese filters control which DCA orders, tokens, and traders\nare included in the DCA analysis."},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Filter by smart money label type."},"DateRangeFilter":{"properties":{"from":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"From","description":"Start date (inclusive), ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"To","description":"End date (inclusive), ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRangeFilter","description":"Filter for date ranges with optional from/to bounds. - Date range"},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"SmartMoneyDcasSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/SmartMoneyDcasSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"SmartMoneyDcasSortOrder"},"SmartMoneyDcasSortField":{"type":"string","enum":["dca_created_at","dca_updated_at","input_token_symbol","output_token_symbol","deposit_token_amount","token_spent_amount","deposit_value_usd","output_token_redeemed_amount"],"title":"SmartMoneyDcasSortField","description":"Enum for sortable fields in smart money DCAs."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"SmartMoneyDcasResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SmartMoneyDca"},"type":"array","title":"Data","description":"List of smart money DCA records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"SmartMoneyDcasResponse","description":"Response model for smart money DCAs endpoint.\n\nContains the filtered smart money DCAs data with metadata."},"SmartMoneyDca":{"properties":{"dca_created_at":{"type":"string","title":"Dca Created At","description":"The timestamp of the earliest transaction"},"dca_updated_at":{"type":"string","title":"Dca Updated At","description":"The timestamp of the latest transaction"},"trader_address":{"type":"string","title":"Trader Address","description":"The address of the trader"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"The transaction hash at the time of creation"},"trader_address_label":{"type":"string","title":"Trader Address Label","description":"Label associated with the address"},"dca_vault_address":{"type":"string","title":"Dca Vault Address","description":"The address of the DCA vault"},"input_token_address":{"type":"string","title":"Input Token Address","description":"Address of token"},"output_token_address":{"type":"string","title":"Output Token Address","description":"Address of token"},"deposit_token_amount":{"anyOf":[{"type":"number"}],"title":"Deposit Token Amount","description":"The amount deposited into the DCA vault"},"token_spent_amount":{"anyOf":[{"type":"number"}],"title":"Token Spent Amount","description":"The amount spent from the deposit"},"output_token_redeemed_amount":{"anyOf":[{"type":"number"}],"title":"Output Token Redeemed Amount","description":"The amount of other tokens redeemed"},"dca_status":{"type":"string","title":"Dca Status","description":"Indicates if the account was closed or active"},"input_token_symbol":{"type":"string","title":"Input Token Symbol","description":"The symbol of the input token"},"output_token_symbol":{"type":"string","title":"Output Token Symbol","description":"The symbol of the output token"},"deposit_value_usd":{"anyOf":[{"type":"number"}],"title":"Deposit Value Usd","description":"The USD value of the deposit"}},"type":"object","required":["dca_created_at","dca_updated_at","trader_address","transaction_hash","trader_address_label","dca_vault_address","input_token_address","output_token_address","dca_status","input_token_symbol","output_token_symbol"],"title":"SmartMoneyDca","description":"Individual smart money DCA record.\n\nRepresents a single DCA (Dollar Cost Averaging) order made by smart money wallets."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/smart-money/dcas":{"post":{"tags":["Smart Money"],"summary":"Get Smart Money DCAs Data","description":"Monitor DCA strategies employed by smart money on Solana through Jupiter DCA. This endpoint reveals systematic accumulation strategies used by smart money.","operationId":"get_smart_money_dcas_api_v1_smart_money_dcas_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyDcasRequest"}}},"required":true},"responses":{"200":{"description":"Smart money DCAs data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyDcasResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # PnL Leaderboard Ranked leaderboard of Smart Money wallets by PnL over a selected timeframe. ## Get Smart Money PnL Leaderboard > Retrieve a ranked leaderboard of smart money wallets by profit and loss (PnL) over a selected timeframe.\ > \ > Each entry includes realized and unrealized PnL, win rate, trade counts, and top token positions. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"SmartMoneyPnlLeaderboardRequest":{"properties":{"chains":{"items":{"$ref":"#/components/schemas/SmartMoneyChain"},"type":"array","title":"Chains","description":"Chains to include in the analysis. Use 'all' to include all available chains."},"timeframe":{"$ref":"#/components/schemas/SmartMoneyPnlLeaderboardTimeframe","description":"Timeframe in days. Allowed values: 1, 7, 30, 90, 180.","default":7},"filters":{"anyOf":[{"$ref":"#/components/schemas/SmartMoneyPnlLeaderboardFilters"}],"description":"Additional filters to apply."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyPnlLeaderboardSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order. Defaults to total_pnl_usd DESC."}},"additionalProperties":false,"type":"object","required":["chains"],"title":"SmartMoneyPnlLeaderboardRequest","description":"Request model for the Smart Money PnL leaderboard endpoint."},"SmartMoneyChain":{"type":"string","enum":["all","arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","iotaevm","linea","mantle","monad","optimism","plasma","polygon","robinhood","sei","solana","sonic"],"title":"SmartMoneyChain","description":"Chains supported in smart money analysis."},"SmartMoneyPnlLeaderboardTimeframe":{"type":"integer","enum":[1,7,30,90,180],"title":"SmartMoneyPnlLeaderboardTimeframe","description":"Allowed timeframe values in days for the PnL leaderboard."},"SmartMoneyPnlLeaderboardFilters":{"properties":{"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Smart money category filters to include"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Smart money category filters to exclude"}},"type":"object","title":"SmartMoneyPnlLeaderboardFilters","description":"Filters for smart money PnL leaderboard endpoint."},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Filter by smart money label type."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"SmartMoneyPnlLeaderboardSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/SmartMoneyPnlLeaderboardSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"SmartMoneyPnlLeaderboardSortOrder"},"SmartMoneyPnlLeaderboardSortField":{"type":"string","enum":["address","realized_pnl_usd","unrealized_pnl_usd","total_pnl_usd","avg_trade_roi","roi_percent_unrealised","win_rate","n_trades","n_tokens","open_trades","held_tokens_count"],"title":"SmartMoneyPnlLeaderboardSortField","description":"Enum for sortable fields in smart money PnL leaderboard."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"SmartMoneyPnlLeaderboardResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SmartMoneyPnlLeaderboard"},"type":"array","title":"Data","description":"List of smart money PnL leaderboard records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"SmartMoneyPnlLeaderboardResponse","description":"Response model for smart money PnL leaderboard endpoint."},"SmartMoneyPnlLeaderboard":{"properties":{"address":{"type":"string","title":"Address","description":"Wallet address"},"address_label":{"anyOf":[{"type":"string"}],"title":"Address Label","description":"Wallet label from Nansen"},"realized_pnl_usd":{"type":"number","title":"Realized Pnl Usd","description":"Realized PnL in USD"},"unrealized_pnl_usd":{"type":"number","title":"Unrealized Pnl Usd","description":"Unrealized PnL in USD"},"total_pnl_usd":{"type":"number","title":"Total Pnl Usd","description":"Total PnL in USD (realized + unrealized)"},"avg_trade_roi":{"anyOf":[{"type":"number"}],"title":"Avg Trade Roi","description":"Average trade ROI as a fraction"},"roi_percent_unrealised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Unrealised","description":"Unrealized ROI percentage"},"win_rate":{"anyOf":[{"type":"number"}],"title":"Win Rate","description":"Win rate as a fraction (0-1)"},"n_trades":{"type":"integer","title":"N Trades","description":"Number of trades"},"n_tokens":{"type":"integer","title":"N Tokens","description":"Number of tokens traded"},"open_trades":{"type":"integer","title":"Open Trades","description":"Number of currently open trades"},"held_tokens_count":{"type":"integer","title":"Held Tokens Count","description":"Number of tokens currently held"},"top_traded_tokens_info":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Top Traded Tokens Info","description":"Top traded tokens information"},"top_5_balance_tokens_info":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Top 5 Balance Tokens Info","description":"Top 5 tokens by balance"}},"type":"object","required":["address","realized_pnl_usd","unrealized_pnl_usd","total_pnl_usd","n_trades","n_tokens","open_trades","held_tokens_count"],"title":"SmartMoneyPnlLeaderboard","description":"Individual smart money PnL leaderboard record."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/smart-money/pnl-leaderboard":{"post":{"tags":["Smart Money"],"summary":"Get Smart Money PnL Leaderboard","description":"Retrieve a ranked leaderboard of smart money wallets by profit and loss (PnL) over a selected timeframe.\n\nEach entry includes realized and unrealized PnL, win rate, trade counts, and top token positions.","operationId":"get_smart_money_pnl_leaderboard_api_v1_smart_money_pnl_leaderboard_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyPnlLeaderboardRequest"}}},"required":true},"responses":{"200":{"description":"Smart money PnL leaderboard data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyPnlLeaderboardResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Profiler # Address Current Balances Get real-time token balance information for any blockchain address or entity ### Common Scenarios {% hint style="info" %} You can use this endpoint to find correct entity name format to use in this Profiler Endpoint: [**Click Here**](https://docs.nansen.ai/api/profiler/entity-name-search) {% endhint %}
UsecaseRequired ParametersOptional FiltersExpected Output
Check current holdings for a single addressaddress = "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 = trueAggregated balances for entity across all wallets, showing holdings per chain
### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Returns a **current, point-in-time snapshot** of holdings — there is no date-range parameter or historical look-back; balances update continuously off on-chain activity and reflect within the standard live latency. ## Get Address Current Balance Data > Retrieve current token holdings for addresses or entities. Returns detailed balance information across specified chains.\ > \ > What it helps to answer:\ > \ > \- Current token holdings with quantities and USD valuations\ > \- Asset distribution across different blockchain networks\ > \- Native token versus token balances\ > \- Stablecoin holdings and percentages\ > \- Cross-chain portfolio composition\ > \ > Note: The address field in the response will be empty if entity\_name is provided. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"ProfilerAddressBalancesRequest":{"properties":{"address":{"anyOf":[{"type":"string"}],"title":"Address","description":"Address to get balances for"},"entity_name":{"anyOf":[{"type":"string"}],"title":"Entity Name","description":"Entity name to get balances for"},"chain":{"$ref":"#/components/schemas/ProfilerChain","description":"Blockchain chain for the balances"},"hide_spam_token":{"type":"boolean","title":"Hide Spam Token","description":"Removes suspicious tokens from the balance list","default":true},"filters":{"anyOf":[{"$ref":"#/components/schemas/ProfilerAddressBalancesFilters"}],"description":"Additional filters to apply. Only filters for columns that are being selected will be applied."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProfilerAddressBalancesSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering"}},"additionalProperties":false,"type":"object","required":["chain"],"title":"ProfilerAddressBalancesRequest","description":""},"ProfilerChain":{"type":"string","enum":["all","arbitrum","arc","avalanche","base","bitcoin","bnb","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"ProfilerChain","description":"Chains supported in profiler analysis."},"ProfilerAddressBalancesFilters":{"properties":{"value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Balance range filter in USD"},"price_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token price range filter in USD"},"token_amount":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Token amount range filter"},"token_symbol":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Symbol","description":"Token symbol filter"},"token_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Address","description":"Token address filter"},"token_name":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Name","description":"Token name filter"}},"additionalProperties":false,"type":"object","title":"ProfilerAddressBalancesFilters","description":"Filters for profiler address current balance endpoint.\n\nThese filters control which token balances are included."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"ProfilerAddressBalancesSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/ProfilerAddressBalancesSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"ProfilerAddressBalancesSortOrder"},"ProfilerAddressBalancesSortField":{"type":"string","enum":["value_usd","token_symbol"],"title":"ProfilerAddressBalancesSortField","description":"Enum for sortable fields in profiler address balances."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"ProfilerAddressBalancesResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/ProfilerBalance"},"type":"array","title":"Data","description":"List of balance records"}},"type":"object","required":["pagination","data"],"title":"ProfilerAddressBalancesResponse","description":"Response model for profiler address current-balance endpoint.\n\nContains the filtered balance data with metadata."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ProfilerBalance":{"properties":{"chain":{"type":"string","title":"Chain","description":"Chain"},"address":{"type":"string","title":"Address","description":"Address of the wallet. Empty if entity_name is provided. EVM addresses are returned in lowercase."},"token_address":{"type":"string","title":"Token Address","description":"Address of token"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"token_name":{"anyOf":[{"type":"string"}],"title":"Token Name","description":"Token name"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"Token balance"},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Price of the token"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Token balance value in USD"}},"type":"object","required":["chain","address","token_address","token_symbol"],"title":"ProfilerBalance","description":"Individual profiler balance record.\n\nRepresents a single token balance from the wallet profiler."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/address/current-balance":{"post":{"tags":["Profiler"],"summary":"Get Address Current Balance Data","description":"Retrieve current token holdings for addresses or entities. Returns detailed balance information across specified chains.\n\nWhat it helps to answer:\n\n- Current token holdings with quantities and USD valuations\n- Asset distribution across different blockchain networks\n- Native token versus token balances\n- Stablecoin holdings and percentages\n- Cross-chain portfolio composition\n\nNote: The address field in the response will be empty if entity_name is provided.","operationId":"get_profiler_address_current_balance_api_v1_profiler_address_current_balance_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressBalancesRequest"}}},"required":true},"responses":{"200":{"description":"Address current balance data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressBalancesResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Address Historical Balances Get historical token balance information for any blockchain address or entity ### Common Scenarios {% hint style="info" %} You can use this endpoint to find correct entity name format to use in this Profiler Endpoint: [**Click Here**](https://docs.nansen.ai/api/profiler/entity-name-search) {% endhint %}
UsecaseRequired ParametersOptional FiltersExpected Output
Check current holdings for a single addressaddress = "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 = trueAggregated balances for entity across all wallets, showing holdings per chain
### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Results are served from a **short server-side cache of up to about an hour**, so very recent balance changes (including current-day activity) may take up to that long to appear — longer than the standard live latency. ## Get Address Historical Balances Data > Track token and native coin balance changes over time for addresses or entities. Provides snapshots at configurable intervals to analyze holding patterns, transaction activity, and portfolio evolution across multiple blockchains.\ > \ > What it helps to answer:\ > \ > \- Portfolio value changes across different time periods\ > \- Token accumulation and distribution patterns over selected timeframes\ > \- New positions entered and exited during specific periods ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"ProfilerAddressHistoricalBalancesRequest":{"properties":{"address":{"anyOf":[{"type":"string"}],"title":"Address","description":"Address to get historical balances for"},"entity_name":{"anyOf":[{"type":"string"}],"title":"Entity Name","description":"Entity name to get historical balances for"},"chain":{"$ref":"#/components/schemas/ProfilerChain","description":"Blockchain chain for the historical balances"},"date":{"$ref":"#/components/schemas/DateRange","description":"Date range for historical data"},"filters":{"anyOf":[{"$ref":"#/components/schemas/ProfilerAddressHistoricalBalancesFilters"}],"description":"Additional filters to apply. Only filters for columns that are being selected will be applied."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProfilerAddressHistoricalBalancesSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering"}},"additionalProperties":false,"type":"object","required":["chain","date"],"title":"ProfilerAddressHistoricalBalancesRequest","description":""},"ProfilerChain":{"type":"string","enum":["all","arbitrum","arc","avalanche","base","bitcoin","bnb","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"ProfilerChain","description":"Chains supported in profiler analysis."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"ProfilerAddressHistoricalBalancesFilters":{"properties":{"value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Balance range filter in USD"},"token_amount":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Token balance count range filter"},"token_symbol":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Symbol","description":"Token symbol filter"},"token_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Address","description":"Token address filter"},"hide_spam_tokens":{"anyOf":[{"type":"boolean"}],"title":"Hide Spam Tokens","description":"Whether to hide spam tokens from results","default":true}},"additionalProperties":false,"type":"object","title":"ProfilerAddressHistoricalBalancesFilters","description":"Filters for profiler address historical balances endpoint.\n\nThese filters control which historical balance data is included."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"ProfilerAddressHistoricalBalancesSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/ProfilerAddressHistoricalBalancesSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"ProfilerAddressHistoricalBalancesSortOrder"},"ProfilerAddressHistoricalBalancesSortField":{"type":"string","enum":["block_timestamp","value_usd","token_symbol"],"title":"ProfilerAddressHistoricalBalancesSortField","description":"Enum for sortable fields in profiler address historical balances."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"ProfilerAddressHistoricalBalancesResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/ProfilerHistoricalBalance"},"type":"array","title":"Data","description":"List of historical balance records"}},"type":"object","required":["pagination","data"],"title":"ProfilerAddressHistoricalBalancesResponse","description":"Response model for profiler address historical-balances endpoint.\n\nContains the filtered historical balance data with metadata."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ProfilerHistoricalBalance":{"properties":{"block_timestamp":{"type":"string","title":"Block Timestamp","description":"The block timestamp as date"},"token_address":{"type":"string","title":"Token Address","description":"Token Address"},"chain":{"type":"string","title":"Chain","description":"Chain"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"Token amount"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Usd balance of the holdings"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Symbol of the token"}},"type":"object","required":["block_timestamp","token_address","chain","token_symbol"],"title":"ProfilerHistoricalBalance","description":"Individual profiler historical balance record.\n\nRepresents a single historical token balance from the wallet profiler."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/address/historical-balances":{"post":{"tags":["Profiler"],"summary":"Get Address Historical Balances Data","description":"Track token and native coin balance changes over time for addresses or entities. Provides snapshots at configurable intervals to analyze holding patterns, transaction activity, and portfolio evolution across multiple blockchains.\n\nWhat it helps to answer:\n\n- Portfolio value changes across different time periods\n- Token accumulation and distribution patterns over selected timeframes\n- New positions entered and exited during specific periods","operationId":"get_profiler_address_historical_balances_api_v1_profiler_address_historical_balances_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressHistoricalBalancesRequest"}}},"required":true},"responses":{"200":{"description":"Address historical balances data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressHistoricalBalancesResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Address DEX Trades ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it. ## Get Wallet DEX Trades > Get DEX trade history for a wallet address on a specific chain. Each record includes the bought/sold tokens, amounts, symbols, token age, market cap, FDV, and the USD value of the trade.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*What DEX trades has this wallet executed on a chain within a date range?\*\*\ > 2\. \*\*Which tokens are being bought and sold, and at what sizes?\*\*\ > 3\. \*\*What is the USD value of each trade, and what was the token's market cap and FDV at trade time?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"ProfilerDexTradeRequest":{"properties":{"address":{"type":"string","title":"Address","description":"Trader address"},"chain":{"$ref":"#/components/schemas/ProfilerDexTradesChain","description":"Chain to query"},"date":{"$ref":"#/components/schemas/DateRange","description":"Date range for the trades"},"filters":{"anyOf":[{"$ref":"#/components/schemas/ProfilerDexTradeFilters"}],"description":"Additional filters for the trades"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProfilerDexTradeSortOrder"},"type":"array"}],"title":"Order By","description":"Sort order for the trades"}},"additionalProperties":false,"type":"object","required":["address","chain","date"],"title":"ProfilerDexTradeRequest","description":"Request model for the Profiler DEX Trades endpoint."},"ProfilerDexTradesChain":{"type":"string","enum":["arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"ProfilerDexTradesChain","description":"Chains supported in profiler DEX trades analysis."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"ProfilerDexTradeFilters":{"properties":{"token_bought_address":{"anyOf":[{"type":"string"}],"title":"Token Bought Address","description":"Filter by bought token address"},"token_sold_address":{"anyOf":[{"type":"string"}],"title":"Token Sold Address","description":"Filter by sold token address"},"token_bought_symbol":{"anyOf":[{"type":"string"}],"title":"Token Bought Symbol","description":"Filter by bought token symbol"},"token_sold_symbol":{"anyOf":[{"type":"string"}],"title":"Token Sold Symbol","description":"Filter by sold token symbol"},"token_bought_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Bought amount range filter"},"token_sold_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Sold amount range filter"},"token_bought_age_days":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Bought token age (in days) range filter"},"token_sold_age_days":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Sold token age (in days) range filter"},"token_bought_market_cap":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Bought token market cap range filter"},"token_sold_market_cap":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Sold token market cap range filter"},"token_bought_fdv":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Bought token FDV range filter"},"token_sold_fdv":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Sold token FDV range filter"},"trade_value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Trade value (USD) range filter"}},"additionalProperties":false,"type":"object","title":"ProfilerDexTradeFilters","description":"Filters for DEX trades."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"ProfilerDexTradeSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/ProfilerDexTradeSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"ProfilerDexTradeSortOrder"},"ProfilerDexTradeSortField":{"type":"string","enum":["chain","block_timestamp","transaction_hash","token_bought_amount","token_sold_amount","token_bought_symbol","token_sold_symbol","token_bought_age_days","token_sold_age_days","token_bought_market_cap","token_sold_market_cap","token_bought_fdv","token_sold_fdv","trade_value_usd"],"title":"ProfilerDexTradeSortField","description":"Enum for DEX trade sort fields."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"ProfilerDexTradeResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/ProfilerDexTrade"},"type":"array","title":"Data","description":"List of DEX trades"}},"additionalProperties":false,"type":"object","required":["pagination","data"],"title":"ProfilerDexTradeResponse","description":"Response model for the Profiler DEX Trades endpoint."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ProfilerDexTrade":{"properties":{"chain":{"type":"string","title":"Chain","description":"Chain on which the trade occurred"},"block_timestamp":{"type":"string","title":"Block Timestamp","description":"Block timestamp of the trade"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Transaction hash of the trade"},"trader_address":{"type":"string","title":"Trader Address","description":"Address that executed the trade"},"trader_address_label":{"anyOf":[{"type":"string"}],"title":"Trader Address Label","description":"Label associated with the trader address"},"token_bought_address":{"type":"string","title":"Token Bought Address","description":"Address of the bought token"},"token_sold_address":{"type":"string","title":"Token Sold Address","description":"Address of the sold token"},"token_bought_amount":{"anyOf":[{"type":"number"}],"title":"Token Bought Amount","description":"Amount of the bought token"},"token_sold_amount":{"anyOf":[{"type":"number"}],"title":"Token Sold Amount","description":"Amount of the sold token"},"token_bought_symbol":{"anyOf":[{"type":"string"}],"title":"Token Bought Symbol","description":"Symbol of the bought token"},"token_sold_symbol":{"anyOf":[{"type":"string"}],"title":"Token Sold Symbol","description":"Symbol of the sold token"},"token_bought_age_days":{"anyOf":[{"type":"integer"}],"title":"Token Bought Age Days","description":"Age (in days) of the bought token"},"token_sold_age_days":{"anyOf":[{"type":"integer"}],"title":"Token Sold Age Days","description":"Age (in days) of the sold token"},"token_bought_market_cap":{"anyOf":[{"type":"number"}],"title":"Token Bought Market Cap","description":"Market cap of the bought token at trade time"},"token_sold_market_cap":{"anyOf":[{"type":"number"}],"title":"Token Sold Market Cap","description":"Market cap of the sold token at trade time"},"token_bought_fdv":{"anyOf":[{"type":"number"}],"title":"Token Bought Fdv","description":"Fully diluted valuation of the bought token"},"token_sold_fdv":{"anyOf":[{"type":"number"}],"title":"Token Sold Fdv","description":"Fully diluted valuation of the sold token"},"trade_value_usd":{"anyOf":[{"type":"number"}],"title":"Trade Value Usd","description":"USD value of the trade"}},"additionalProperties":false,"type":"object","required":["chain","block_timestamp","transaction_hash","trader_address","token_bought_address","token_sold_address"],"title":"ProfilerDexTrade","description":"A single DEX trade by the profiled address."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/dex-trades":{"post":{"tags":["Profiler"],"summary":"Get Wallet DEX Trades","description":"Get DEX trade history for a wallet address on a specific chain. Each record includes the bought/sold tokens, amounts, symbols, token age, market cap, FDV, and the USD value of the trade.\n\n**What it helps to answer:**\n\n1. **What DEX trades has this wallet executed on a chain within a date range?**\n2. **Which tokens are being bought and sold, and at what sizes?**\n3. **What is the USD value of each trade, and what was the token's market cap and FDV at trade time?**","operationId":"get_profiler_dex_trades_api_v1_profiler_dex_trades_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerDexTradeRequest"}}},"required":true},"responses":{"200":{"description":"DEX trade history for the address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerDexTradeResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Address Transactions ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it. ## Get Address Transactions Data > Retrieve recent blockchain transactions for an address including token transfers, native currency movements, and contract interactions. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"ProfilerAddressTransactionsRequest":{"properties":{"address":{"type":"string","title":"Address","description":"Address to get transactions for"},"chain":{"$ref":"#/components/schemas/ProfilerTransactionsChain","description":"Blockchain chain for the transactions"},"date":{"$ref":"#/components/schemas/DateRange","description":"Date range for the transactions"},"hide_spam_token":{"type":"boolean","title":"Hide Spam Token","description":"Removes suspicious tokens from the transaction list","default":true},"filters":{"anyOf":[{"$ref":"#/components/schemas/ProfilerAddressTransactionsFilters"}],"description":"Additional filters to apply. Only filters for columns that are being selected will be applied."},"pagination":{"$ref":"#/components/schemas/ProfilerPaginationRequest","description":"Pagination parameters. This endpoint caps page size at 100, lower than the API-wide maximum of 1000, and defaults to 20."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProfilerAddressTransactionsSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering"}},"additionalProperties":false,"type":"object","required":["address","chain","date"],"title":"ProfilerAddressTransactionsRequest","description":""},"ProfilerTransactionsChain":{"type":"string","enum":["all","arbitrum","arc","avalanche","base","bitcoin","bnb","ethereum","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"ProfilerTransactionsChain","description":"Chains supported in profiler transactions analysis."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"ProfilerAddressTransactionsFilters":{"properties":{"token_symbol":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Symbol","description":"Token symbol filter"},"token_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Address","description":"Token address filter"},"counterparty_name":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Counterparty Name","description":"Counterparty name filter"},"counterparty_address":{"anyOf":[{"type":"string"}],"title":"Counterparty Address","description":"Counterparty address filter"},"volume_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Transaction volume range filter in USD"},"method":{"anyOf":[{"type":"string"}],"title":"Method","description":"Transaction method filter"},"source_type":{"anyOf":[{"type":"string"}],"title":"Source Type","description":"Transaction source type filter"}},"additionalProperties":false,"type":"object","title":"ProfilerAddressTransactionsFilters","description":"Filters for profiler address transactions endpoint.\n\nThese filters control which transactions are included\nin the wallet transaction history."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"ProfilerPaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":100,"minimum":1,"title":"Per Page","description":"Number of records per page. This endpoint caps page size at 100, lower than the API-wide maximum of 1000, to keep response times predictable for address transaction history. Values above 100 are rejected with a validation error.","default":20}},"type":"object","title":"ProfilerPaginationRequest","description":"Pagination parameters for address transaction history.\n\nThis endpoint allows at most 100 records per page, lower than the API-wide\nmaximum of 1000, and returns 20 records per page by default."},"ProfilerAddressTransactionsSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/ProfilerAddressTransactionsSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"ProfilerAddressTransactionsSortOrder"},"ProfilerAddressTransactionsSortField":{"type":"string","enum":["block_timestamp"],"title":"ProfilerAddressTransactionsSortField","description":"Enum for sortable fields in smart money inflows."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"ProfilerAddressTransactionsResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/ProfilerTransaction"},"type":"array","title":"Data","description":"List of transaction records"}},"type":"object","required":["pagination","data"],"title":"ProfilerAddressTransactionsResponse","description":"Response model for profiler address transactions endpoint.\n\nContains the filtered transaction data with metadata."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ProfilerTransaction":{"properties":{"chain":{"type":"string","title":"Chain","description":"Blockchain chain"},"method":{"type":"string","title":"Method","description":"Transaction method (sent/received)"},"tokens_sent":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProfilerTokenInfo"},"type":"array"}],"title":"Tokens Sent","description":"Tokens sent in the transaction"},"tokens_received":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProfilerTokenInfo"},"type":"array"}],"title":"Tokens Received","description":"Tokens received in the transaction"},"volume_usd":{"anyOf":[{"type":"number"}],"title":"Volume Usd","description":"Transaction volume in USD"},"block_timestamp":{"type":"string","title":"Block Timestamp","description":"Block timestamp in ISO format"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Transaction hash in hex format"},"source_type":{"type":"string","title":"Source Type","description":"Transaction source type"}},"type":"object","required":["chain","method","block_timestamp","transaction_hash","source_type"],"title":"ProfilerTransaction","description":"Individual profiler transaction record.\n\nRepresents a single transaction from the wallet profiler."},"ProfilerTokenInfo":{"properties":{"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"token_amount":{"type":"number","title":"Token Amount","description":"Token amount"},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Token price in USD"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Token value in USD"},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"chain":{"type":"string","title":"Chain","description":"Blockchain chain"},"from_address":{"type":"string","title":"From Address","description":"Source address"},"to_address":{"type":"string","title":"To Address","description":"Destination address"},"from_address_label":{"anyOf":[{"type":"string"}],"title":"From Address Label","description":"Source address label"},"to_address_label":{"anyOf":[{"type":"string"}],"title":"To Address Label","description":"Destination address label"}},"type":"object","required":["token_symbol","token_amount","token_address","chain","from_address","to_address"],"title":"ProfilerTokenInfo","description":"Token information for profiler transactions.\n\nRepresents detailed information about a token in a transaction."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/address/transactions":{"post":{"tags":["Profiler"],"summary":"Get Address Transactions Data","description":"Retrieve recent blockchain transactions for an address including token transfers, native currency movements, and contract interactions.","operationId":"get_profiler_address_transactions_api_v1_profiler_address_transactions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressTransactionsRequest"}}},"required":true},"responses":{"200":{"description":"Address transaction data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressTransactionsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` ## Get Transaction with Token Transfer Lookup Data > Get comprehensive transaction information including token transfers and NFT transfers.\ > This endpoint provides detailed information about a specific transaction including\ > native cryptocurrency movements, token transfers, and NFT transfers with USD values. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TransactionLookupRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TransactionLookupChain","description":"Blockchain chain for the transaction lookup"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Transaction hash to lookup"},"block_timestamp":{"anyOf":[{"type":"string"}],"title":"Block Timestamp","description":"Timestamp of the transaction block (format: 'YYYY-MM-DD HH:MM:SS'). Optional for most EVM chains — resolved automatically when omitted. Required for non-EVM chains (bitcoin, tron, ton, starknet, sui)."}},"additionalProperties":false,"type":"object","required":["chain","transaction_hash"],"title":"TransactionLookupRequest","description":""},"TransactionLookupChain":{"type":"string","enum":["all","arbitrum","arc","avalanche","base","bitcoin","bnb","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","robinhood","sei","sonic","starknet","sui","ton","tron"],"title":"TransactionLookupChain","description":"Blockchain chain for the transaction lookup."},"TransactionLookupListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TransactionLookupResponse"},"type":"array","title":"Data","description":"List of transaction lookup results"}},"type":"object","required":["data"],"title":"TransactionLookupListResponse","description":"Response model for transaction lookup endpoint returning a list of transactions."},"TransactionLookupResponse":{"properties":{"chain":{"type":"string","title":"Chain","description":"The blockchain network of the transaction"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"The unique identifier of the transaction"},"from_address":{"type":"string","title":"From Address","description":"The hexadecimal address of the sender"},"from_address_label":{"anyOf":[{"type":"string"}],"title":"From Address Label","description":"The name or label associated with the sender's address"},"to_address":{"type":"string","title":"To Address","description":"The hexadecimal address of the recipient"},"to_address_label":{"anyOf":[{"type":"string"}],"title":"To Address Label","description":"The name or label associated with the recipient's address"},"native_value":{"anyOf":[{"type":"number"}],"title":"Native Value","description":"The amount of native cryptocurrency transferred"},"dated_native_price":{"anyOf":[{"type":"number"}],"title":"Dated Native Price","description":"The price of the native cryptocurrency at the time of the transaction"},"dated_native_value_usd":{"anyOf":[{"type":"number"}],"title":"Dated Native Value Usd","description":"The USD value of the native cryptocurrency transferred at the time of the transaction"},"current_native_price":{"anyOf":[{"type":"number"}],"title":"Current Native Price","description":"The current price of the native cryptocurrency"},"current_native_value_usd":{"anyOf":[{"type":"number"}],"title":"Current Native Value Usd","description":"The current USD value of the native cryptocurrency transferred"},"receipt_status":{"anyOf":[{"type":"integer"}],"title":"Receipt Status","description":"The status of the transaction receipt (1 for success, 0 for failure)"},"block_timestamp":{"type":"string","title":"Block Timestamp","description":"The timestamp of the block in which the transaction was included"},"token_transfer_array":{"anyOf":[{"items":{"$ref":"#/components/schemas/TokenTransfer"},"type":"array"}],"title":"Token Transfer Array","description":"Information about any token transfers associated with this transaction"},"nft_transfer_array":{"anyOf":[{"items":{"$ref":"#/components/schemas/NFTTransfer"},"type":"array"}],"title":"Nft Transfer Array","description":"Information about any NFT transfers associated with this transaction"}},"type":"object","required":["chain","transaction_hash","from_address","from_address_label","to_address","to_address_label","native_value","dated_native_price","dated_native_value_usd","current_native_price","current_native_value_usd","receipt_status","block_timestamp","token_transfer_array","nft_transfer_array"],"title":"TransactionLookupResponse","description":"Response model for transaction lookup endpoint.\n\nContains comprehensive transaction information including token transfers and NFT transfers."},"TokenTransfer":{"properties":{"from_address":{"type":"string","title":"From Address","description":"From address"},"from_address_label":{"type":"string","title":"From Address Label","description":"From address label"},"to_address":{"type":"string","title":"To Address","description":"To address"},"to_address_label":{"type":"string","title":"To Address Label","description":"To address label"},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"token_amount":{"type":"number","title":"Token Amount","description":"Token amount transferred"},"dated_price_usd":{"anyOf":[{"type":"number"}],"title":"Dated Price Usd","description":"Price of the token in USD at the time of the transaction"},"dated_value_usd":{"anyOf":[{"type":"number"}],"title":"Dated Value Usd","description":"USD value of the token transferred at the time of the transaction"},"current_price_usd":{"anyOf":[{"type":"number"}],"title":"Current Price Usd","description":"Current price of the token in USD"},"current_value_usd":{"anyOf":[{"type":"number"}],"title":"Current Value Usd","description":"Current USD value of the token transferred"},"transfer_id":{"type":"string","title":"Transfer Id","description":"Transfer ID"}},"type":"object","required":["from_address","from_address_label","to_address","to_address_label","token_address","token_symbol","token_amount","dated_price_usd","dated_value_usd","current_price_usd","current_value_usd","transfer_id"],"title":"TokenTransfer","description":"Model for token transfer information."},"NFTTransfer":{"properties":{"from_address":{"type":"string","title":"From Address","description":"From address"},"from_address_label":{"type":"string","title":"From Address Label","description":"From address label"},"to_address":{"type":"string","title":"To Address","description":"To address"},"to_address_label":{"type":"string","title":"To Address Label","description":"To address label"},"project_id":{"type":"string","title":"Project Id","description":"Project ID"},"collection_name":{"type":"string","title":"Collection Name","description":"Collection name"},"nft_id":{"type":"string","title":"Nft Id","description":"NFT ID"}},"type":"object","required":["from_address","from_address_label","to_address","to_address_label","project_id","collection_name","nft_id"],"title":"NFTTransfer","description":"Model for NFT transfer information."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/transaction-with-token-transfer-lookup":{"post":{"tags":["Profiler"],"summary":"Get Transaction with Token Transfer Lookup Data","description":"Get comprehensive transaction information including token transfers and NFT transfers.\n This endpoint provides detailed information about a specific transaction including\n native cryptocurrency movements, token transfers, and NFT transfers with USD values.","operationId":"get_transaction_with_token_transfer_lookup_api_v1_transaction_with_token_transfer_lookup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionLookupRequest"}}},"required":true},"responses":{"200":{"description":"Transaction lookup data with token and NFT transfer information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionLookupListResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Address Counterparties Get counterparties and their interaction statistics for any address or entity. ### Common Scenarios {% hint style="info" %} You can use this endpoint to find correct entity name format to use in this Profiler Endpoint: [**Click Here**](https://docs.nansen.ai/api/profiler/entity-name-search) {% endhint %}
UsecaseRequired ParametersExpected Output
Get counterparties for a single addressaddress = "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
### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Results are served from a server-side cache: once a requested date range has fully settled (about two days after it closes) it is cached for up to **7 days**, while ranges that include today or a recently-closed window use a short cache of up to **5 minutes**. ## Get Address Counterparties Data > Get top counterparties that wallet addresses have interacted with, supporting different\ > grouping options (wallet or entity) and source filtering (Combined, Tokens, ETH).\ > Returns interaction statistics including volume, frequency, and timing data.\ > \ > What it helps to answer:\ > \ > \- Most frequent transaction partners by count and volume\ > \- Net value flows between addresses (inflows vs outflows)\ > \- Exchange and protocol interaction patterns\ > \- DeFi protocol usage and DEX trading counterparties\ > \- High-value transfer relationships and funding sources ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"ProfilerAddressCounterpartiesRequest":{"properties":{"address":{"anyOf":[{"type":"string"}],"title":"Address","description":"Address to get counterparties for"},"entity_name":{"anyOf":[{"type":"string"}],"title":"Entity Name","description":"Entity name to get counterparties for"},"chain":{"$ref":"#/components/schemas/ProfilerChain","description":"Blockchain chain for the counterparties data"},"date":{"$ref":"#/components/schemas/DateRange","description":"Date range for the counterparties data. Note: High-volume addresses (e.g., WETH on Base) are limited to 180 days. Very high-activity wallets (e.g. exchange hot wallets) can be slow over wide ranges — use a shorter range for those."},"source_input":{"$ref":"#/components/schemas/SourceInput","description":"Type of interactions to include","default":"Combined"},"group_by":{"$ref":"#/components/schemas/GroupBy","description":"Group counterparties by wallet or entity","default":"wallet"},"filters":{"anyOf":[{"$ref":"#/components/schemas/ProfilerAddressCounterpartiesFilters"}],"description":"Additional filters to apply. Only filters for columns that are being selected will be applied."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProfilerAddressCounterpartiesSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"total_volume_usd\", \"direction\": \"DESC\"}] - Sort by total volume descending\n- [{\"field\": \"interaction_count\", \"direction\": \"ASC\"}] - Sort by interaction count ascending\n- [{\"field\": \"volume_in_usd\", \"direction\": \"DESC\"}] - Sort by incoming volume descending"}},"additionalProperties":false,"type":"object","required":["chain","date"],"title":"ProfilerAddressCounterpartiesRequest","description":""},"ProfilerChain":{"type":"string","enum":["all","arbitrum","arc","avalanche","base","bitcoin","bnb","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"ProfilerChain","description":"Chains supported in profiler analysis."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"SourceInput":{"type":"string","enum":["Combined","Tokens","ETH"],"title":"SourceInput","description":"Enum for source input types in counterparties endpoint."},"GroupBy":{"type":"string","enum":["wallet","entity"],"title":"GroupBy","description":"Enum for grouping types in counterparties endpoint."},"ProfilerAddressCounterpartiesFilters":{"properties":{"interaction_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Interaction count range filter"},"total_volume_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total volume range filter in USD"},"volume_in_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Volume in USD range filter"},"volume_out_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Volume out USD range filter"},"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Include smart money labels for counterparties"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels for counterparties"}},"additionalProperties":false,"type":"object","title":"ProfilerAddressCounterpartiesFilters","description":"Filters for profiler address counterparties endpoint.\n\nThese filters control which counterparties and interactions are included."},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"LabelType":{"type":"string","enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"title":"LabelType","description":"Filter by entity label type."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"ProfilerAddressCounterpartiesSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/ProfilerAddressCounterpartiesSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"ProfilerAddressCounterpartiesSortOrder"},"ProfilerAddressCounterpartiesSortField":{"type":"string","enum":["interaction_count","total_volume_usd","volume_in_usd","volume_out_usd"],"title":"ProfilerAddressCounterpartiesSortField","description":"Enum for sortable fields in profiler address counterparties."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"ProfilerAddressCounterpartiesResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/ProfilerCounterparty"},"type":"array","title":"Data","description":"List of counterparty records"}},"type":"object","required":["pagination","data"],"title":"ProfilerAddressCounterpartiesResponse","description":"Response model for profiler address counterparties endpoint.\n\nContains the filtered counterparties data with metadata."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ProfilerCounterparty":{"properties":{"counterparty_address":{"type":"string","title":"Counterparty Address","description":"Counterparty address in hex format"},"counterparty_address_label":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Counterparty Address Label","description":"List of labels associated with this counterparty"},"interaction_count":{"type":"integer","title":"Interaction Count","description":"Total number of interactions with this counterparty"},"total_volume_usd":{"anyOf":[{"type":"number"}],"title":"Total Volume Usd","description":"Total transaction volume in USD"},"volume_in_usd":{"anyOf":[{"type":"number"}],"title":"Volume In Usd","description":"Incoming transaction volume in USD"},"volume_out_usd":{"anyOf":[{"type":"number"}],"title":"Volume Out Usd","description":"Outgoing transaction volume in USD"},"tokens_info":{"anyOf":[{"items":{"$ref":"#/components/schemas/TokenInfo"},"type":"array"}],"title":"Tokens Info","description":"Per-token transfers with this counterparty, including total, incoming, and outgoing amounts in token units. Different tokens are not combined."}},"type":"object","required":["counterparty_address","interaction_count"],"title":"ProfilerCounterparty","description":"Individual profiler counterparty record.\n\nRepresents a counterparty that a wallet has interacted with."},"TokenInfo":{"properties":{"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"token_name":{"type":"string","title":"Token Name","description":"Token name"},"num_transfer":{"type":"string","title":"Num Transfer","description":"Number of transfers"},"total_token_amount":{"anyOf":[{"type":"number"}],"title":"Total Token Amount","description":"Total amount of this token transferred with this counterparty, in token units. Incoming and outgoing transfers of the same token are added together, matching total volume. Amounts of different tokens are not combined. Null when transferred token units cannot be determined."},"token_in_amount":{"anyOf":[{"type":"number"}],"title":"Token In Amount","description":"Amount of this token received from this counterparty, in token units, relative to the requested wallet or selected entity. Null when transferred token units cannot be determined."},"token_out_amount":{"anyOf":[{"type":"number"}],"title":"Token Out Amount","description":"Amount of this token sent to this counterparty, in token units, relative to the requested wallet or selected entity. Null when transferred token units cannot be determined."}},"type":"object","required":["token_address","token_symbol","token_name","num_transfer"],"title":"TokenInfo","description":"Token information for counterparty interactions."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/address/counterparties":{"post":{"tags":["Profiler"],"summary":"Get Address Counterparties Data","description":"Get top counterparties that wallet addresses have interacted with, supporting different\ngrouping options (wallet or entity) and source filtering (Combined, Tokens, ETH).\nReturns interaction statistics including volume, frequency, and timing data.\n\nWhat it helps to answer:\n\n- Most frequent transaction partners by count and volume\n- Net value flows between addresses (inflows vs outflows)\n- Exchange and protocol interaction patterns\n- DeFi protocol usage and DEX trading counterparties\n- High-value transfer relationships and funding sources","operationId":"get_profiler_address_counterparties_api_v1_profiler_address_counterparties_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressCounterpartiesRequest"}}},"required":true},"responses":{"200":{"description":"Address counterparties data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressCounterpartiesResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Address Counterparties (Batch) Batch counterparties lookup — counterparties and interaction statistics for up to 10 wallet addresses in a single request. Batch version of [Address Counterparties](/api/profiler/address-counterparties): fetch top counterparties for up to 10 distinct wallet addresses in a single request. Each input wallet gets its **own** counterparty set — results are **not** aggregated across wallets. Every response row carries a `wallet_address` field; group by it to split the flattened result back into per-wallet lists. ### Common Scenarios
UsecaseRequired ParametersExpected Output
Counterparties for several EVM wallets at oncewallet_addresses = ["0x28c6...", "0x1522..."],
chain = "ethereum"		Per-wallet counterparty lists with interaction stats, keyed by wallet_address
Batch across EVM chains in one requestwallet_addresses = ["0x...(eth)", "0x...(base)"],
chain = "all"		Each address auto-routed to its chain; counterparties returned per wallet
### Limitations * `wallet_addresses`: maximum **10 distinct** addresses per request. * `date`: maximum **90 days** per request; split wider windows into multiple requests. * `chain`: one ecosystem per request. Use `all` to batch across EVM chains (Ethereum, Base, Polygon, etc.) or `solana` for Solana; **EVM and Solana addresses cannot be mixed** in a single request. ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Results are served from a server-side cache: once a requested date range has fully settled (about two days after it closes) it is cached for up to **7 days**, while ranges that include today or a recently-closed window use a short cache of up to **5 minutes**. ## Get Address Counterparties Data (Batch) > Batch version of the address counterparties endpoint: fetch top counterparties for\ > up to 10 distinct wallet addresses across a date range of up to\ > 90 days.\ > \ > Each input wallet gets its \*\*own\*\* counterparty set — results are \*\*not\*\* aggregated\ > across the input wallets. Every row in the response carries a \`wallet\_address\` field;\ > group by it to demux the flattened result back into per-wallet counterparty lists.\ > \ > Rows are returned as contiguous per-wallet blocks (each block matches what the\ > single-wallet endpoint would return for that wallet), sorted within a block by the\ > requested \`order\_by\` (default \`total\_volume\_usd\` DESC).\ > \ > Limitations:\ > \- \`wallet\_addresses\`: maximum 10 distinct addresses per request.\ > \- \`date\`: maximum 90 days per request; split wider windows into multiple requests.\ > \- \`chain\`: one ecosystem per request. Use \`all\` to batch across EVM chains\ > (Ethereum, Base, Polygon, etc.) or \`solana\` for Solana; EVM and Solana\ > addresses cannot be mixed in a single request.\ > \ > For a single wallet, or for entity-name / entity-grouped lookups, use\ > \`/api/v1/profiler/address/counterparties\` instead. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"ProfilerAddressCounterpartiesBatchRequest":{"properties":{"wallet_addresses":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Wallet Addresses","description":"Wallet addresses to batch-query (max 10 distinct). Each address gets its own counterparty set; results are not aggregated across wallets. Every response row carries a `wallet_address` demux key."},"chain":{"$ref":"#/components/schemas/ProfilerChain","description":"Blockchain chain for the counterparties data. A single request covers one ecosystem: use `all` to batch addresses across EVM chains (auto-detected — Ethereum, Base, Polygon, etc. may be mixed), or `solana` for Solana. EVM and Solana addresses cannot be mixed in one request; query them separately."},"date":{"$ref":"#/components/schemas/DateRange","description":"Date range for the counterparties data. Batch requests are capped at 90 days; split wider ranges into multiple requests. Very high-activity wallets (e.g. exchange hot wallets) can be slow even within the cap — use a shorter range for those."},"source_input":{"$ref":"#/components/schemas/SourceInput","description":"Type of interactions to include","default":"Combined"},"filters":{"anyOf":[{"$ref":"#/components/schemas/ProfilerAddressCounterpartiesFilters"}],"description":"Additional filters to apply. Numeric range filters (interaction_count, total_volume_usd, volume_in_usd, volume_out_usd) are applied per counterparty row; include/exclude smart money labels filter by label. Filters for columns that are not selected are ignored."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters. Pages the flattened result stream, which is ordered as contiguous per-wallet blocks (see order_by)."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProfilerAddressCounterpartiesSortOrder"},"type":"array"}],"title":"Order By","description":"Sort order applied WITHIN each wallet's counterparty block.\n\nThe result is always grouped by `wallet_address` first (so each wallet's rows are\ncontiguous, like an independent single-wallet response), then sorted by these\nfields, then by `counterparty_address` as a final tiebreaker to keep pagination\ndeterministic across pages.\n\nDefaults to `total_volume_usd DESC`."}},"additionalProperties":false,"type":"object","required":["wallet_addresses","chain","date"],"title":"ProfilerAddressCounterpartiesBatchRequest","description":"Request model for the batch profiler address counterparties endpoint.\n\nWallet-address input only (no entity_name / entity grouping — use the\nsingle-wallet /v1/profiler/address/counterparties endpoint for those)."},"ProfilerChain":{"type":"string","enum":["all","arbitrum","arc","avalanche","base","bitcoin","bnb","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"ProfilerChain","description":"Chains supported in profiler analysis."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"SourceInput":{"type":"string","enum":["Combined","Tokens","ETH"],"title":"SourceInput","description":"Enum for source input types in counterparties endpoint."},"ProfilerAddressCounterpartiesFilters":{"properties":{"interaction_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Interaction count range filter"},"total_volume_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total volume range filter in USD"},"volume_in_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Volume in USD range filter"},"volume_out_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Volume out USD range filter"},"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Include smart money labels for counterparties"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels for counterparties"}},"additionalProperties":false,"type":"object","title":"ProfilerAddressCounterpartiesFilters","description":"Filters for profiler address counterparties endpoint.\n\nThese filters control which counterparties and interactions are included."},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"LabelType":{"type":"string","enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"title":"LabelType","description":"Filter by entity label type."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"ProfilerAddressCounterpartiesSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/ProfilerAddressCounterpartiesSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"ProfilerAddressCounterpartiesSortOrder"},"ProfilerAddressCounterpartiesSortField":{"type":"string","enum":["interaction_count","total_volume_usd","volume_in_usd","volume_out_usd"],"title":"ProfilerAddressCounterpartiesSortField","description":"Enum for sortable fields in profiler address counterparties."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"ProfilerAddressCounterpartiesBatchResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/BatchProfilerCounterparty"},"type":"array","title":"Data","description":"Counterparty rows across all requested wallets."}},"type":"object","required":["pagination","data"],"title":"ProfilerAddressCounterpartiesBatchResponse","description":"Response model for the batch profiler address counterparties endpoint.\n\n`data` is a flat list of counterparty rows ordered as contiguous per-wallet\nblocks; group by `wallet_address` to demux back into per-wallet results."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"BatchProfilerCounterparty":{"properties":{"counterparty_address":{"type":"string","title":"Counterparty Address","description":"Counterparty address in hex format"},"counterparty_address_label":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Counterparty Address Label","description":"List of labels associated with this counterparty"},"interaction_count":{"type":"integer","title":"Interaction Count","description":"Total number of interactions with this counterparty"},"total_volume_usd":{"anyOf":[{"type":"number"}],"title":"Total Volume Usd","description":"Total transaction volume in USD"},"volume_in_usd":{"anyOf":[{"type":"number"}],"title":"Volume In Usd","description":"Incoming transaction volume in USD"},"volume_out_usd":{"anyOf":[{"type":"number"}],"title":"Volume Out Usd","description":"Outgoing transaction volume in USD"},"tokens_info":{"anyOf":[{"items":{"$ref":"#/components/schemas/TokenInfo"},"type":"array"}],"title":"Tokens Info","description":"Per-token transfers with this counterparty, including total, incoming, and outgoing amounts in token units. Different tokens are not combined."},"wallet_address":{"type":"string","title":"Wallet Address","description":"The input wallet (from `wallet_addresses`) this row belongs to."},"chain":{"type":"string","title":"Chain","description":"Chain this interaction occurred on. For chain='all' (cross-EVM) the same (wallet, counterparty) pair can appear on multiple chains as separate rows."}},"type":"object","required":["counterparty_address","interaction_count","wallet_address","chain"],"title":"BatchProfilerCounterparty","description":"A single counterparty row, tagged with the input wallet it belongs to.\n\nExtends the single-wallet `ProfilerCounterparty` with the `wallet_address`\ndemux key so the caller can split the flattened batch result back out per\nwallet."},"TokenInfo":{"properties":{"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"token_name":{"type":"string","title":"Token Name","description":"Token name"},"num_transfer":{"type":"string","title":"Num Transfer","description":"Number of transfers"},"total_token_amount":{"anyOf":[{"type":"number"}],"title":"Total Token Amount","description":"Total amount of this token transferred with this counterparty, in token units. Incoming and outgoing transfers of the same token are added together, matching total volume. Amounts of different tokens are not combined. Null when transferred token units cannot be determined."},"token_in_amount":{"anyOf":[{"type":"number"}],"title":"Token In Amount","description":"Amount of this token received from this counterparty, in token units, relative to the requested wallet or selected entity. Null when transferred token units cannot be determined."},"token_out_amount":{"anyOf":[{"type":"number"}],"title":"Token Out Amount","description":"Amount of this token sent to this counterparty, in token units, relative to the requested wallet or selected entity. Null when transferred token units cannot be determined."}},"type":"object","required":["token_address","token_symbol","token_name","num_transfer"],"title":"TokenInfo","description":"Token information for counterparty interactions."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/address/counterparties/batch":{"post":{"tags":["Profiler"],"summary":"Get Address Counterparties Data (Batch)","description":"Batch version of the address counterparties endpoint: fetch top counterparties for\nup to 10 distinct wallet addresses across a date range of up to\n90 days.\n\nEach input wallet gets its **own** counterparty set — results are **not** aggregated\nacross the input wallets. Every row in the response carries a `wallet_address` field;\ngroup by it to demux the flattened result back into per-wallet counterparty lists.\n\nRows are returned as contiguous per-wallet blocks (each block matches what the\nsingle-wallet endpoint would return for that wallet), sorted within a block by the\nrequested `order_by` (default `total_volume_usd` DESC).\n\nLimitations:\n- `wallet_addresses`: maximum 10 distinct addresses per request.\n- `date`: maximum 90 days per request; split wider windows into multiple requests.\n- `chain`: one ecosystem per request. Use `all` to batch across EVM chains\n (Ethereum, Base, Polygon, etc.) or `solana` for Solana; EVM and Solana\n addresses cannot be mixed in a single request.\n\nFor a single wallet, or for entity-name / entity-grouped lookups, use\n`/api/v1/profiler/address/counterparties` instead.","operationId":"get_profiler_address_counterparties_batch_api_v1_profiler_address_counterparties_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressCounterpartiesBatchRequest"}}},"required":true},"responses":{"200":{"description":"Batch address counterparties data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressCounterpartiesBatchResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Address Related Wallets ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Returns a **current, point-in-time view** of related wallets — there is no date-range parameter or historical look-back; relationships are derived from on-chain activity and reflect within the standard live latency. ## Get Address Related Wallets Data > Get wallets that are related to the input address through various types\ > of blockchain interactions and relationships. Returns detailed information\ > about each related wallet including the relationship type, transaction details, and timing information. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"ProfilerAddressRelatedWalletsRequest":{"properties":{"wallet_address":{"type":"string","title":"Wallet Address","description":"Wallet address to get related wallets for. Required, unless the deprecated `address` field is sent."},"address":{"anyOf":[{"type":"string"}],"title":"Address","description":"Deprecated: Use 'wallet_address' instead. Alias of `wallet_address`. If you send both fields, they must contain the same address.","deprecated":true},"chain":{"$ref":"#/components/schemas/ProfilerAddressRelatedWalletsChain","description":"Blockchain chain for the related wallets data"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProfilerAddressRelatedWalletsSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering"}},"additionalProperties":false,"type":"object","required":["chain"],"title":"ProfilerAddressRelatedWalletsRequest","description":""},"ProfilerAddressRelatedWalletsChain":{"type":"string","enum":["arbitrum","arc","avalanche","base","bitcoin","bnb","ethereum","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"ProfilerAddressRelatedWalletsChain","description":"Chains supported in profiler related wallets analysis."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"ProfilerAddressRelatedWalletsSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/ProfilerAddressRelatedWalletsSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"ProfilerAddressRelatedWalletsSortOrder"},"ProfilerAddressRelatedWalletsSortField":{"type":"string","enum":["order"],"title":"ProfilerAddressRelatedWalletsSortField","description":"Enum for sortable fields in profiler address related wallets."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"ProfilerAddressRelatedWalletsResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/ProfilerRelatedWallet"},"type":"array","title":"Data","description":"List of related wallet records"}},"type":"object","required":["pagination","data"],"title":"ProfilerAddressRelatedWalletsResponse","description":"Response model for profiler address related wallets endpoint.\n\nContains the related wallets data with metadata."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ProfilerRelatedWallet":{"properties":{"address":{"type":"string","title":"Address","description":"Hexadecimal representation of the related address"},"address_label":{"anyOf":[{"type":"string"}],"title":"Address Label","description":"The label of the address"},"relation":{"type":"string","title":"Relation","description":"The type of relation between the address and the input address"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Hexadecimal representation of the transaction hash"},"block_timestamp":{"type":"string","title":"Block Timestamp","description":"The timestamp of the transaction"},"order":{"type":"integer","title":"Order","description":"The order of the relation"},"chain":{"type":"string","title":"Chain","description":"The chain of the relation"}},"type":"object","required":["address","relation","transaction_hash","block_timestamp","order","chain"],"title":"ProfilerRelatedWallet","description":"Individual profiler related wallet record.\n\nRepresents a wallet that is related to the input address."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/address/related-wallets":{"post":{"tags":["Profiler"],"summary":"Get Address Related Wallets Data","description":"Get wallets that are related to the input address through various types\nof blockchain interactions and relationships. Returns detailed information\nabout each related wallet including the relationship type, transaction details, and timing information.","operationId":"get_profiler_address_related_wallets_api_v1_profiler_address_related_wallets_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressRelatedWalletsRequest"}}},"required":true},"responses":{"200":{"description":"Address related wallets data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressRelatedWalletsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Address First Funder Returns the **first funder** of a wallet: the earliest address to send native gas to the input EVM address. > **First funder = the first address to send native gas to this wallet**, on whichever supported chain the earliest funding happened. This is the gas-funder / funding source, **not** the USDC (or any stablecoin) source. Usually the same entity (a CEX withdrawal drops both), but not guaranteed. ### Notes * Input is any EVM address; non-EVM addresses are rejected. * `chain` is fixed to `all` — the first funder is resolved across chains and the returned `chain` reflects where the first funding occurred. * Returns a **current, point-in-time view**: there is no date-range parameter or historical look-back. See [Data Coverage by Chain](/api/data-coverage). * An **empty result** (`data: []`) is returned when the wallet has no first-funder attribution — e.g. a wallet that was only ever credited by an exchange or bridge withdrawal that paid the gas on its behalf, so the wallet itself never received native gas. This is a normal `200` response, not an error. ## Get Address First Funder Data > Get the first wallet that funded the input EVM address. The first funder is the\ > earliest address to send native gas to the wallet, returned with the Nansen label\ > of that funder and the funding transaction details. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"ProfilerAddressFirstFunderRequest":{"properties":{"address":{"type":"string","title":"Address","description":"EVM address to look up the first funder for"},"chain":{"$ref":"#/components/schemas/ProfilerAddressFirstFunderChain","description":"Fixed to 'all'; the first funder is resolved across chains","default":"all"}},"additionalProperties":false,"type":"object","required":["address"],"title":"ProfilerAddressFirstFunderRequest","description":""},"ProfilerAddressFirstFunderChain":{"type":"string","enum":["all"],"title":"ProfilerAddressFirstFunderChain","description":"Chains supported in profiler address first funder analysis (fixed to 'all')."},"ProfilerAddressFirstFunderResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/ProfilerAddressFirstFunderData"},"type":"array","title":"Data","description":"List of first funder records"}},"type":"object","required":["pagination","data"],"title":"ProfilerAddressFirstFunderResponse","description":"Response model for the profiler address first funder endpoint.\n\nContains the first funder record with metadata."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ProfilerAddressFirstFunderData":{"properties":{"wallet_address":{"type":"string","title":"Wallet Address","description":"The input wallet address that was funded"},"first_funder_address":{"type":"string","title":"First Funder Address","description":"The address that first funded the input wallet"},"first_funder_name":{"anyOf":[{"type":"string"}],"title":"First Funder Name","description":"The label of the first funder address"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Hexadecimal representation of the funding transaction hash"},"block_timestamp":{"type":"string","title":"Block Timestamp","description":"The timestamp of the funding transaction"},"chain":{"type":"string","title":"Chain","description":"The chain on which the first funding occurred"}},"type":"object","required":["wallet_address","first_funder_address","transaction_hash","block_timestamp","chain"],"title":"ProfilerAddressFirstFunderData","description":"First funder record for an input EVM address.\n\nThe first funder is the earliest address to send native gas to the input\nwallet. This is the gas-funder / funding source, not necessarily the source\nof any stablecoin balance."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/address/first-funder":{"post":{"tags":["Profiler"],"summary":"Get Address First Funder Data","description":"Get the first wallet that funded the input EVM address. The first funder is the\nearliest address to send native gas to the wallet, returned with the Nansen label\nof that funder and the funding transaction details.","operationId":"get_profiler_address_first_funder_api_v1_profiler_address_first_funder_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressFirstFunderRequest"}}},"required":true},"responses":{"200":{"description":"Address first funder data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressFirstFunderResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Address PnL & Trade Performance {% hint style="info" %} You can use this endpoint to find correct entity name format to use in this Profiler Endpoint: [**Click Here**](https://docs.nansen.ai/api/profiler/entity-name-search) {% endhint %} ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * The aggregate PnL summary is served from a **short server-side cache of up to about an hour**, so its figures may lag your most recent trades by up to that long; the detailed per-token PnL breakdown is served live within the standard latency. ## Get Address PnL Summary Data > Get aggregate PnL statistics and top profitable tokens for a specific wallet address.\ > This endpoint provides comprehensive profit and loss analysis including realized PnL, win rate, and top performing tokens. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"ProfilerAddressPnlSummaryRequest":{"properties":{"wallet_address":{"anyOf":[{"type":"string"}],"title":"Wallet Address","description":"Wallet address to get PnL summary for"},"address":{"anyOf":[{"type":"string"}],"title":"Address","description":"Deprecated: Use 'wallet_address' instead. Alias of `wallet_address`. If you send both fields, they must contain the same address.","deprecated":true},"entity_name":{"anyOf":[{"type":"string"}],"title":"Entity Name","description":"Entity name to get PnL summary for"},"chain":{"$ref":"#/components/schemas/ProfilerPnLChain","description":"Blockchain chain for the PnL data"},"date":{"$ref":"#/components/schemas/DateRange","description":"Date range for the PnL data"}},"additionalProperties":false,"type":"object","required":["chain","date"],"title":"ProfilerAddressPnlSummaryRequest","description":""},"ProfilerPnLChain":{"type":"string","enum":["all","arbitrum","arc","avalanche","base","bnb","ethereum","linea","mantle","monad","optimism","plasma","polygon","robinhood","sei","solana","sonic","sui"],"title":"ProfilerPnLChain","description":"Chains supported in profiler PnL analysis."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"ProfilerAddressPnlSummaryResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"top5_tokens":{"items":{"$ref":"#/components/schemas/ProfilerTopToken"},"type":"array","title":"Top5 Tokens","description":"Top 5 tokens by realized profit"},"traded_token_count":{"type":"integer","title":"Traded Token Count","description":"Total number of different tokens that have been bought or sold"},"traded_times":{"type":"integer","title":"Traded Times","description":"Total number of sales (outflow or dex sell)"},"realized_pnl_usd":{"type":"number","title":"Realized Pnl Usd","description":"Total realized profit and loss in USD"},"realized_pnl_percent":{"type":"number","title":"Realized Pnl Percent","description":"Realized profit and loss as a percentage (not multiplied by 100)"},"win_rate":{"type":"number","title":"Win Rate","description":"Number of sales where price of the token was higher than cost basis"}},"type":"object","required":["pagination","top5_tokens","traded_token_count","traded_times","realized_pnl_usd","realized_pnl_percent","win_rate"],"title":"ProfilerAddressPnlSummaryResponse","description":"Response model for profiler address pnl-summary endpoint.\n\nContains aggregate PnL statistics and top profitable tokens."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ProfilerTopToken":{"properties":{"realized_pnl":{"anyOf":[{"type":"number"}],"title":"Realized Pnl","description":"Realized profit and loss in USD"},"realized_roi":{"anyOf":[{"type":"number"}],"title":"Realized Roi","description":"Realized return on investment as percentage"},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"chain":{"type":"string","title":"Chain","description":"Blockchain chain"}},"type":"object","required":["realized_pnl","realized_roi","token_address","token_symbol","chain"],"title":"ProfilerTopToken","description":"Individual top token record for PnL summary.\n\nRepresents a top profitable token from the wallet's trading history."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/address/pnl-summary":{"post":{"tags":["Profiler"],"summary":"Get Address PnL Summary Data","description":"Get aggregate PnL statistics and top profitable tokens for a specific wallet address.\nThis endpoint provides comprehensive profit and loss analysis including realized PnL, win rate, and top performing tokens.","operationId":"get_profiler_address_pnl_summary_api_v1_profiler_address_pnl_summary_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressPnlSummaryRequest"}}},"required":true},"responses":{"200":{"description":"Address PnL summary data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressPnlSummaryResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` ## Retrieve address PnL data > Calculate profit and loss metrics for a specific address and token. Provides detailed trading performance including realized gains from sales and unrealized gains from current holdings.\ > \ > What it helps to answer:\ > \ > \- Realized profits or losses from completed token sales\ > \- Unrealized gains or losses on current token holdings\ > \- Average purchase and sale prices for the token\ > \- Total return on investment ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"ProfilerAddressPnlRequest":{"properties":{"address":{"anyOf":[{"type":"string"}],"title":"Address","description":"Wallet address to get PnL for"},"entity_name":{"anyOf":[{"type":"string"}],"title":"Entity Name","description":"Entity name to get PnL for"},"chain":{"$ref":"#/components/schemas/ProfilerPnLChain","description":"Blockchain chain for the PnL data"},"date":{"anyOf":[{"$ref":"#/components/schemas/DateRange"}],"description":"Date range for PnL analysis (ISO 8601 date-time)"},"filters":{"anyOf":[{"$ref":"#/components/schemas/ProfilerAddressPnlFilters"}],"description":"Additional filters to apply."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProfilerAddressPnlSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering (default: pnl_usd_realised DESC).\n\nIf the parameter show_realized is false, the default sort order is pnl_usd_unrealised DESC."}},"additionalProperties":false,"type":"object","required":["chain"],"title":"ProfilerAddressPnlRequest","description":""},"ProfilerPnLChain":{"type":"string","enum":["all","arbitrum","arc","avalanche","base","bnb","ethereum","linea","mantle","monad","optimism","plasma","polygon","robinhood","sei","solana","sonic","sui"],"title":"ProfilerPnLChain","description":"Chains supported in profiler PnL analysis."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"ProfilerAddressPnlFilters":{"properties":{"show_realized":{"anyOf":[{"type":"boolean"}],"title":"Show Realized","description":"Include realized profit/loss in results","default":false},"token_address":{"anyOf":[{"type":"string"}],"title":"Token Address","description":"Token address filter for specific token PnL"}},"additionalProperties":false,"type":"object","title":"ProfilerAddressPnlFilters","description":"Filters for profiler address PnL endpoint.\n\nThese filters control token filtering and realized PnL options for analysis."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"ProfilerAddressPnlSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/ProfilerAddressPnlSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"ProfilerAddressPnlSortOrder"},"ProfilerAddressPnlSortField":{"type":"string","enum":["pnl_usd_realised","roi_percent_realised","pnl_usd_unrealised","roi_percent_unrealised","bought_usd","sold_usd","holding_usd"],"title":"ProfilerAddressPnlSortField","description":"Enum for sortable fields in profiler address PnL."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"ProfilerAddressPnlResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/ProfilerAddressPnl"},"type":"array","title":"Data","description":"List of PnL records"}},"type":"object","required":["pagination","data"],"title":"ProfilerAddressPnlResponse","description":"Response model for profiler address pnl endpoint.\n\nContains the filtered PnL data with metadata."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ProfilerAddressPnl":{"properties":{"token_address":{"type":"string","title":"Token Address","description":"Hexadecimal representation of the token's address"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Symbol of the token"},"token_price":{"anyOf":[{"type":"number"}],"title":"Token Price","description":"Price of the token on date_to"},"roi_percent_realised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Realised","description":"Realised return on investment for only realised gains (not multiplied by 100)"},"pnl_usd_realised":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Realised","description":"Realised profit and loss in USD"},"pnl_usd_unrealised":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Unrealised","description":"Unrealised profit and loss in USD"},"roi_percent_unrealised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Unrealised","description":"Unrealised return on investment for only unrealised gains (not multiplied by 100)"},"bought_amount":{"anyOf":[{"type":"number"}],"title":"Bought Amount","description":"Amount of tokens bought from date_from to date_to"},"bought_usd":{"anyOf":[{"type":"number"}],"title":"Bought Usd","description":"USD value of bought tokens"},"cost_basis_usd":{"anyOf":[{"type":"number"}],"title":"Cost Basis Usd","description":"Cost basis of tokens in USD as of date_to"},"sold_amount":{"anyOf":[{"type":"number"}],"title":"Sold Amount","description":"Amount of tokens sold from date_from to date_to"},"sold_usd":{"anyOf":[{"type":"number"}],"title":"Sold Usd","description":"USD value of sold tokens"},"avg_sold_price_usd":{"anyOf":[{"type":"number"}],"title":"Avg Sold Price Usd","description":"Average sale price of tokens sold in USD"},"holding_amount":{"anyOf":[{"type":"number"}],"title":"Holding Amount","description":"Current token balance"},"holding_usd":{"anyOf":[{"type":"number"}],"title":"Holding Usd","description":"USD value of token balance"},"nof_buys":{"type":"string","title":"Nof Buys","description":"Number of buys (either inflow or dex buy)"},"nof_sells":{"type":"string","title":"Nof Sells","description":"Number of sells (either outflow or dex sell)"},"max_balance_held":{"anyOf":[{"type":"number"}],"title":"Max Balance Held","description":"Maximum amount of tokens held at some point in time"},"max_balance_held_usd":{"anyOf":[{"type":"number"}],"title":"Max Balance Held Usd","description":"Maximum amount of tokens in current USD value, held at some point in time"}},"type":"object","required":["token_address","token_symbol","nof_buys","nof_sells"],"title":"ProfilerAddressPnl","description":"Individual profiler address PnL record.\n\nRepresents PnL data for a token traded by the wallet."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/address/pnl":{"post":{"tags":["Profiler"],"summary":"Retrieve address PnL data","description":"Calculate profit and loss metrics for a specific address and token. Provides detailed trading performance including realized gains from sales and unrealized gains from current holdings.\n\nWhat it helps to answer:\n\n- Realized profits or losses from completed token sales\n- Unrealized gains or losses on current token holdings\n- Average purchase and sale prices for the token\n- Total return on investment","operationId":"get_profiler_address_pnl_api_v1_profiler_address_pnl_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressPnlRequest"}}},"required":true},"responses":{"200":{"description":"Address PnL data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressPnlResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Address Labels Retrieves all entity and behavioural labels associated with an address on a chain. ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Returns the **current set of labels** for an address — there is no date-range parameter or historical look-back; labels reflect Nansen's latest label data and update within the standard live latency. ### Empty results and credit charges Both endpoints return HTTP `200` with `data: []` when no eligible labels match the request. A successful empty response costs **0 credits**, including an empty page after the last result. A nonempty response costs **100 credits** for `/labels` or **500 credits** for `/premium-labels`. The balance check happens before the lookup. You still need at least 100 or 500 credits respectively to make the request. `X-Nansen-Credits-Cost` quotes that upfront amount; `X-Nansen-Credits-Used` reports the actual charge, which is `0` for an empty response. This rule applies to plan credits. Separate pay-per-request payments retain their own pricing. Labels are scoped to chains. An address can have labels on Ethereum and none on BNB, even though the address format is valid on both. Use `chain: "all"` to search all chains compatible with the address format. When the lookup finds no rows on the first page for a specific EVM chain, both endpoints return the same generic hint: ```json { "data": [], "hint": "Try chain: \"all\". No API credits were charged for this call." } ``` The example omits the usual pagination fields. This suggestion is returned regardless of whether labels exist on another chain. The response does not include a list of available chains. Requests using `chain: "all"`, non-EVM addresses, and empty later pages do not receive this hint. `chain: "all"` returns one combined list of eligible labels across chains compatible with the address format. Each label has `label`, `category`, and `kind`; labels are not grouped by chain. To retrieve labels for a particular chain, request that chain explicitly. Nonempty responses retain the endpoint's 100/500-credit price. Other reasons for an empty response include an address with no known labels, premium-only labels excluded by `/labels`, and exhausted pagination. `/premium-labels` can return a derived address name even when no labels are scoped to the requested chain. A response containing that name is nonempty and costs 500 credits. ## Retrieve address label data > Get labels for a wallet address. Returns non-premium labels only.\ > \ > Labels include ENS domains, behavioral labels, DeFi labels, CEX labels, and more.\ > Premium labels (smart money, alpha trader) are excluded from this endpoint.\ > \ > Use /api/v1/profiler/address/premium-labels to get all labels including premium ones.\ > \ > Successful empty responses cost 0 credits; nonempty responses cost 100 credits.\ > The upfront balance check still requires 100 credits. Empty first pages for\ > a specific EVM chain may include a generic hint to use chain="all". The hint does not report whether labels exist on other chains.\ > Empty later pages are also free. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"}},"schemas":{"ProfilerAddressLabelsRequest":{"properties":{"address":{"type":"string","title":"Address","description":"Wallet address to get labels for"},"chain":{"$ref":"#/components/schemas/ProfilerLabelsChain","description":"Blockchain chain. Use 'all' to search all chains compatible with the address format."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters (default: 100 per page)"}},"additionalProperties":false,"type":"object","required":["address","chain"],"title":"ProfilerAddressLabelsRequest","description":"Request model for Address Labels endpoint."},"ProfilerLabelsChain":{"type":"string","enum":["all","arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","hyperliquid","iotaevm","linea","mantle","monad","optimism","plasma","polygon","robinhood","sei","solana","sonic","tron"],"title":"ProfilerLabelsChain","description":"Chains supported for Profiler Address Labels endpoint."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"ProfilerAddressLabelsResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/ProfilerAddressLabel"},"type":"array","title":"Data","description":"List of labels for the address"},"hint":{"anyOf":[{"type":"string"}],"title":"Hint","description":"Generic suggestion to use chain='all' on an empty first page for a specific EVM chain. It does not indicate whether labels exist elsewhere."}},"type":"object","required":["pagination","data"],"title":"ProfilerAddressLabelsResponse","description":"Response model for Address Labels endpoint."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ProfilerAddressLabel":{"properties":{"label":{"type":"string","title":"Label","description":"The label name"},"category":{"anyOf":[{"type":"string"}],"title":"Category","description":"Label category (smart_money, behavioral, defi, social, cefi, nft, others)"},"kind":{"items":{"type":"string"},"type":"array","title":"Kind","description":"Label type/classifications, such as entity, name, or entity-tag"}},"type":"object","required":["label"],"title":"ProfilerAddressLabel","description":"A single label for a wallet address."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/address/labels":{"post":{"tags":["Profiler"],"summary":"Retrieve address label data","description":"Get labels for a wallet address. Returns non-premium labels only.\n\nLabels include ENS domains, behavioral labels, DeFi labels, CEX labels, and more.\nPremium labels (smart money, alpha trader) are excluded from this endpoint.\n\nUse /api/v1/profiler/address/premium-labels to get all labels including premium ones.\n\nSuccessful empty responses cost 0 credits; nonempty responses cost 100 credits.\nThe upfront balance check still requires 100 credits. Empty first pages for\na specific EVM chain may include a generic hint to use chain=\"all\". The hint does not report whether labels exist on other chains.\nEmpty later pages are also free.","operationId":"get_profiler_address_labels_api_v1_profiler_address_labels_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressLabelsRequest"}}},"required":true},"responses":{"200":{"description":"Address labels data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressLabelsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` ## Get Address Premium Labels > Get all labels for a wallet address, including premium labels.\ > \ > Returns all labels including smart money labels, alpha trader labels, and public figure tags\ > that are excluded from the standard /labels endpoint.\ > \ > Successful empty responses cost 0 credits; nonempty responses cost 500 credits.\ > The upfront balance check still requires 500 credits. Empty first pages for\ > a specific EVM chain may include a generic hint to use chain="all". The hint does not report whether labels exist on other chains.\ > Empty later pages are also free.\ > Derived address names can appear without labels scoped to the requested chain;\ > these make the response nonempty and it costs 500 credits. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"}},"schemas":{"ProfilerAddressLabelsRequest":{"properties":{"address":{"type":"string","title":"Address","description":"Wallet address to get labels for"},"chain":{"$ref":"#/components/schemas/ProfilerLabelsChain","description":"Blockchain chain. Use 'all' to search all chains compatible with the address format."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters (default: 100 per page)"}},"additionalProperties":false,"type":"object","required":["address","chain"],"title":"ProfilerAddressLabelsRequest","description":"Request model for Address Labels endpoint."},"ProfilerLabelsChain":{"type":"string","enum":["all","arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","hyperliquid","iotaevm","linea","mantle","monad","optimism","plasma","polygon","robinhood","sei","solana","sonic","tron"],"title":"ProfilerLabelsChain","description":"Chains supported for Profiler Address Labels endpoint."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"ProfilerAddressLabelsResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/ProfilerAddressLabel"},"type":"array","title":"Data","description":"List of labels for the address"},"hint":{"anyOf":[{"type":"string"}],"title":"Hint","description":"Generic suggestion to use chain='all' on an empty first page for a specific EVM chain. It does not indicate whether labels exist elsewhere."}},"type":"object","required":["pagination","data"],"title":"ProfilerAddressLabelsResponse","description":"Response model for Address Labels endpoint."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ProfilerAddressLabel":{"properties":{"label":{"type":"string","title":"Label","description":"The label name"},"category":{"anyOf":[{"type":"string"}],"title":"Category","description":"Label category (smart_money, behavioral, defi, social, cefi, nft, others)"},"kind":{"items":{"type":"string"},"type":"array","title":"Kind","description":"Label type/classifications, such as entity, name, or entity-tag"}},"type":"object","required":["label"],"title":"ProfilerAddressLabel","description":"A single label for a wallet address."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/address/premium-labels":{"post":{"tags":["Profiler"],"summary":"Get Address Premium Labels","description":"Get all labels for a wallet address, including premium labels.\n\nReturns all labels including smart money labels, alpha trader labels, and public figure tags\nthat are excluded from the standard /labels endpoint.\n\nSuccessful empty responses cost 0 credits; nonempty responses cost 500 credits.\nThe upfront balance check still requires 500 credits. Empty first pages for\na specific EVM chain may include a generic hint to use chain=\"all\". The hint does not report whether labels exist on other chains.\nEmpty later pages are also free.\nDerived address names can appear without labels scoped to the requested chain;\nthese make the response nonempty and it costs 500 credits.","operationId":"get_profiler_address_premium_labels_api_v1_profiler_address_premium_labels_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressLabelsRequest"}}},"required":true},"responses":{"200":{"description":"Address labels data (including premium)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressLabelsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` ### Related guides * [Use case 6: Finding FOMO Traders](/guides/templates/complex-use-cases/use-case-6-finding-fomo-traders) shows how to find wallets labelled with a FOMO handle and check a single wallet with `premium-labels`. # Address Perp Positions ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Returns a **current, point-in-time snapshot** of the address's open positions — there is no date-range parameter or historical look-back, and values reflect within the standard live latency. ## Get Perpetual Positions Data > Get perpetual positions data for a user by calling the Hyperliquid API directly. This endpoint provides real-time position information including entry price, mark price, PnL, leverage, and other position details.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*What are the current perpetual positions for a specific user address?\*\*\ > 2\. \*\*What is the unrealized PnL and performance of each position?\*\*\ > 3\. \*\*What are the leverage levels and margin requirements for each position?\*\*\ > 4\. \*\*What are the liquidation prices and risk levels for each position?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"PerpPositionsRequest":{"properties":{"address":{"type":"string","maxLength":42,"minLength":42,"title":"Address","description":"User's Hyperliquid address in 42-character hexadecimal format"},"filters":{"anyOf":[{"$ref":"#/components/schemas/PerpPositionsFilters"}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/PerpPositionsSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"position_value_usd\", \"direction\": \"DESC\"}] - Sort by position value descending\n- [{\"field\": \"unrealized_pnl_usd\", \"direction\": \"ASC\"}] - Sort by unrealized PnL ascending\n\nIf not provided, positions are sorted by position value descending."}},"additionalProperties":false,"type":"object","required":["address"],"title":"PerpPositionsRequest","description":"Request model for Perp Positions endpoint."},"PerpPositionsFilters":{"properties":{"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","description":"Filter by token symbol"},"position_value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Filter by position value in USD"},"position_type":{"anyOf":[{"type":"string"}],"title":"Position Type","description":"Filter by position type"},"unrealized_pnl_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Filter by unrealized PnL in USD"}},"additionalProperties":false,"type":"object","title":"PerpPositionsFilters","description":"Filters for perp positions endpoint."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"PerpPositionsSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/PerpPositionsSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"PerpPositionsSortOrder"},"PerpPositionsSortField":{"type":"string","enum":["leverage_value","position_value_usd","entry_price_usd","liquidation_price_usd","unrealized_pnl_usd","size","token_symbol","position_type"],"title":"PerpPositionsSortField","description":"Enum for perp positions sort fields."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"PerpPositionsResponse":{"properties":{"data":{"$ref":"#/components/schemas/PerpPositionsData","description":"Hyperliquid clearinghouse state data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"PerpPositionsResponse","description":"Response model for perp positions endpoint."},"PerpPositionsData":{"properties":{"assetPositions":{"anyOf":[{"items":{"$ref":"#/components/schemas/AssetPosition"},"type":"array"}],"title":"Assetpositions","description":"List of asset positions"},"crossMaintenanceMarginUsed":{"anyOf":[{"type":"string"}],"title":"Crossmaintenancemarginused","description":"Cross maintenance margin used USD"},"cross_margin_summary_account_value_usd":{"anyOf":[{"type":"string"}],"title":"Cross Margin Summary Account Value Usd","description":"Cross margin summary account value USD"},"cross_margin_summary_total_margin_used_usd":{"anyOf":[{"type":"string"}],"title":"Cross Margin Summary Total Margin Used Usd","description":"Cross margin summary total margin used USD"},"cross_margin_summary_total_net_liquidation_position_on_usd":{"anyOf":[{"type":"string"}],"title":"Cross Margin Summary Total Net Liquidation Position On Usd","description":"Cross margin summary total net liquidation position on USD"},"cross_margin_summary_total_raw_usd":{"anyOf":[{"type":"string"}],"title":"Cross Margin Summary Total Raw Usd","description":"Cross margin summary total raw USD"},"margin_summary_account_value_usd":{"anyOf":[{"type":"string"}],"title":"Margin Summary Account Value Usd","description":"Margin summary account value USD"},"margin_summary_total_margin_used_usd":{"anyOf":[{"type":"string"}],"title":"Margin Summary Total Margin Used Usd","description":"Margin summary total margin used USD"},"margin_summary_total_net_liquidation_position_usd":{"anyOf":[{"type":"string"}],"title":"Margin Summary Total Net Liquidation Position Usd","description":"Margin summary total net liquidation position USD"},"margin_summary_total_raw_usd":{"anyOf":[{"type":"string"}],"title":"Margin Summary Total Raw Usd","description":"Margin summary total raw USD"},"time":{"anyOf":[{"type":"integer"}],"title":"Time","description":"Timestamp"},"withdrawable":{"anyOf":[{"type":"string"}],"title":"Withdrawable","description":"Withdrawable USD"}},"additionalProperties":false,"type":"object","title":"PerpPositionsData","description":"Data model for Hyperliquid clearinghouse state response."},"AssetPosition":{"properties":{"position":{"anyOf":[{"$ref":"#/components/schemas/Position"}],"description":"Position data"},"position_type":{"anyOf":[{"type":"string"}],"title":"Position Type","description":"Position type"}},"additionalProperties":false,"type":"object","title":"AssetPosition","description":"Asset position wrapper."},"Position":{"properties":{"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","description":"Asset symbol (e.g., BTC, ETH)"},"size":{"anyOf":[{"type":"string"}],"title":"Size","description":"Size"},"position_value_usd":{"anyOf":[{"type":"string"}],"title":"Position Value Usd","description":"Position value USD"},"entry_price_usd":{"anyOf":[{"type":"string"}],"title":"Entry Price Usd","description":"Entry price USD"},"liquidation_price_usd":{"anyOf":[{"type":"string"}],"title":"Liquidation Price Usd","description":"Liquidation price USD"},"leverage_value":{"anyOf":[{"type":"integer"}],"title":"Leverage Value","description":"Leverage value"},"leverage_type":{"anyOf":[{"type":"string"}],"title":"Leverage Type","description":"Leverage type: 'cross' or 'isolated'"},"leverage_raw_usd":{"anyOf":[{"type":"string"}],"title":"Leverage Raw Usd","description":"Raw USD leverage"},"margin_used_usd":{"anyOf":[{"type":"string"}],"title":"Margin Used Usd","description":"Margin used USD"},"max_leverage_value":{"anyOf":[{"type":"integer"}],"title":"Max Leverage Value","description":"Maximum allowed leverage value"},"return_on_equity":{"anyOf":[{"type":"string"}],"title":"Return On Equity","description":"Return on equity"},"unrealized_pnl_usd":{"anyOf":[{"type":"string"}],"title":"Unrealized Pnl Usd","description":"Unrealized PnL USD"},"cumulative_funding_all_time_usd":{"anyOf":[{"type":"string"}],"title":"Cumulative Funding All Time Usd","description":"Cumulative funding all time USD"},"cumulative_funding_since_change_usd":{"anyOf":[{"type":"string"}],"title":"Cumulative Funding Since Change Usd","description":"Cumulative funding since change USD"},"cumulative_funding_since_open_usd":{"anyOf":[{"type":"string"}],"title":"Cumulative Funding Since Open Usd","description":"Cumulative funding since open USD"}},"additionalProperties":false,"type":"object","title":"Position","description":"Individual perpetual position."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/perp-positions":{"post":{"tags":["Profiler"],"summary":"Get Perpetual Positions Data","description":"Get perpetual positions data for a user by calling the Hyperliquid API directly. This endpoint provides real-time position information including entry price, mark price, PnL, leverage, and other position details.\n\n**What it helps to answer:**\n\n1. **What are the current perpetual positions for a specific user address?**\n2. **What is the unrealized PnL and performance of each position?**\n3. **What are the leverage levels and margin requirements for each position?**\n4. **What are the liquidation prices and risk levels for each position?**","operationId":"get_perp_positions_api_v1_profiler_perp_positions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpPositionsRequest"}}},"required":true},"responses":{"200":{"description":"Perpetual positions data for the user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpPositionsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Address Perp Trades ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Covers the Hyperliquid perpetuals dataset (reliable from **May 2025**), not per-chain history — see the Hyperliquid note on the coverage page. ## Get Perpetual Trade Data > Get perpetual trade data for a user. This endpoint provides trade information including trade price, size, side, fees, and other trade details.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*What are the perpetual trades for a specific user address within a date range?\*\*\ > 2\. \*\*What are the trade prices, sizes, and directions for each trade?\*\*\ > 3\. \*\*What are the trading fees and closed PnL for each trade?\*\*\ > 4\. \*\*What are the order IDs and transaction hashes for trade tracking?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"PerpTradeRequest":{"properties":{"address":{"type":"string","maxLength":42,"minLength":42,"title":"Address","description":"User's Hyperliquid address in 42-character hexadecimal format"},"date":{"$ref":"#/components/schemas/DateRange","description":"Date range for the trades (ISO 8601 date-time)"},"filters":{"anyOf":[{"$ref":"#/components/schemas/PerpTradeFilters"}],"description":"Additional filters for the trades"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/PerpTradeSortOrder"},"type":"array"}],"title":"Order By","description":"Sort order for the trades"}},"additionalProperties":false,"type":"object","required":["address","date"],"title":"PerpTradeRequest","description":"Request model for Perp Trades endpoint."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PerpTradeFilters":{"properties":{"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","description":"Token symbol filter"},"side":{"anyOf":[{"$ref":"#/components/schemas/PerpTradeType"}],"description":"Position side filter (Long or Short)"},"action":{"anyOf":[{"$ref":"#/components/schemas/PerpTradeActionFilter"}],"description":"Action filter (Open/Add, Close/Reduce, Liquidation)"},"crossed":{"anyOf":[{"type":"boolean"}],"title":"Crossed","description":"Whether the trade was crossed"},"size":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Trade size range filter"},"start_position":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Start position range filter"},"closed_pnl":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Closed PnL range filter"},"fee_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Fee in USD range filter"},"fee_token_symbol":{"anyOf":[{"type":"string"}],"title":"Fee Token Symbol","description":"Fee token filter"},"oid":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Order ID range filter"},"price":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Price range filter"},"value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Value in USD range filter"}},"additionalProperties":false,"type":"object","title":"PerpTradeFilters","description":"Filters for perp trades endpoint.\n\nThese filters control which perpetual trades are included in the results\nbased on various trade criteria."},"PerpTradeType":{"type":"string","enum":["Long","Short"],"title":"PerpTradeType","description":"Enum for perp trade position types."},"PerpTradeActionFilter":{"type":"string","enum":["Open/Add","Close/Reduce","Liquidation"],"title":"PerpTradeActionFilter","description":"Enum for perp trade action filters (grouped)."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"PerpTradeSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/PerpTradeSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"PerpTradeSortOrder"},"PerpTradeSortField":{"type":"string","enum":["timestamp","size","fee_usd","closed_pnl","price","value_usd"],"title":"PerpTradeSortField","description":"Enum for perp trade sort fields."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"PerpTradeResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/PerpTrade"},"type":"array","title":"Data","description":"List of perpetual trades"}},"additionalProperties":false,"type":"object","required":["pagination","data"],"title":"PerpTradeResponse","description":"Response model for perp trades endpoint."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"PerpTrade":{"properties":{"timestamp":{"type":"string","title":"Timestamp","description":"Timestamp of the trade"},"side":{"anyOf":[{"$ref":"#/components/schemas/PerpTradeType"}],"description":"Position side (Long or Short)"},"action":{"type":"string","title":"Action","description":"Action taken (Open, Add, Close, Reduce, etc.)"},"block_number":{"type":"integer","title":"Block Number","description":"Block number of the trade"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Symbol of the token"},"price":{"anyOf":[{"type":"number"}],"title":"Price","description":"Average price of the trade (averaged across fills)"},"size":{"type":"number","title":"Size","description":"Total size of the trade (sum of all fills)"},"value_usd":{"type":"number","title":"Value Usd","description":"Total value in USD of the trade"},"start_position":{"type":"number","title":"Start Position","description":"Start position of the trade in token units"},"closed_pnl":{"type":"number","title":"Closed Pnl","description":"Total closed PnL of the trade (sum of all fills)"},"crossed":{"type":"boolean","title":"Crossed","description":"Crossed of the trade"},"fee_usd":{"type":"number","title":"Fee Usd","description":"Total fee in USD of the trade (sum of all fills)"},"fee_token_symbol":{"type":"string","title":"Fee Token Symbol","description":"Fee in token of the trade"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Transaction hash of the trade"},"user":{"type":"string","title":"User","description":"User of the trade"},"oid":{"type":"integer","title":"Oid","description":"Order ID of the trade"}},"additionalProperties":false,"type":"object","required":["timestamp","side","action","block_number","token_symbol","price","size","value_usd","start_position","closed_pnl","crossed","fee_usd","fee_token_symbol","transaction_hash","user","oid"],"title":"PerpTrade","description":"Perpetual trade with computed type and action fields for client response."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/perp-trades":{"post":{"tags":["Profiler"],"summary":"Get Perpetual Trade Data","description":"Get perpetual trade data for a user. This endpoint provides trade information including trade price, size, side, fees, and other trade details.\n\n**What it helps to answer:**\n\n1. **What are the perpetual trades for a specific user address within a date range?**\n2. **What are the trade prices, sizes, and directions for each trade?**\n3. **What are the trading fees and closed PnL for each trade?**\n4. **What are the order IDs and transaction hashes for trade tracking?**","operationId":"get_perp_trades_api_v1_profiler_perp_trades_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpTradeRequest"}}},"required":true},"responses":{"200":{"description":"Perpetual trade data for the user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpTradeResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Hyperliquid Address Leaderboard {% hint style="warning" %} **Update:** The `premium_labels` parameter on this endpoint now defaults to `false`, as previously announced in the API changelog. Requests that omit the parameter return free-tier labels at the standard credit cost. Passing `premium_labels=true` returns premium labels (Smart Money, Fund, etc.), is billed at **150 credits per call**, and requires a paid plan. See the API changelog for details. {% endhint %} ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Covers the Hyperliquid perpetuals dataset (reliable from **May 2025**), not per-chain history — see the Hyperliquid note on the coverage page. ## Get Perpetual Trading Leaderboard Data > Get perpetual trading leaderboard data showing the most profitable traders within a given date range. This endpoint provides trader performance metrics including total PnL, ROI, and account values.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*Who are the most profitable perpetual traders in a given timeframe?\*\*\ > 2\. \*\*What is the ROI of the top performing traders?\*\*\ > 3\. \*\*What are the account values of successful perpetual traders?\*\*\ > 4\. \*\*How do trader addresses and labels correlate with performance?\*\*\ > 5\. \*\*What is a top trader holding right now?\*\*\ > \ > \*\*Key Features:\*\*\ > \- Trader address and label information\ > \- Total, realized and unrealized PnL in USD\ > \- ROI as a fractional ratio (0.15 means 15%)\ > \- Traded notional and fill count over the timeframe\ > \- The five largest open positions per trader\ > \- Account value tracking\ > \- Flexible filtering and sorting options\ > \ > \*\*Label Tier Control (\`premium\_labels\`):\*\*\ > When omitted or set to \`false\` (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing \`premium\_labels=true\` returns premium labels (Smart Money, Fund, and other advanced labels), is billed at \*\*150 credits per call\*\*, and requires a paid plan. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"PerpLeaderboardRequest":{"properties":{"date":{"$ref":"#/components/schemas/DateOnlyRange","description":"Date range object with optional from and to fields in YYYY-MM-DD format"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/PerpLeaderboardFilters"}],"description":"Additional filters to apply to the query."},"premium_labels":{"anyOf":[{"type":"boolean"}],"title":"Premium Labels","description":"Controls label tier in the response. When null/omitted or false (the default), returns free-tier labels at the standard credit cost for this endpoint. When true, returns premium labels (Smart Money, Fund, and other advanced labels), is billed at 150 credits per call, and requires a paid plan."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/PerpLeaderboardSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering"}},"additionalProperties":false,"type":"object","required":["date"],"title":"PerpLeaderboardRequest","description":"Request model for Perp Leaderboard endpoint.\nThis endpoint provides a perpetual trading leaderboard showing the most profitable\ntraders within a given date range."},"DateOnlyRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in YYYY-MM-DD format"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in YYYY-MM-DD format"}},"type":"object","title":"DateOnlyRange","description":"Date range model that only accepts YYYY-MM-DD format (no time components)."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"PerpLeaderboardFilters":{"properties":{"trader_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address","description":"Trader address filter"},"trader_address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address Label","description":"Filter by wallet display name. Use LIKE patterns (%) for partial matching. Note: This filters by the wallet's display name, not by label category. To filter by smart money labels, use include_smart_money_labels instead."},"total_pnl":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total PnL range filter in USD"},"roi":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"ROI range filter as a fractional ratio (0.15 means 15%). Signed, so a loss is negative and a min of 0 keeps profitable traders only."},"account_value":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Account value range filter in USD. Note: Only the top 500K traders have account value data available."},"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Filter to include only traders with these smart money labels. For Hyperliquid, use 'Smart HL Perps Trader'. See SmartMoneyFilterType enum for valid values."},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels"}},"additionalProperties":false,"type":"object","title":"PerpLeaderboardFilters","description":"Filters for Perp Leaderboard endpoint.\n\nThese filters control which traders are included in the leaderboard."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Filter by smart money label type."},"PerpLeaderboardSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/PerpLeaderboardSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"PerpLeaderboardSortOrder"},"PerpLeaderboardSortField":{"type":"string","enum":["total_pnl","realized_pnl_usd","unrealized_pnl_usd","roi","volume_usd","total_trades","account_value"],"title":"PerpLeaderboardSortField","description":"Sort field for the perpetuals leaderboard."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"PerpLeaderboardResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/PerpLeaderboard"},"type":"array","title":"Data","description":"List of Perp Leaderboard records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"PerpLeaderboardResponse","description":"Response model for Perp Leaderboard endpoint.\nContains a list of leaderboard records with pagination and metadata."},"PerpLeaderboard":{"properties":{"trader_address":{"type":"string","title":"Trader Address","description":"The Ethereum wallet address of the trader."},"trader_address_label":{"anyOf":[{"type":"string"}],"title":"Trader Address Label","description":"The name associated with the address, derived using Nansen's multichain label function for Ethereum."},"total_pnl":{"anyOf":[{"type":"number"}],"title":"Total Pnl","description":"Profit and loss for the selected timeframe in USD, realized plus unrealized."},"realized_pnl_usd":{"anyOf":[{"type":"number"}],"title":"Realized Pnl Usd","description":"Realized profit and loss for the selected timeframe in USD."},"unrealized_pnl_usd":{"anyOf":[{"type":"number"}],"title":"Unrealized Pnl Usd","description":"Unrealized profit and loss in USD on positions still open, valued at the current mark price."},"roi":{"anyOf":[{"type":"number"}],"title":"Roi","description":"Return on investment for the selected timeframe as a fractional ratio (0.15 means 15%, -0.20 means -20%). Computed as total_pnl divided by traded notional in USD plus the notional of positions still open, so it measures PnL per dollar traded rather than return on capital: a position that was opened and closed contributes both fills to the denominator."},"volume_usd":{"anyOf":[{"type":"number"}],"title":"Volume Usd","description":"Traded notional in USD over the selected timeframe. Both the opening and the closing fill of a position count."},"total_trades":{"anyOf":[{"type":"integer"}],"title":"Total Trades","description":"Number of fills over the selected timeframe."},"top_positions":{"items":{"$ref":"#/components/schemas/PerpLeaderboardPosition"},"type":"array","title":"Top Positions","description":"The trader's five largest open positions by absolute position value, largest first. Covers only positions in coins the trader traded during the selected timeframe, so a position held through the window in a coin that was not traded is not listed. Empty for a trader with no such open position."},"account_value":{"anyOf":[{"type":"number"}],"title":"Account Value","description":"Current total account value in USD. Note: Account value data is only available for the top 500K traders due to upstream data limitations. Traders outside the top 500K may show 0 or null values."}},"type":"object","required":["trader_address"],"title":"PerpLeaderboard","description":"Individual Perp Leaderboard record.\nRepresents a single trader's perpetual trading performance."},"PerpLeaderboardPosition":{"properties":{"coin":{"type":"string","title":"Coin","description":"Perp market symbol the position is in."},"side":{"type":"string","title":"Side","description":"Position direction: 'long' or 'short'."},"size_base":{"type":"number","title":"Size Base","description":"Position size in base/coin units (absolute); `side` carries direction."},"position_value_usd":{"type":"number","title":"Position Value Usd","description":"Notional value of the position in USD."},"entry_price":{"type":"number","title":"Entry Price","description":"Average entry price of the position."},"unrealized_pnl_usd":{"type":"number","title":"Unrealized Pnl Usd","description":"Unrealized PnL on the position, in USD."}},"type":"object","required":["coin","side","size_base","position_value_usd","entry_price","unrealized_pnl_usd"],"title":"PerpLeaderboardPosition","description":"A single open perpetual position held by a leaderboard trader."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/perp-leaderboard":{"post":{"tags":["Perp Leaderboard"],"summary":"Get Perpetual Trading Leaderboard Data","description":"Get perpetual trading leaderboard data showing the most profitable traders within a given date range. This endpoint provides trader performance metrics including total PnL, ROI, and account values.\n\n**What it helps to answer:**\n\n1. **Who are the most profitable perpetual traders in a given timeframe?**\n2. **What is the ROI of the top performing traders?**\n3. **What are the account values of successful perpetual traders?**\n4. **How do trader addresses and labels correlate with performance?**\n5. **What is a top trader holding right now?**\n\n**Key Features:**\n- Trader address and label information\n- Total, realized and unrealized PnL in USD\n- ROI as a fractional ratio (0.15 means 15%)\n- Traded notional and fill count over the timeframe\n- The five largest open positions per trader\n- Account value tracking\n- Flexible filtering and sorting options\n\n**Label Tier Control (`premium_labels`):**\nWhen omitted or set to `false` (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing `premium_labels=true` returns premium labels (Smart Money, Fund, and other advanced labels), is billed at **150 credits per call**, and requires a paid plan.","operationId":"get_perp_leaderboard_api_v1_perp_leaderboard_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpLeaderboardRequest"}}},"required":true},"responses":{"200":{"description":"Perpetual trading leaderboard data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpLeaderboardResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Get Hyperliquid Perp PnL Summary ## Get Hyperliquid Perp PnL Summary > Get aggregate realized PnL statistics for a Hyperliquid perpetual trader over a date range.\ > Returns total realized PnL, closing-notional return, fees, trade counts, win rate, and top coins.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*What is the total realized PnL for a Hyperliquid trader over a time period?\*\*\ > 2\. \*\*What is the win rate based on closing trades?\*\*\ > 3\. \*\*Which perp coins are the most profitable for this trader?\*\*\ > \ > \*\*Note:\*\* This endpoint covers realized PnL only. For current unrealized PnL and\ > open positions, use the \`profiler/perp-positions\` endpoint. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"PerpPnlSummaryRequest":{"properties":{"address":{"type":"string","maxLength":42,"minLength":42,"title":"Address","description":"Hyperliquid wallet address in 42-character hexadecimal format"},"date":{"$ref":"#/components/schemas/DateRange","description":"Date range for the PnL analysis"}},"additionalProperties":false,"type":"object","required":["address","date"],"title":"PerpPnlSummaryRequest","description":"Request model for the Hyperliquid perp PnL summary endpoint."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PerpPnlSummaryResponse":{"properties":{"data":{"$ref":"#/components/schemas/PerpPnlSummaryData","description":"Aggregate realized PnL summary"}},"additionalProperties":false,"type":"object","required":["data"],"title":"PerpPnlSummaryResponse","description":"Response model for the Hyperliquid perp PnL summary endpoint."},"PerpPnlSummaryData":{"properties":{"top5_coins":{"items":{"$ref":"#/components/schemas/PerpPnlTopCoin"},"type":"array","title":"Top5 Coins","description":"Top 5 coins by realized PnL"},"traded_coin_count":{"type":"integer","title":"Traded Coin Count","description":"Number of distinct perp coins traded"},"traded_times":{"type":"integer","title":"Traded Times","description":"Total number of trades"},"closed_trade_count":{"type":"integer","title":"Closed Trade Count","description":"Number of trades that close or reduce a position"},"winning_trade_count":{"type":"integer","title":"Winning Trade Count","description":"Number of closing trades with positive realized PnL"},"realized_pnl_usd":{"type":"number","title":"Realized Pnl Usd","description":"Total realized PnL in USD"},"realized_pnl_percent":{"type":"number","title":"Realized Pnl Percent","description":"Realized PnL divided by total closing notional"},"win_rate":{"type":"number","title":"Win Rate","description":"Share of closing trades with positive realized PnL"},"fees_usd":{"type":"number","title":"Fees Usd","description":"Total trading fees in USD"}},"additionalProperties":false,"type":"object","required":["top5_coins","traded_coin_count","traded_times","closed_trade_count","winning_trade_count","realized_pnl_usd","realized_pnl_percent","win_rate","fees_usd"],"title":"PerpPnlSummaryData","description":"Aggregate realized PnL summary for a Hyperliquid trader."},"PerpPnlTopCoin":{"properties":{"coin":{"type":"string","title":"Coin","description":"Perp coin symbol"},"realized_pnl_usd":{"type":"number","title":"Realized Pnl Usd","description":"Realized PnL in USD for this coin"},"realized_roi":{"type":"number","title":"Realized Roi","description":"Realized return on closing notional for this coin"},"closed_trade_count":{"type":"integer","title":"Closed Trade Count","description":"Number of closing trades for this coin"},"fees_usd":{"type":"number","title":"Fees Usd","description":"Total fees in USD for this coin"}},"additionalProperties":false,"type":"object","required":["coin","realized_pnl_usd","realized_roi","closed_trade_count","fees_usd"],"title":"PerpPnlTopCoin","description":"A top coin entry in the PnL summary."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/perp-pnl-summary":{"post":{"tags":["Profiler"],"summary":"Get Hyperliquid Perp PnL Summary","description":"Get aggregate realized PnL statistics for a Hyperliquid perpetual trader over a date range.\nReturns total realized PnL, closing-notional return, fees, trade counts, win rate, and top coins.\n\n**What it helps to answer:**\n\n1. **What is the total realized PnL for a Hyperliquid trader over a time period?**\n2. **What is the win rate based on closing trades?**\n3. **Which perp coins are the most profitable for this trader?**\n\n**Note:** This endpoint covers realized PnL only. For current unrealized PnL and\nopen positions, use the `profiler/perp-positions` endpoint.","operationId":"get_perp_pnl_summary_api_v1_profiler_perp_pnl_summary_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpPnlSummaryRequest"}}},"required":true},"responses":{"200":{"description":"Hyperliquid perp PnL summary data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpPnlSummaryResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Token God Mode # Token Information ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Returns current, point-in-time token metrics (no historical range); responses are cached for up to 5 minutes. ## Get "Token God Mode" (TGM) token information data > Get comprehensive token information including basic details (name, symbol, contract address, logo), token details (deployment date, social links, market metrics like market cap and FDV), and spot trading metrics (volume, buys/sells, unique traders, liquidity, holders).\ > \ > This endpoint provides a complete overview of a token's metadata, market position, and trading activity for a specific date range. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMTokenInformationRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TGMChain","description":"Blockchain chain"},"token_address":{"type":"string","title":"Token Address","description":"Token address"},"timeframe":{"$ref":"#/components/schemas/TGMFlowIntelligenceTimeframe","description":"Timeframe for the token information query"}},"additionalProperties":false,"type":"object","required":["chain","token_address","timeframe"],"title":"TGMTokenInformationRequest","description":"Request model for TGM token information endpoint.\nThis endpoint provides comprehensive token information including basic details,\ntoken details (deployment, social links, market metrics), and spot trading metrics."},"TGMChain":{"type":"string","enum":["arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","hyperliquid","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"TGMChain","description":"Chains supported in TGM (Token God Mode) endpoints."},"TGMFlowIntelligenceTimeframe":{"type":"string","enum":["5m","1h","6h","12h","1d","7d"],"title":"TGMFlowIntelligenceTimeframe","description":"TGM flow intelligence timeframe options."},"TGMTokenInformationResponse":{"properties":{"data":{"$ref":"#/components/schemas/TGMTokenInformation","description":"Token information data"}},"type":"object","required":["data"],"title":"TGMTokenInformationResponse","description":"Response model for TGM token information endpoint.\nContains comprehensive token information including basic details,\ntoken details, and spot metrics."},"TGMTokenInformation":{"properties":{"name":{"anyOf":[{"type":"string"}],"title":"Name","description":"Token name"},"symbol":{"anyOf":[{"type":"string"}],"title":"Symbol","description":"Token symbol"},"contract_address":{"anyOf":[{"type":"string"}],"title":"Contract Address","description":"Token contract address"},"logo":{"anyOf":[{"type":"string"}],"title":"Logo","description":"Token logo URL"},"token_details":{"anyOf":[{"$ref":"#/components/schemas/TokenDetails"}],"description":"Token details including deployment, social links, and market metrics"},"spot_metrics":{"anyOf":[{"$ref":"#/components/schemas/SpotMetrics"}],"description":"Spot trading metrics for the token"}},"type":"object","title":"TGMTokenInformation","description":"Token information including basic details, token details, and spot metrics."},"TokenDetails":{"properties":{"token_deployment_date":{"anyOf":[{"type":"string"}],"title":"Token Deployment Date","description":"Token deployment date in ISO format"},"website":{"anyOf":[{"type":"string"}],"title":"Website","description":"Token website URL"},"x":{"anyOf":[{"type":"string"}],"title":"X","description":"X (Twitter) profile URL"},"telegram":{"anyOf":[{"type":"string"}],"title":"Telegram","description":"Telegram channel URL"},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Market capitalization in USD"},"fdv_usd":{"anyOf":[{"type":"number"}],"title":"Fdv Usd","description":"Fully diluted valuation in USD"},"circulating_supply":{"anyOf":[{"type":"number"}],"title":"Circulating Supply","description":"Circulating supply of the token"},"total_supply":{"anyOf":[{"type":"number"}],"title":"Total Supply","description":"Total supply of the token"}},"type":"object","title":"TokenDetails","description":"Token details including deployment, social links, and market metrics."},"SpotMetrics":{"properties":{"volume_total_usd":{"anyOf":[{"type":"number"}],"title":"Volume Total Usd","description":"Total trading volume in USD"},"buy_volume_usd":{"anyOf":[{"type":"number"}],"title":"Buy Volume Usd","description":"Total buy volume in USD"},"sell_volume_usd":{"anyOf":[{"type":"number"}],"title":"Sell Volume Usd","description":"Total sell volume in USD"},"total_buys":{"anyOf":[{"type":"integer"}],"title":"Total Buys","description":"Total number of buy transactions"},"total_sells":{"anyOf":[{"type":"integer"}],"title":"Total Sells","description":"Total number of sell transactions"},"unique_buyers":{"anyOf":[{"type":"integer"}],"title":"Unique Buyers","description":"Number of unique buyers"},"unique_sellers":{"anyOf":[{"type":"integer"}],"title":"Unique Sellers","description":"Number of unique sellers"},"liquidity_usd":{"anyOf":[{"type":"number"}],"title":"Liquidity Usd","description":"Liquidity in USD"},"total_holders":{"anyOf":[{"type":"integer"}],"title":"Total Holders","description":"Total number of token holders"}},"type":"object","title":"SpotMetrics","description":"Spot trading metrics for the token."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/token-information":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) token information data","description":"Get comprehensive token information including basic details (name, symbol, contract address, logo), token details (deployment date, social links, market metrics like market cap and FDV), and spot trading metrics (volume, buys/sells, unique traders, liquidity, holders).\n\nThis endpoint provides a complete overview of a token's metadata, market position, and trading activity for a specific date range.","operationId":"get_tgm_token_information_api_v1_tgm_token_information_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMTokenInformationRequest"}}},"required":true},"responses":{"200":{"description":"TGM token information data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMTokenInformationResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Nansen Indicators ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Indicator scores are recomputed by a **daily batch**, so new activity is reflected at the next daily run rather than in real time. ## Get Nansen Score Indicators > Get risk and reward indicators for a specific token.\ > \ > Returns two groups of indicators:\ > \- \*\*risk\_indicators\*\*: Metrics for assessing token risk (btc-reflexivity, liquidity-risk, concentration-risk, token-supply-inflation)\ > \- \*\*reward\_indicators\*\*: Metrics for assessing alpha potential (chain-tvl, trading-range, price-momentum, chain-fees, protocol-fees, cex-flows, funding-rate)\ > \ > Each indicator includes:\ > \- \*\*score\*\*: Summary assessment ('low'/'medium'/'high' for risk, 'bearish'/'neutral'/'bullish' for reward)\ > \- \*\*signal\*\*: Raw metric value\ > \- \*\*signal\_percentile\*\*: Percentile rank (0-100) vs tokens in same market cap group\ > \- \*\*last\_trigger\_on\*\*: When the indicator last changed state ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMIndicatorsRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TGMChain","description":"Blockchain chain"},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"}},"additionalProperties":false,"type":"object","required":["chain","token_address"],"title":"TGMIndicatorsRequest","description":"Request model for TGM Indicators endpoint.\n\nThis endpoint provides risk and reward indicators for a specific token."},"TGMChain":{"type":"string","enum":["arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","hyperliquid","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"TGMChain","description":"Chains supported in TGM (Token God Mode) endpoints."},"TGMIndicatorsResponse":{"properties":{"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"chain":{"type":"string","title":"Chain","description":"Blockchain chain"},"token_info":{"$ref":"#/components/schemas/TGMIndicatorTokenInfo","description":"Token metadata including market cap information"},"risk_indicators":{"items":{"$ref":"#/components/schemas/TGMIndicator"},"type":"array","title":"Risk Indicators","description":"Risk assessment indicators (btc-reflexivity, liquidity-risk, concentration-risk, token-supply-inflation)"},"reward_indicators":{"items":{"$ref":"#/components/schemas/TGMIndicator"},"type":"array","title":"Reward Indicators","description":"Reward/alpha potential indicators (chain-tvl, trading-range, price-momentum, chain-fees, protocol-fees, cex-flows, funding-rate)"}},"type":"object","required":["token_address","chain","token_info","risk_indicators","reward_indicators"],"title":"TGMIndicatorsResponse","description":"Response model for TGM Indicators endpoint.\n\nContains risk and reward indicators grouped separately."},"TGMIndicatorTokenInfo":{"properties":{"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Market capitalization in USD"},"market_cap_group":{"anyOf":[{"type":"string"}],"title":"Market Cap Group","description":"Market cap classification group"},"is_stablecoin":{"anyOf":[{"type":"boolean"}],"title":"Is Stablecoin","description":"Flag indicating if token is a stablecoin"}},"type":"object","title":"TGMIndicatorTokenInfo","description":"Token metadata from indicator data."},"TGMIndicator":{"properties":{"indicator_type":{"type":"string","title":"Indicator Type","description":"The type of indicator"},"score":{"anyOf":[{"type":"string"}],"title":"Score","description":"Summary score (risk: low/medium/high, reward: bearish/neutral/bullish)"},"signal":{"anyOf":[{"type":"number"}],"title":"Signal","description":"The raw signal value for the indicator"},"signal_percentile":{"anyOf":[{"type":"number"}],"title":"Signal Percentile","description":"Percentile of the signal against tokens in the same market cap group (0-100)"},"last_trigger_on":{"anyOf":[{"type":"string"}],"title":"Last Trigger On","description":"Date when the indicator last changed state (YYYY-MM-DD)"}},"type":"object","required":["indicator_type"],"title":"TGMIndicator","description":"Individual indicator record."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/indicators":{"post":{"tags":["Token God Mode"],"summary":"Get Nansen Score Indicators","description":"Get risk and reward indicators for a specific token.\n\nReturns two groups of indicators:\n- **risk_indicators**: Metrics for assessing token risk (btc-reflexivity, liquidity-risk, concentration-risk, token-supply-inflation)\n- **reward_indicators**: Metrics for assessing alpha potential (chain-tvl, trading-range, price-momentum, chain-fees, protocol-fees, cex-flows, funding-rate)\n\nEach indicator includes:\n- **score**: Summary assessment ('low'/'medium'/'high' for risk, 'bearish'/'neutral'/'bullish' for reward)\n- **signal**: Raw metric value\n- **signal_percentile**: Percentile rank (0-100) vs tokens in same market cap group\n- **last_trigger_on**: When the indicator last changed state","operationId":"get_tgm_indicators_api_v1_tgm_indicators_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMIndicatorsRequest"}}},"required":true},"responses":{"200":{"description":"Nansen score indicators data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMIndicatorsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Price OHLCV ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * **Latency:** the most recent candle is the current, still-open interval and keeps updating until it closes. Prices come from a median price feed that refreshes roughly every 5 minutes, so `5m` and larger candles are at most \~5 minutes behind; the `1m` timeframe is built directly from on-chain swaps and is trade-fresh over a short recent window. Hyperliquid tokens are served live from Hyperliquid's own feed. * **History:** each token's history goes back to the first price Nansen recorded for it, so the start date varies by token. * **Batch tokens with no data:** in batch requests, tokens that have no candles for the requested chain, timeframe, and date range are omitted from `tokens`. They are not returned as empty `data: []` placeholders and do not cause an error. To identify omitted tokens, compare your submitted addresses with the `tokens[].token_address` values in the response. This omission is distinct from truncation; a token can be omitted with no data while `truncated` remains `false`. * **Truncation:** single-token requests return at most 50,000 candles per token, ordered oldest first; if the requested range exceeds that cap, the most recent candles are dropped first. Batch requests return at most 50,000 candles shared across all requested tokens, ordered oldest first across the batch. Check the `truncated` boolean; when it is `true`, inspect `truncation_note` for details. To retrieve complete data, narrow or split the date range. For batch requests, reduce the token count or query tokens individually when complete per-token coverage is required. * **Truncation on Hyperliquid:** Hyperliquid tokens come from Hyperliquid's own feed, which caps each token's response at roughly 5,000 candles — well below the 50,000 above — and drops the **oldest** candles rather than the most recent, so a range wider than the cap comes back starting later than requested. The same `truncated` / `truncation_note` fields flag it; in a batch request `truncated` is `true` when at least one token was cut short. Split the request into shorter ranges to walk the full history. ## Retrieve token OHLCV candle data > Get unified OHLCV (Open, High, Low, Close, Volume) data for tokens across supported chains.\ > \ > \*\*Low timeframes\*\* (sub-hourly + 4h): \`1m\`, \`5m\`, \`15m\`, \`30m\`, \`1h\`, \`4h\`\ > \*\*High timeframes\*\* (multi-day): \`1d\`, \`1w\`, \`1M\`\ > \ > Returns OHLCV candle data including:\ > \- \*\*Price data\*\*: open, high, low, close prices\ > \- \*\*Volume data\*\*: trading volume in token units and USD\ > \- \*\*Market cap data\*\*: market capitalization at each time point\ > \ > Date range defaults to the last 30 days if not specified.\ > \ > \*\*Sub-daily resolution notes\*\* (\`1m\`, \`5m\`, \`15m\`, \`30m\`, \`1h\`, \`4h\`)\ > \ > \- \*\*Open price\*\*: Derived from the previous completed candle's close (carry-forward).\ > It can therefore fall outside the current candle's \`low\`–\`high\` range when price\ > moves sharply at an interval boundary. The very first candle has \`open: null\`.\ > \- \*\*Gaps\*\* (\`1m\` only): Only intervals that contain at least one qualifying on-chain\ > trade emit a candle. Minutes with no activity produce no row — the candle array may\ > be sparse. This is expected behavior and is independent of the \`truncated\` flag,\ > which reports only the 50,000-candle server cap.\ > \- \*\*Token-unit volume\*\* (\`1m\` only): The \`volume\` field is null at \`1m\` resolution.\ > Use \`volume\_usd\` for volume data at this timeframe.\ > \- \*\*Time range boundary\*\* (\`1m\` only): The \`to\` parameter is exclusive — the candle\ > starting at exactly \`to\` is not included (\`\[from, to)\` semantics). All other\ > timeframes (\`5m\` and above) use an inclusive upper bound (\`\[from, to]\`). ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TokenOHLCVRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TGMOHLCVChain","description":"Blockchain chain"},"token_address":{"anyOf":[{"type":"string"}],"title":"Token Address","description":"Token contract address"},"token_addresses":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Token Addresses","description":"Array of token contract addresses for batch queries (max 10, or max 5 for Hyperliquid, mutually exclusive with token_address)"},"date_range":{"anyOf":[{"$ref":"#/components/schemas/TokenOHLCVDateRange"}],"description":"DEPRECATED: Use 'date' instead. Date range with start/end fields.","deprecated":true},"date":{"anyOf":[{"$ref":"#/components/schemas/DateRange"}],"description":"Date range for the data (defaults to last 30 days if not specified)"},"timeframe":{"$ref":"#/components/schemas/ResolutionEnum","description":"Time resolution for OHLCV data"}},"additionalProperties":false,"type":"object","required":["chain","timeframe"],"title":"TokenOHLCVRequest","description":"Request model for Token OHLCV endpoint.\n\nThis endpoint provides unified OHLCV (Open, High, Low, Close, Volume) data\nfor tokens across supported chains with different time resolutions."},"TGMOHLCVChain":{"type":"string","enum":["algorand","aptos","arbitrum","arc","avalanche","base","bitcoin","bitlayer","bnb","chiliz","ethereum","gravity","hyperevm","hyperliquid","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","stacks","starknet","stellar","sui","ton","tron","viction"],"title":"TGMOHLCVChain","description":"Chains supported for TGM OHLCV endpoint (includes Bitcoin)."},"TokenOHLCVDateRange":{"properties":{"start":{"type":"string","title":"Start","description":"Start date and time (ISO format)"},"end":{"type":"string","title":"End","description":"End date and time (ISO format)"}},"type":"object","required":["start","end"],"title":"TokenOHLCVDateRange","description":"DEPRECATED: Use 'date' field with standard DateRange instead."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"ResolutionEnum":{"type":"string","enum":["1m","5m","15m","30m","1h","4h","1d","1w","1M"],"title":"ResolutionEnum","description":"Supported OHLCV resolution values."},"TokenOHLCVResponse":{"properties":{"chain":{"type":"string","title":"Chain","description":"Blockchain chain"},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"timeframe":{"type":"string","title":"Timeframe","description":"Time resolution used"},"data":{"items":{"$ref":"#/components/schemas/OHLCVCandle"},"type":"array","title":"Data","description":"OHLCV candle data points, ordered by interval_start"},"truncated":{"type":"boolean","title":"Truncated","description":"True if the result reached the candle cap and some candles were omitted. On most chains the cap is 50,000 candles for this token and the omitted candles are the most recent ones, since results are ordered by interval_start ascending. Hyperliquid tokens are served from Hyperliquid's own feed, which applies a smaller per-response cap of roughly 5,000 candles and omits the oldest candles instead, so the returned data starts later than requested. Narrow the date range for complete coverage.","default":false},"truncation_note":{"anyOf":[{"type":"string"}],"title":"Truncation Note","description":"Human-readable detail when 'truncated' is true, naming the cap that was reached and which end of the requested range was omitted."}},"type":"object","required":["chain","token_address","timeframe","data"],"title":"TokenOHLCVResponse","description":"Response model for Token OHLCV endpoint (single token).\n\nContains the requested OHLCV data with metadata about the request parameters."},"OHLCVCandle":{"properties":{"interval_start":{"type":"string","title":"Interval Start","description":"Start time of the candle interval (ISO datetime string)"},"open":{"anyOf":[{"type":"number"}],"title":"Open","description":"Opening price. For sub-daily timeframes (`1m`, `5m`, `15m`, `30m`, `1h`, `4h`) this is the previous completed candle's close (carry-forward), so it can fall outside the current candle's `low`–`high` range when price gaps at the interval boundary. Null on the very first (inception) candle, when no prior close exists."},"high":{"anyOf":[{"type":"number"}],"title":"High","description":"Highest price in the interval"},"low":{"anyOf":[{"type":"number"}],"title":"Low","description":"Lowest price in the interval"},"close":{"anyOf":[{"type":"number"}],"title":"Close","description":"Closing price"},"volume":{"anyOf":[{"type":"number"}],"title":"Volume","description":"Trading volume in token units. Null for `1m` resolution — token-unit volume is not available at that resolution; use `volume_usd` instead."},"volume_usd":{"anyOf":[{"type":"number"}],"title":"Volume Usd","description":"Trading volume in USD"},"market_cap":{"$ref":"#/components/schemas/MarketCapData","description":"Market capitalization data for the candle"}},"type":"object","required":["interval_start","market_cap"],"title":"OHLCVCandle","description":"Individual OHLCV candle data point."},"MarketCapData":{"properties":{"open":{"anyOf":[{"type":"number"}],"title":"Open","description":"Market cap at candle open"},"high":{"anyOf":[{"type":"number"}],"title":"High","description":"Highest market cap in the candle"},"low":{"anyOf":[{"type":"number"}],"title":"Low","description":"Lowest market cap in the candle"},"close":{"anyOf":[{"type":"number"}],"title":"Close","description":"Market cap at candle close"}},"type":"object","title":"MarketCapData","description":"Market capitalization data for OHLCV candles."},"TokenOHLCVBatchResponse":{"properties":{"chain":{"type":"string","title":"Chain","description":"Blockchain chain"},"timeframe":{"type":"string","title":"Timeframe","description":"Time resolution used"},"tokens":{"items":{"$ref":"#/components/schemas/TokenOHLCVTokenData"},"type":"array","title":"Tokens","description":"OHLCV data per token, ordered by token address. Only tokens with available data are included. A requested token with no data is omitted from this array, not returned with an empty data list. Compare the length of this array against the number of token addresses in your request to detect omitted tokens."},"truncated":{"type":"boolean","title":"Truncated","description":"True if the result reached the candle cap and some candles were omitted. On most chains the cap is 50,000 candles shared across all requested tokens: candles are collected in interval_start ascending, then token_address ascending order, so the most recent candles across all tokens are omitted first and a single token with dense data may consume a disproportionate share of the cap. Hyperliquid tokens are served from Hyperliquid's own feed, which caps each token separately at roughly 5,000 candles and omits that token's oldest candles instead; the flag is true when at least one token was cut short. To ensure complete coverage, narrow the date range or query tokens individually.","default":false},"truncation_note":{"anyOf":[{"type":"string"}],"title":"Truncation Note","description":"Human-readable detail when 'truncated' is true, naming the cap that was reached and which end of the requested range was omitted."}},"type":"object","required":["chain","timeframe","tokens"],"title":"TokenOHLCVBatchResponse","description":"Response model for batch Token OHLCV requests (multiple tokens).\n\nContains OHLCV data grouped by token address."},"TokenOHLCVTokenData":{"properties":{"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"data":{"items":{"$ref":"#/components/schemas/OHLCVCandle"},"type":"array","title":"Data","description":"OHLCV candle data points, ordered by interval_start"}},"type":"object","required":["token_address","data"],"title":"TokenOHLCVTokenData","description":"OHLCV data for a single token within a batch response."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/token-ohlcv":{"post":{"tags":["Token God Mode"],"summary":"Retrieve token OHLCV candle data","description":"Get unified OHLCV (Open, High, Low, Close, Volume) data for tokens across supported chains.\n\n**Low timeframes** (sub-hourly + 4h): `1m`, `5m`, `15m`, `30m`, `1h`, `4h`\n**High timeframes** (multi-day): `1d`, `1w`, `1M`\n\nReturns OHLCV candle data including:\n- **Price data**: open, high, low, close prices\n- **Volume data**: trading volume in token units and USD\n- **Market cap data**: market capitalization at each time point\n\nDate range defaults to the last 30 days if not specified.\n\n**Sub-daily resolution notes** (`1m`, `5m`, `15m`, `30m`, `1h`, `4h`)\n\n- **Open price**: Derived from the previous completed candle's close (carry-forward).\n It can therefore fall outside the current candle's `low`–`high` range when price\n moves sharply at an interval boundary. The very first candle has `open: null`.\n- **Gaps** (`1m` only): Only intervals that contain at least one qualifying on-chain\n trade emit a candle. Minutes with no activity produce no row — the candle array may\n be sparse. This is expected behavior and is independent of the `truncated` flag,\n which reports only the 50,000-candle server cap.\n- **Token-unit volume** (`1m` only): The `volume` field is null at `1m` resolution.\n Use `volume_usd` for volume data at this timeframe.\n- **Time range boundary** (`1m` only): The `to` parameter is exclusive — the candle\n starting at exactly `to` is not included (`[from, to)` semantics). All other\n timeframes (`5m` and above) use an inclusive upper bound (`[from, to]`).","operationId":"get_token_ohlcv_api_v1_tgm_token_ohlcv_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenOHLCVRequest"}}},"required":true},"responses":{"200":{"description":"Token OHLCV data","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TokenOHLCVResponse"},{"$ref":"#/components/schemas/TokenOHLCVBatchResponse"}],"title":"Response Get Token Ohlcv Api V1 Tgm Token Ohlcv Post"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Token Screener Set `filters.include_native_tokens` to `true` to include native, wrapped-native, LST, and LRT assets. The default is `false`. See [Native Tokens](/reference/native-tokens) for representation and coverage limitations. {% hint style="info" %} **Data Retention Limits** This endpoint only supports recent data: * Minute Granularity: Last 130 minutes * Hourly Granularity: Last 50 hours * Daily Granularity: Last 50 days **Historical Analysis Not Supported:** * `to_date` must be within 5 minutes of current time * Historical snapshots (e.g., "show me January 2024") are not available {% endhint %} ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * A live, point-in-time screener: results reflect data as of request time rather than a historical window; no response cache. ## Retrieve token screener data > Discover and screen tokens across multiple blockchains with advanced filtering capabilities. This endpoint helps identify trending tokens, new launches, and smart money movements by combining metrics like volume, liquidity, market cap, and trading activity.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*Which tokens are experiencing significant smart money activity across different chains?\*\*\ > 2\. \*\*How do market metrics (price, volume, liquidity) correlate with holder behavior and smart money movements?\*\*\ > 3\. \*\*What tokens show strong fundamentals in terms of holder distribution and trading patterns?\*\*\ > 4\. \*\*Which emerging tokens are attracting fresh wallet inflows while maintaining healthy smart money participation?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TokenScreenerRequest":{"properties":{"chains":{"items":{"$ref":"#/components/schemas/TokenScreenerChain"},"type":"array","maxItems":5,"minItems":1,"title":"Chains","description":"List of blockchain chains to filter by"},"timeframe":{"anyOf":[{"$ref":"#/components/schemas/TokenScreenerTimeframe"}],"description":"**Required** (unless using deprecated 'date' parameter).\n\nTime window for token screening data.\n\nAvailable timeframes and their data characteristics:\n- 5m: Last 5 minutes (minute-level granularity, 2-hour retention)\n- 10m: Last 10 minutes (minute-level granularity, 2-hour retention)\n- 1h: Last 1 hour (minute-level granularity, 2-hour retention)\n- 6h: Last 6 hours (hourly granularity, 2-day retention)\n- 24h: Last 24 hours (hourly granularity, 2-day retention)\n- 7d: Last 7 days (daily granularity, 2-month retention)\n- 30d: Last 30 days (daily granularity, 2-month retention)\n\nCannot be used together with 'date'."},"date":{"anyOf":[{"$ref":"#/components/schemas/DateRange"}],"description":"**DEPRECATED**: Use 'timeframe' instead. It offers better reliability and performance.\n\nRequired only if 'timeframe' is not provided.\n\nCustom date range for the token screener. The granularity is automatically determined from the date range:\n- ≤ 1 hour: minute-level data (limited to last 2 hours)\n- > 1 hour to 1 day: hourly data (limited to last 2 days)\n- > 1 day: daily data (limited to last 2 months)\n\nCannot be used together with 'timeframe'.","deprecated":true},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TokenScreenerFilters"}],"description":"Additional filters to apply"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TokenScreenerSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"buy_volume\", \"direction\": \"DESC\"}] - Sort by buy volume descending\n- [{\"field\": \"price_change\", \"direction\": \"DESC\"}] - Sort by price change descending"}},"additionalProperties":false,"type":"object","required":["chains"],"title":"TokenScreenerRequest","description":"Request model for Token Screener endpoint.\n\nEither 'timeframe' (recommended) or 'date' (deprecated) must be provided."},"TokenScreenerChain":{"type":"string","enum":["arbitrum","arc","avalanche","base","bitcoin","bnb","citrea","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"TokenScreenerChain","description":"Chains supported for Token Screener endpoint."},"TokenScreenerTimeframe":{"type":"string","enum":["5m","10m","1h","6h","24h","7d","30d"],"title":"TokenScreenerTimeframe","description":"Token screener timeframe options.\n\nDefines the time window for token screening data.\nEach timeframe corresponds to different data granularity and retention periods.\nMatches the timeframe options in the Nansen token-screener widget."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TokenScreenerFilters":{"properties":{"token_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Address","description":"Token address or symbol filter"},"token_symbol":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Symbol","description":"Token symbol filter"},"only_smart_money":{"anyOf":[{"type":"boolean"}],"title":"Only Smart Money","description":"Deprecated: Use 'trader_type' instead. Whether to only include smart money tokens","deprecated":true},"trader_type":{"anyOf":[{"$ref":"#/components/schemas/TraderType"}],"description":"Filter by trader type. Overrides only_smart_money when provided. Supported values: `all`, `sm`, `whale`, `public_figure`, `trending`."},"sectors":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Sectors","description":"Token sectors to include, as bare sector names (e.g. DeFi, Gaming). Note: this differs from the perp screener's sectors_filter, which uses category:subcategory values."},"exclude_sectors":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Exclude Sectors","description":"Token sectors to exclude, as bare sector names."},"token_age_days":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token age range filter in days"},"market_cap_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Market cap range filter"},"liquidity":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Liquidity range filter"},"price_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Current price range filter in USD"},"price_change":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Price change percentage range filter"},"fdv":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Fully Diluted Valuation range filter"},"fdv_mc_ratio":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"FDV to Market Cap ratio range filter"},"nof_buyers":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of unique buyers range filter"},"nof_traders":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of unique traders range filter"},"nof_sellers":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of unique sellers range filter"},"nof_buys":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of buy transactions range filter"},"nof_sells":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of sell transactions range filter"},"buy_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Buy volume range filter in USD"},"sell_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Sell volume range filter in USD"},"volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total trading volume range filter in USD"},"netflow":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Net flow range filter in USD"},"inflow_fdv_ratio":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Inflow to FDV ratio range filter"},"outflow_fdv_ratio":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Outflow to FDV ratio range filter"},"include_stablecoins":{"type":"boolean","title":"Include Stablecoins","description":"Whether to include stablecoins in token screener results. Default true preserves current behavior. Set to false to exclude USDC, USDT, DAI, and other major stablecoins.","default":true},"include_native_tokens":{"type":"boolean","title":"Include Native Tokens","description":"Whether to include native tokens (e.g. ETH, SOL) and wrapped-native / LST / LRT derivatives in results. Default false preserves current behavior.","default":false},"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Include smart money labels"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels"}},"additionalProperties":false,"type":"object","title":"TokenScreenerFilters","description":"Filters for token screener endpoints.\n\nThese filters control which tokens are included in the screening\nresults based on various criteria."},"TraderType":{"type":"string","enum":["all","sm","whale","public_figure","trending","consistent_perps_winner","high_winrate_hl_perps_trader","predicted_winner"],"title":"TraderType","description":"Trader type filter for token screener."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Filter by smart money label type."},"TokenScreenerSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TokenScreenerSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TokenScreenerSortOrder"},"TokenScreenerSortField":{"type":"string","enum":["chain","token_address","token_symbol","market_cap_usd","volume","liquidity","nof_traders","nof_buyers","nof_sellers","nof_buys","nof_sells","price_change","price_usd","netflow","buy_volume","sell_volume","fdv","fdv_mc_ratio","inflow_fdv_ratio","outflow_fdv_ratio","token_age_days"],"title":"TokenScreenerSortField","description":"Enum for sortable fields in token screener."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TokenScreenerResponse":{"properties":{"data":{"items":{"anyOf":[{"$ref":"#/components/schemas/TokenScreenerDataDefault"},{"$ref":"#/components/schemas/TokenScreenerDataSmartMoneyDefault"},{"$ref":"#/components/schemas/TokenScreenerDataNonDefault"}]},"type":"array","title":"Data","description":"List of token screening results"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TokenScreenerResponse","description":"Response model for token screener endpoint."},"TokenScreenerDataDefault":{"properties":{"chain":{"type":"string","title":"Chain","description":"The blockchain network on which the token is deployed."},"token_address":{"type":"string","title":"Token Address","description":"Address of token"},"token_symbol":{"type":"string","title":"Token Symbol","description":"The symbol of the token."},"token_age_days":{"anyOf":[{"type":"number"}],"title":"Token Age Days","description":"Number of days since token deployment."},"token_age_hours":{"anyOf":[{"type":"number"}],"title":"Token Age Hours","description":"Number of hours since token deployment."},"token_deployment_date":{"anyOf":[{"type":"string"}],"title":"Token Deployment Date","description":"ISO 8601 timestamp of token deployment."},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Market capitalization in USD."},"liquidity":{"anyOf":[{"type":"number"}],"title":"Liquidity","description":"Total on-chain liquidity in USD."},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Price of the token"},"price_change":{"anyOf":[{"type":"number"}],"title":"Price Change","description":"Price change percentage from the previous period."},"fdv":{"anyOf":[{"type":"number"}],"title":"Fdv","description":"Fully Diluted Valuation in USD."},"fdv_mc_ratio":{"anyOf":[{"type":"number"}],"title":"Fdv Mc Ratio","description":"Ratio of Fully Diluted Valuation to Market Cap."},"buy_volume":{"anyOf":[{"type":"number"}],"title":"Buy Volume","description":"Total buy volume in USD."},"inflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Inflow Fdv Ratio","description":"Ratio of inflow to Fully Diluted Valuation."},"outflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Outflow Fdv Ratio","description":"Ratio of outflow to Fully Diluted Valuation."},"sell_volume":{"anyOf":[{"type":"number"}],"title":"Sell Volume","description":"Total sell volume in USD."},"volume":{"anyOf":[{"type":"number"}],"title":"Volume","description":"Total trading volume in USD."},"netflow":{"anyOf":[{"type":"number"}],"title":"Netflow","description":"Net flow (buy_volume - sell_volume) in USD."}},"type":"object","required":["chain","token_address","token_symbol"],"title":"TokenScreenerDataDefault","description":"Data model for token screener results with non-default query (excludes trader-related columns)."},"TokenScreenerDataSmartMoneyDefault":{"properties":{"chain":{"type":"string","title":"Chain","description":"The blockchain network on which the token is deployed."},"token_address":{"type":"string","title":"Token Address","description":"Address of token"},"token_symbol":{"type":"string","title":"Token Symbol","description":"The symbol of the token."},"token_age_days":{"anyOf":[{"type":"number"}],"title":"Token Age Days","description":"Number of days since token deployment."},"token_age_hours":{"anyOf":[{"type":"number"}],"title":"Token Age Hours","description":"Number of hours since token deployment."},"token_deployment_date":{"anyOf":[{"type":"string"}],"title":"Token Deployment Date","description":"ISO 8601 timestamp of token deployment."},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Market capitalization in USD."},"liquidity":{"anyOf":[{"type":"number"}],"title":"Liquidity","description":"Total on-chain liquidity in USD."},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Price of the token"},"price_change":{"anyOf":[{"type":"number"}],"title":"Price Change","description":"Price change percentage from the previous period."},"fdv":{"anyOf":[{"type":"number"}],"title":"Fdv","description":"Fully Diluted Valuation in USD."},"fdv_mc_ratio":{"anyOf":[{"type":"number"}],"title":"Fdv Mc Ratio","description":"Ratio of Fully Diluted Valuation to Market Cap."},"nof_traders":{"anyOf":[{"type":"integer"}],"title":"Nof Traders","description":"Total number of unique traders."},"buy_volume":{"anyOf":[{"type":"number"}],"title":"Buy Volume","description":"Total buy volume in USD."},"inflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Inflow Fdv Ratio","description":"Ratio of inflow to Fully Diluted Valuation."},"outflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Outflow Fdv Ratio","description":"Ratio of outflow to Fully Diluted Valuation."},"sell_volume":{"anyOf":[{"type":"number"}],"title":"Sell Volume","description":"Total sell volume in USD."},"volume":{"anyOf":[{"type":"number"}],"title":"Volume","description":"Total trading volume in USD."},"netflow":{"anyOf":[{"type":"number"}],"title":"Netflow","description":"Net flow (buy_volume - sell_volume) in USD."}},"type":"object","required":["chain","token_address","token_symbol"],"title":"TokenScreenerDataSmartMoneyDefault","description":"Data model for smart money token screener with default query.\n\nIncludes nof_traders but excludes other trader-related columns\n(nof_buyers, nof_sellers, nof_buys, nof_sells)."},"TokenScreenerDataNonDefault":{"properties":{"chain":{"type":"string","title":"Chain","description":"The blockchain network on which the token is deployed."},"token_address":{"type":"string","title":"Token Address","description":"Address of token"},"token_symbol":{"type":"string","title":"Token Symbol","description":"The symbol of the token."},"token_age_days":{"anyOf":[{"type":"number"}],"title":"Token Age Days","description":"Number of days since token deployment."},"token_age_hours":{"anyOf":[{"type":"number"}],"title":"Token Age Hours","description":"Number of hours since token deployment."},"token_deployment_date":{"anyOf":[{"type":"string"}],"title":"Token Deployment Date","description":"ISO 8601 timestamp of token deployment."},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Market capitalization in USD."},"liquidity":{"anyOf":[{"type":"number"}],"title":"Liquidity","description":"Total on-chain liquidity in USD."},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Price of the token"},"price_change":{"anyOf":[{"type":"number"}],"title":"Price Change","description":"Price change percentage from the previous period."},"fdv":{"anyOf":[{"type":"number"}],"title":"Fdv","description":"Fully Diluted Valuation in USD."},"fdv_mc_ratio":{"anyOf":[{"type":"number"}],"title":"Fdv Mc Ratio","description":"Ratio of Fully Diluted Valuation to Market Cap."},"nof_buyers":{"anyOf":[{"type":"integer"}],"title":"Nof Buyers","description":"Number of unique buyers."},"nof_traders":{"anyOf":[{"type":"integer"}],"title":"Nof Traders","description":"Total number of unique traders."},"nof_sellers":{"anyOf":[{"type":"integer"}],"title":"Nof Sellers","description":"Number of unique sellers."},"nof_buys":{"anyOf":[{"type":"integer"}],"title":"Nof Buys","description":"Total number of buy transactions."},"nof_sells":{"anyOf":[{"type":"integer"}],"title":"Nof Sells","description":"Total number of sell transactions."},"buy_volume":{"anyOf":[{"type":"number"}],"title":"Buy Volume","description":"Total buy volume in USD."},"inflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Inflow Fdv Ratio","description":"Ratio of inflow to Fully Diluted Valuation."},"outflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Outflow Fdv Ratio","description":"Ratio of outflow to Fully Diluted Valuation."},"sell_volume":{"anyOf":[{"type":"number"}],"title":"Sell Volume","description":"Total sell volume in USD."},"volume":{"anyOf":[{"type":"number"}],"title":"Volume","description":"Total trading volume in USD."},"netflow":{"anyOf":[{"type":"number"}],"title":"Netflow","description":"Net flow (buy_volume - sell_volume) in USD."}},"type":"object","required":["chain","token_address","token_symbol"],"title":"TokenScreenerDataNonDefault","description":"Data model for token screener results with non-default query (includes all columns)."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/token-screener":{"post":{"tags":["Token Screener"],"summary":"Retrieve token screener data","description":"Discover and screen tokens across multiple blockchains with advanced filtering capabilities. This endpoint helps identify trending tokens, new launches, and smart money movements by combining metrics like volume, liquidity, market cap, and trading activity.\n\n**What it helps to answer:**\n\n1. **Which tokens are experiencing significant smart money activity across different chains?**\n2. **How do market metrics (price, volume, liquidity) correlate with holder behavior and smart money movements?**\n3. **What tokens show strong fundamentals in terms of holder distribution and trading patterns?**\n4. **Which emerging tokens are attracting fresh wallet inflows while maintaining healthy smart money participation?**","operationId":"get_token_screener_api_v1_token_screener_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenScreenerRequest"}}},"required":true},"responses":{"200":{"description":"Token screening data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenScreenerResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Flow Intelligence {% hint style="info" %} This endpoint accepts supported native-token placeholders through a specialized query path, but results can be thinner than for contract tokens. See [Native Tokens](/reference/native-tokens). {% endhint %} ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Recent (\~last 24h) data is live; older data comes from an hourly batch and can lag up to about an hour. Responses are cached 10–30 minutes depending on timeframe. ## Get "Token God Mode" (TGM) flow intelligence data > This endpoint provides comprehensive flow intelligence analytics, including inflows, outflows, and net flows for a specific token, broken down by various holder segments (Exchanges, Smart Money, Public Figures, Whales) with time-based statistics and trends. It can be used for identifying accumulation/distribution patterns across different holder segments. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMFlowIntelligenceRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TGMFlowIntelligenceChain","description":"Blockchain chain"},"token_address":{"type":"string","title":"Token Address","description":"Token address"},"timeframe":{"$ref":"#/components/schemas/TGMFlowIntelligenceTimeframe","description":"Time window for the flow intelligence data","default":"1d"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMFlowIntelligenceFilters"}],"description":"Additional filters to apply to the query."}},"additionalProperties":false,"type":"object","required":["chain","token_address"],"title":"TGMFlowIntelligenceRequest","description":"Request model for TGM flow-intelligence endpoint.\n\nThis endpoint provides detailed token flow intelligence for analyzing token movements\nacross different chains. It helps track and categorize token transfers, identifying\npatterns such as exchange deposits, withdrawals, and transfers between different\ntypes of wallets."},"TGMFlowIntelligenceChain":{"type":"string","enum":["arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","injective","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"TGMFlowIntelligenceChain","description":"Chains supported for the TGM flow intelligence endpoint."},"TGMFlowIntelligenceTimeframe":{"type":"string","enum":["5m","1h","6h","12h","1d","7d"],"title":"TGMFlowIntelligenceTimeframe","description":"TGM flow intelligence timeframe options."},"TGMFlowIntelligenceFilters":{"properties":{"public_figure_net_flow_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Public figure net flow range filter in USD"},"public_figure_avg_flow_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Public figure average flow range filter in USD"},"public_figure_wallet_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Public figure wallet count range filter"},"top_pnl_net_flow_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Top PnL net flow range filter in USD"},"top_pnl_avg_flow_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Top PnL average flow range filter in USD"},"top_pnl_wallet_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Top PnL wallet count range filter"},"whale_net_flow_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Whale net flow range filter in USD"},"whale_avg_flow_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Whale average flow range filter in USD"},"whale_wallet_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Whale wallet count range filter"},"smart_trader_net_flow_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Smart trader net flow range filter in USD"},"smart_trader_avg_flow_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Smart trader average flow range filter in USD"},"smart_trader_wallet_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Smart trader wallet count range filter"},"exchange_net_flow_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Exchange net flow range filter in USD"},"exchange_avg_flow_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Exchange average flow range filter in USD"},"exchange_wallet_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Exchange wallet count range filter"},"fresh_wallets_net_flow_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Fresh wallets net flow range filter in USD"},"fresh_wallets_avg_flow_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Fresh wallets average flow range filter in USD"},"fresh_wallets_wallet_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Fresh wallets wallet count range filter"}},"additionalProperties":false,"type":"object","title":"TGMFlowIntelligenceFilters","description":"Filters for TGM flow intelligence endpoint.\n\nThese filters control the flow intelligence analysis data."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"TGMFlowIntelligenceResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMFlowIntelligence"},"type":"array","title":"Data","description":"List of TGM flow intelligence records"},"warnings":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Warnings","description":"Optional warnings about the query results. For example, if fresh_wallets fields are null due to timeframe constraints."}},"type":"object","required":["data"],"title":"TGMFlowIntelligenceResponse","description":"Response model for TGM flow-intelligence endpoint.\n\nContains flow intelligence data with pagination and metadata."},"TGMFlowIntelligence":{"properties":{"public_figure_net_flow_usd":{"anyOf":[{"type":"number"}],"title":"Public Figure Net Flow Usd","description":"Net flow (USD) for addresses labeled as Public Figure"},"public_figure_avg_flow_usd":{"anyOf":[{"type":"number"}],"title":"Public Figure Avg Flow Usd","description":"Geometric mean of absolute flow for Public Figure addresses"},"public_figure_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Public Figure Wallet Count","description":"Unique wallet count for Public Figure addresses"},"top_pnl_net_flow_usd":{"anyOf":[{"type":"number"}],"title":"Top Pnl Net Flow Usd","description":"Net flow (USD) for addresses labeled as Top PnL"},"top_pnl_avg_flow_usd":{"anyOf":[{"type":"number"}],"title":"Top Pnl Avg Flow Usd","description":"Geometric mean of absolute flow for Top PnL addresses"},"top_pnl_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Top Pnl Wallet Count","description":"Unique wallet count for Top PnL addresses"},"whale_net_flow_usd":{"anyOf":[{"type":"number"}],"title":"Whale Net Flow Usd","description":"Net flow (USD) for addresses labeled as Whale"},"whale_avg_flow_usd":{"anyOf":[{"type":"number"}],"title":"Whale Avg Flow Usd","description":"Geometric mean of absolute flow for Whale addresses"},"whale_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Whale Wallet Count","description":"Unique wallet count for Whale addresses"},"smart_trader_net_flow_usd":{"anyOf":[{"type":"number"}],"title":"Smart Trader Net Flow Usd","description":"Net flow (USD) for addresses labeled as Smart Trader"},"smart_trader_avg_flow_usd":{"anyOf":[{"type":"number"}],"title":"Smart Trader Avg Flow Usd","description":"Geometric mean of absolute flow for Smart Trader addresses"},"smart_trader_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Smart Trader Wallet Count","description":"Unique wallet count for Smart Trader addresses"},"exchange_net_flow_usd":{"anyOf":[{"type":"number"}],"title":"Exchange Net Flow Usd","description":"Net flow (USD) for addresses labeled as Exchange"},"exchange_avg_flow_usd":{"anyOf":[{"type":"number"}],"title":"Exchange Avg Flow Usd","description":"Geometric mean of absolute flow for Exchange addresses"},"exchange_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Exchange Wallet Count","description":"Always 0 — exchange wallet count is not tracked, even when exchange net flow is non-zero."},"fresh_wallets_net_flow_usd":{"anyOf":[{"type":"number"}],"title":"Fresh Wallets Net Flow Usd","description":"Net flow (USD) for fresh wallets. Only available for 1d and 7d timeframes."},"fresh_wallets_avg_flow_usd":{"anyOf":[{"type":"number"}],"title":"Fresh Wallets Avg Flow Usd","description":"Average absolute flow (USD) for fresh wallets. Only available for 1d and 7d timeframes."},"fresh_wallets_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Fresh Wallets Wallet Count","description":"Always 0 for the 1d and 7d timeframes (null for shorter timeframes) — fresh wallet count is not tracked separately."}},"type":"object","title":"TGMFlowIntelligence","description":"Individual TGM flow intelligence record.\n\nRepresents flow intelligence data for different wallet categories."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/flow-intelligence":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) flow intelligence data","description":"This endpoint provides comprehensive flow intelligence analytics, including inflows, outflows, and net flows for a specific token, broken down by various holder segments (Exchanges, Smart Money, Public Figures, Whales) with time-based statistics and trends. It can be used for identifying accumulation/distribution patterns across different holder segments.","operationId":"get_tgm_flow_intelligence_api_v1_tgm_flow_intelligence_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMFlowIntelligenceRequest"}}},"required":true},"responses":{"200":{"description":"TGM flow intelligence data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMFlowIntelligenceResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Holders {% hint style="info" %} To query a native asset such as ETH, use its API placeholder address with the matching chain. Native SOL is not supported by this endpoint. Non-entity, non-Bitcoin native-token queries using `label_type: "all_holders"` have reduced filtering and ordering options, and the default $1 minimum holding value is **not** applied — results include sub-$1 holders. See [Native Tokens](/reference/native-tokens). {% endhint %} {% hint style="warning" %} **Update:** The `premium_labels` parameter on this endpoint now defaults to `false`, as previously announced in the API changelog. Requests that omit the parameter return free-tier labels at the standard credit cost. Passing `premium_labels=true` returns premium labels (Smart Money, Fund, etc.), is billed at **150 credits per call**, and requires a paid plan. See the API changelog for details. {% endhint %} ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it. ## Get "Token God Mode" (TGM) holders data > Retrieve the top token holders with their current balances, historical activity, and recent balance changes. Provides insights into token distribution, smart money and fund holdings.\ > \ > \*\*Performance Optimization for Native Tokens:\*\*\ > When querying native tokens with \`label\_type: "all\_holders"\`, this endpoint uses an optimized model to prevent timeouts. This optimization has the following limitations:\ > \- \*\*Ordering\*\*: Only \`token\_amount\` field is supported\ > \- \*\*Filters\*\*: Limited to: \`token\_amount\`, \`total\_outflow\`, \`total\_inflow\`, \`address\`, \`include\_smart\_money\_labels\`, \`exclude\_smart\_money\_labels\`\ > \ > To use advanced filters and ordering on native tokens, specify a \`label\_type\` other than "all\_holders" (e.g., "smart\_money", "whale", "exchange").\ > \ > \*\*Label Tier Control (\`premium\_labels\`):\*\*\ > When omitted or set to \`false\` (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing \`premium\_labels=true\` returns premium labels (Smart Money, Fund, and other advanced labels), is billed at \*\*150 credits per call\*\*, and requires a paid plan. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMHoldersRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TGMHoldersChain","description":"Blockchain chain"},"token_address":{"type":"string","title":"Token Address","description":"Token address"},"aggregate_by_entity":{"type":"boolean","title":"Aggregate By Entity","description":"Whether to return entity data","default":false},"label_type":{"$ref":"#/components/schemas/TGMHoldersLabel","description":"Label type. You must also include the labels filter to match the label type. For example, for label type 'smart_money', you must include '30D Smart Trader', '90D Smart Trader', '180D Smart Trader', 'Fund' or 'Smart Trader' in the filters.labels.include parameter.","default":"all_holders"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMHoldersFilters"}],"description":"Additional filters to apply to the query."},"premium_labels":{"anyOf":[{"type":"boolean"}],"title":"Premium Labels","description":"Controls label tier in the response. When null/omitted or false (the default), returns free-tier labels at the standard credit cost for this endpoint. When true, returns premium labels (Smart Money, Fund, and other advanced labels), is billed at 150 credits per call, and requires a paid plan."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMHoldersSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"value_usd\", \"direction\": \"DESC\"}] - Sort by value USD descending\n- [{\"field\": \"token_amount\", \"direction\": \"ASC\"}] - Sort by token amount ascending\n- [{\"field\": \"ownership_percentage\", \"direction\": \"DESC\"}] - Sort by ownership percentage descending"}},"additionalProperties":false,"type":"object","required":["chain","token_address"],"title":"TGMHoldersRequest","description":"Request model for TGM holders endpoint.\n\nThis endpoint provides comprehensive data on token holders and their balances.\nRetrieve holders by various criteria including smart money, exchanges, public figures,\nwhales, and top holders with detailed balance information and filtering options."},"TGMHoldersChain":{"type":"string","enum":["arbitrum","arc","avalanche","base","bitcoin","bnb","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"TGMHoldersChain","description":"Chains supported for TGM holders endpoint."},"TGMHoldersLabel":{"type":"string","enum":["whale","public_figure","smart_money","all_holders","exchange"],"title":"TGMHoldersLabel","description":"TGM holders label types."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMHoldersFilters":{"properties":{"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Include smart money labels for holders"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels for holders"},"address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Address","description":"Holder address filter"},"address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Address Label","description":"Holder label filter"},"token_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token amount range filter"},"total_outflow":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total outflow range filter"},"total_inflow":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total inflow range filter"},"balance_change_24h":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"24-hour balance change range filter"},"balance_change_7d":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"7-day balance change range filter"},"balance_change_30d":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"30-day balance change range filter"},"ownership_percentage":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Ownership percentage range filter"},"value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Balance range filter in USD. Defaults to min: 1.0 to exclude dust holders. Set explicitly to override (e.g., {\"min\": 0} to include all holders). Note: This default does not apply to native tokens with 'all_holders' label."}},"additionalProperties":false,"type":"object","title":"TGMHoldersFilters","description":"Filters for TGM holders endpoint.\n\nThese filters control which holders are included in the analysis."},"LabelType":{"type":"string","enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"title":"LabelType","description":"Filter by entity label type."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"TGMHoldersSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMHoldersSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMHoldersSortOrder"},"TGMHoldersSortField":{"type":"string","enum":["address","name","token_amount","total_outflow","total_inflow","balance_change_24h","balance_change_7d","balance_change_30d","ownership_percentage","value_usd"],"title":"TGMHoldersSortField","description":"Enum for sortable fields in TGM holders."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMHoldersResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMHolder"},"type":"array","title":"Data","description":"List of TGM holder records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"warnings":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Warnings","description":"Optional warnings about the query results. For example, if a token has no USD price data, a warning will indicate that the default value_usd filter may be excluding results."}},"type":"object","required":["data","pagination"],"title":"TGMHoldersResponse","description":"Response model for TGM holders endpoint.\n\nContains a list of holder records with pagination and metadata."},"TGMHolder":{"properties":{"address":{"anyOf":[{"type":"string"}],"title":"Address","description":"Address of contract/EOA"},"address_label":{"anyOf":[{"type":"string"}],"title":"Address Label","description":"Label associated with the address"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"Total balance count"},"total_outflow":{"anyOf":[{"type":"number"}],"title":"Total Outflow","description":"Total amount of tokens sent by this address"},"total_inflow":{"anyOf":[{"type":"number"}],"title":"Total Inflow","description":"Total amount of tokens received by this address"},"balance_change_24h":{"anyOf":[{"type":"number"}],"title":"Balance Change 24H","description":"Token balance change over the last 24 hours"},"balance_change_7d":{"anyOf":[{"type":"number"}],"title":"Balance Change 7D","description":"Token balance change over the last 7 days"},"balance_change_30d":{"anyOf":[{"type":"number"}],"title":"Balance Change 30D","description":"Token balance change over the last 30 days"},"ownership_percentage":{"anyOf":[{"type":"number"}],"title":"Ownership Percentage","description":"Percentage of total token supply owned by this address"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Current token balance value in USD"}},"type":"object","title":"TGMHolder","description":"Individual TGM holder record.\n\nRepresents a single holder with balance information and metadata."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/holders":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) holders data","description":"Retrieve the top token holders with their current balances, historical activity, and recent balance changes. Provides insights into token distribution, smart money and fund holdings.\n\n**Performance Optimization for Native Tokens:**\nWhen querying native tokens with `label_type: \"all_holders\"`, this endpoint uses an optimized model to prevent timeouts. This optimization has the following limitations:\n- **Ordering**: Only `token_amount` field is supported\n- **Filters**: Limited to: `token_amount`, `total_outflow`, `total_inflow`, `address`, `include_smart_money_labels`, `exclude_smart_money_labels`\n\nTo use advanced filters and ordering on native tokens, specify a `label_type` other than \"all_holders\" (e.g., \"smart_money\", \"whale\", \"exchange\").\n\n**Label Tier Control (`premium_labels`):**\nWhen omitted or set to `false` (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing `premium_labels=true` returns premium labels (Smart Money, Fund, and other advanced labels), is billed at **150 credits per call**, and requires a paid plan.","operationId":"get_tgm_holders_api_v1_tgm_holders_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMHoldersRequest"}}},"required":true},"responses":{"200":{"description":"TGM holders data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMHoldersResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` ### How to use the Holders Endpoint The Holders Endpoint returns the current holders of a given token on a specific chain. It takes no date range. For holders on a past date, use [Historical Top Holders](/api/backtesting-data/historical-top-holders). You can use this to analyze who is holding a particular token—whether it’s Smart Money wallets, exchanges, or all holders. #### Usecase 1: Get list of Smart Money Holders 1. Set "label" to "smart\_money" in the parameters object. 2. Add "includeLabels" as an array with the specific Smart Money segments you want (e.g., "Fund", "30D Smart Trader"). 3. Other parameters (like chain, tokenAddress, etc.) stay the same. **Example Configuration:** ```json "label": "smart_money", "includeLabels": ["Fund", "30D Smart Trader"] "isEntity": true, -- To aggregate by Entity ``` #### Usecase 2: List of Exchanges Holding a Token 1. Set "label" to "exchange" in the parameters object. 2. Add "includeLabels" with "Exchange" 3. Other parameters remain unchanged. **Example Configuration:** ```json "label": "exchange", "includeLabels": ["Exchange"] "isEntity": true, -- To aggregate by Entity ``` # Flows {% hint style="warning" %} This endpoint does not support native tokens on any chain. Use a contract token address. See [Native Tokens](/reference/native-tokens) for endpoint-specific coverage. {% endhint %} ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it. ## Get "Token God Mode" (TGM) flows data > Analyze aggregated token flows by holder category over time. Shows hourly snapshots for ranges of seven days or less and daily snapshots for longer ranges.\ > \ > \`date\` and \`bucket\_end\` are RFC 3339 UTC timestamps for the inclusive start and exclusive end of each aggregation bucket. The request \`date.to\` value is an inclusive cutoff. \`is\_complete\` is \`false\` when that upper cutoff truncates a bucket or the bucket is still live. On Hyperliquid it is also \`false\` when \`date.from\` truncates the first bucket; on other chains the lower cutoff is aligned to the bucket start, so the full first bucket is returned. This flag describes request-window coverage, not whether the underlying data is final or will never be revised. Consumers should omit or visibly mark incomplete buckets in normal historical views.\ > \ > \*\*Note:\*\* the DEX/CEX breakdown fields (\`total\_inflows\_dex\`, \`total\_outflows\_dex\`, \`total\_inflows\_cex\`, \`total\_outflows\_cex\`) are only populated when \`label=exchange\` and are \`null\` for all other labels; a \`warnings\` entry is included in the response in that case. For net flow per holder segment (e.g. smart money), use the Flow Intelligence endpoint (\`POST /api/v1/tgm/flow-intelligence\`). ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMFlowsRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TGMFlowsChain","description":"Blockchain chain"},"token_address":{"type":"string","title":"Token Address","description":"Token address"},"date":{"$ref":"#/components/schemas/DateRange","description":"ISO 8601 date-time range object with optional from and to fields"},"label":{"$ref":"#/components/schemas/TGMFlowsLabel","description":"Label type for filtering flows","default":"top_100_holders"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMFlowsFilters"}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMFlowsSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"date\", \"direction\": \"DESC\"}] - Sort by date descending (most recent first)\n- [{\"field\": \"total_inflows_usd\", \"direction\": \"ASC\"}] - Sort by total inflows ascending\n- [{\"field\": \"total_outflows_usd\", \"direction\": \"DESC\"}] - Sort by total outflows descending"}},"additionalProperties":false,"type":"object","required":["chain","token_address","date"],"title":"TGMFlowsRequest","description":"Request model for TGM flows endpoint.\n\nThis endpoint provides comprehensive token flow analytics showing inflow and outflow patterns\nfrom various holder segments including Exchanges, Smart Money addresses, Public Figures, and Whales\nwith time-based statistics and trends."},"TGMFlowsChain":{"type":"string","enum":["arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","hyperliquid","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"TGMFlowsChain","description":"Chains supported for the TGM flows endpoint."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"TGMFlowsLabel":{"type":"string","enum":["whale","public_figure","smart_money","top_100_holders","exchange"],"title":"TGMFlowsLabel","description":"TGM flow label types."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMFlowsFilters":{"properties":{"price_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Price range filter in USD"},"token_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token amount range filter"},"value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Value range filter in USD"},"holders_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Holders count range filter"},"total_inflows_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Total inflows count range filter"},"total_outflows_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Total outflows count range filter"}},"additionalProperties":false,"type":"object","title":"TGMFlowsFilters","description":"Filters for TGM flows endpoint.\n\nThese filters control which data points are included in the flows analysis."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"TGMFlowsSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMFlowsSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMFlowsSortOrder"},"TGMFlowsSortField":{"type":"string","enum":["date","price_usd","token_amount","value_usd","holders_count","total_inflows_count","total_outflows_count","total_inflows_dex","total_outflows_dex","total_inflows_cex","total_outflows_cex"],"title":"TGMFlowsSortField","description":"Enum for sortable fields in TGM flows."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMFlowsResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMFlows"},"type":"array","title":"Data","description":"List of TGM flow records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"warnings":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Warnings","description":"Optional warnings about the query results. For example, when the DEX/CEX flow fields are null because a non-exchange label was requested."}},"type":"object","required":["data","pagination"],"title":"TGMFlowsResponse","description":"Response model for TGM flows endpoint.\n\nContains a list of flow records with pagination and metadata."},"TGMFlows":{"properties":{"date":{"type":"string","title":"Date","description":"Inclusive bucket start as an RFC 3339 UTC timestamp."},"bucket_end":{"anyOf":[{"type":"string"}],"title":"Bucket End","description":"Exclusive bucket end as an RFC 3339 UTC timestamp."},"is_complete":{"anyOf":[{"type":"boolean"}],"title":"Is Complete","description":"Whether the returned data covers the entire bucket under the endpoint's per-chain cutoff behavior. This describes request-window coverage, not whether the data is final."},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Daily median token price in USD. For the current day, uses the latest spot price."},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"Total token amount"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Total token value in USD"},"holders_count":{"anyOf":[{"type":"integer"}],"title":"Holders Count","description":"Number of token holders"},"total_inflows_count":{"anyOf":[{"type":"number"}],"title":"Total Inflows Count","description":"Total inflows"},"total_outflows_count":{"anyOf":[{"type":"number"}],"title":"Total Outflows Count","description":"Total outflows"},"total_inflows_dex":{"anyOf":[{"type":"number"}],"title":"Total Inflows Dex","description":"Total DEX inflows (token amount). Only populated when label=exchange, null otherwise."},"total_outflows_dex":{"anyOf":[{"type":"number"}],"title":"Total Outflows Dex","description":"Total DEX outflows (token amount). Only populated when label=exchange, null otherwise."},"total_inflows_cex":{"anyOf":[{"type":"number"}],"title":"Total Inflows Cex","description":"Total CEX inflows (token amount). Only populated when label=exchange, null otherwise."},"total_outflows_cex":{"anyOf":[{"type":"number"}],"title":"Total Outflows Cex","description":"Total CEX outflows (token amount). Only populated when label=exchange, null otherwise."}},"type":"object","required":["date"],"title":"TGMFlows","description":"Individual TGM flow record.\n\nRepresents a single flow record with token holder statistics."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/flows":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) flows data","description":"Analyze aggregated token flows by holder category over time. Shows hourly snapshots for ranges of seven days or less and daily snapshots for longer ranges.\n\n`date` and `bucket_end` are RFC 3339 UTC timestamps for the inclusive start and exclusive end of each aggregation bucket. The request `date.to` value is an inclusive cutoff. `is_complete` is `false` when that upper cutoff truncates a bucket or the bucket is still live. On Hyperliquid it is also `false` when `date.from` truncates the first bucket; on other chains the lower cutoff is aligned to the bucket start, so the full first bucket is returned. This flag describes request-window coverage, not whether the underlying data is final or will never be revised. Consumers should omit or visibly mark incomplete buckets in normal historical views.\n\n**Note:** the DEX/CEX breakdown fields (`total_inflows_dex`, `total_outflows_dex`, `total_inflows_cex`, `total_outflows_cex`) are only populated when `label=exchange` and are `null` for all other labels; a `warnings` entry is included in the response in that case. For net flow per holder segment (e.g. smart money), use the Flow Intelligence endpoint (`POST /api/v1/tgm/flow-intelligence`).","operationId":"get_tgm_flows_api_v1_tgm_flows_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMFlowsRequest"}}},"required":true},"responses":{"200":{"description":"TGM flows data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMFlowsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` ### Using /flows Endpoint The /flows endpoint allows you to analyze historical inflows and outflows of token holdings across specific wallet labels (e.g., Smart Money, Whales, Public Figures, etc.) on supported blockchains. This enables powerful workflows to investigate token accumulation or distribution trends by high-signal wallet groups over time. This guide walks through how to use the endpoint in a workflow to explore Smart Money behavior for a given token on a given chain. #### Usecase 1: Track Smart Money Accumulation Trends This workflow helps you: * Identify what tokens Smart Money is holding (e.g., via /holdings or /inflows) * Investigate how inflows/outflows of Smart Money have evolved over time * Combine historical activity with price trends for better decision-making **Step by Step Guide:** 1. Start with /holdings endpoint to identify what tokens Smart Money is holding. 2. Pick a token of interest based on value and activity patterns. 3. Use the /flows endpoint with the token address and smart\_money label to view inflow/outflow trends. 4. Specify timeframe (e.g., last 30 days) and examine how Smart Money behavior is evolving. #### Usecase 2: Monitor Exchange Flows This workflow helps you: * Track how much of a token is being sent to or from exchange wallets * Spot accumulation or distribution trends by observing net exchange flow * Correlate token price movement with CEX behavior patterns **Step by Step Guide:** 1. Identify a supported contract token of interest (for example, USDC). Native assets such as ETH and SOL are not supported by this endpoint. 2. Choose the chain where it is active. 3. Use label: "exchange" to track exchange wallets. 4. Analyze net flows: * High inflow = Possible sell pressure * High outflow = Possible accumulation 5. Correlate flow data with price action or events (e.g., listings, unlocks, news). # Position Intelligence Aggregated perpetual position analytics on Hyperliquid broken down by trader cohort. Position Intelligence shows aggregated long/short position sizes for a token's perpetual contract on Hyperliquid, broken down by trader cohorts: Smart Money, Whales, Top PnL, and Public Figures. Use it to understand sentiment and positioning distribution across high-signal wallet groups. ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Covers the Hyperliquid perpetuals dataset (reliable from **May 2025**), not per-chain history — see the Hyperliquid note on the coverage page. ## Get "Token God Mode" (TGM) position intelligence data > This endpoint provides position intelligence analytics for perpetual contracts on Hyperliquid, showing aggregated position sizes (longs, shorts, and totals) broken down by various trader cohorts (Smart Money, Whales, Top PnL, Public Figures). It can be used for analyzing position distributions and sentiment across different trader segments. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMPositionIntelligenceRequest":{"properties":{"token_address":{"type":"string","minLength":1,"title":"Token Address","description":"Token address (for perps and hyperliquid, validation is skipped)"}},"additionalProperties":false,"type":"object","required":["token_address"],"title":"TGMPositionIntelligenceRequest","description":"Request model for TGM position-intelligence endpoint.\n\nThis endpoint provides position intelligence analytics for perpetual contracts\non Hyperliquid, showing aggregated position sizes by different trader cohorts."},"TGMPositionIntelligenceResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMPositionIntelligence"},"type":"array","title":"Data","description":"List of TGM position intelligence records"}},"type":"object","required":["data"],"title":"TGMPositionIntelligenceResponse","description":"Response model for TGM position-intelligence endpoint.\n\nContains position intelligence data with pagination and metadata."},"TGMPositionIntelligence":{"properties":{"smart_trader_longs_usd":{"anyOf":[{"type":"number"}],"title":"Smart Trader Longs Usd","description":"Sum of absolute long sizes for addresses labeled Smart HL Perps Trader."},"smart_trader_shorts_usd":{"anyOf":[{"type":"number"}],"title":"Smart Trader Shorts Usd","description":"Sum of absolute short sizes for addresses labeled Smart HL Perps Trader."},"smart_trader_total_usd":{"anyOf":[{"type":"number"}],"title":"Smart Trader Total Usd","description":"Total absolute position size for addresses labeled Smart HL Perps Trader."},"whale_longs_usd":{"anyOf":[{"type":"number"}],"title":"Whale Longs Usd","description":"Sum of absolute long sizes for addresses labeled Whale."},"whale_shorts_usd":{"anyOf":[{"type":"number"}],"title":"Whale Shorts Usd","description":"Sum of absolute short sizes for addresses labeled Whale."},"whale_total_usd":{"anyOf":[{"type":"number"}],"title":"Whale Total Usd","description":"Total absolute position size for addresses labeled Whale."},"public_figure_longs_usd":{"anyOf":[{"type":"number"}],"title":"Public Figure Longs Usd","description":"Sum of absolute long sizes for addresses labeled Public Figure."},"public_figure_shorts_usd":{"anyOf":[{"type":"number"}],"title":"Public Figure Shorts Usd","description":"Sum of absolute short sizes for addresses labeled Public Figure."},"public_figure_total_usd":{"anyOf":[{"type":"number"}],"title":"Public Figure Total Usd","description":"Total absolute position size for addresses labeled Public Figure."}},"type":"object","title":"TGMPositionIntelligence","description":"Individual TGM position intelligence record.\n\nRepresents aggregated position sizes for different trader cohorts."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/position-intelligence":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) position intelligence data","description":"This endpoint provides position intelligence analytics for perpetual contracts on Hyperliquid, showing aggregated position sizes (longs, shorts, and totals) broken down by various trader cohorts (Smart Money, Whales, Top PnL, Public Figures). It can be used for analyzing position distributions and sentiment across different trader segments.","operationId":"get_tgm_position_intelligence_api_v1_tgm_position_intelligence_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPositionIntelligenceRequest"}}},"required":true},"responses":{"200":{"description":"TGM position intelligence data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPositionIntelligenceResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Who Bought/Sold ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Results are served from a server-side cache: once a requested date range has fully settled (about two days after it closes) it is cached for up to **7 days**, while ranges that include today or a recently-closed window use a short cache of up to **5 minutes**. ## Get "Token God Mode" (TGM) who bought/sold data > This endpoint provides an aggregated summary of trade volumes in USD for addresses. It can be used to identify addresses that are net buyers or sellers of a token within a time period. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMWhoBoughtSoldRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TGMChain","description":"Blockchain chain"},"token_address":{"type":"string","title":"Token Address","description":"Address of token"},"buy_or_sell":{"$ref":"#/components/schemas/TGMWhoBoughtSoldType","description":"Are we checking buys or sells","default":"BUY"},"date":{"$ref":"#/components/schemas/DateRange","description":"ISO 8601 date-time range object with from and to fields"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMWhoBoughtSoldFilters"}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMWhoBoughtSoldSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"bought_volume_usd\", \"direction\": \"DESC\"}] - Sort by bought volume descending\n- [{\"field\": \"sold_volume_usd\", \"direction\": \"ASC\"}] - Sort by sold volume ascending"}},"additionalProperties":false,"type":"object","required":["chain","token_address","date"],"title":"TGMWhoBoughtSoldRequest","description":"Request model for TGM who bought/sold endpoint.\n\nThis endpoint provides an aggregated summary of trade volumes in USD for addresses\ninvolved in DEX (Decentralized Exchange) trades for a specific token."},"TGMChain":{"type":"string","enum":["arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","hyperliquid","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"TGMChain","description":"Chains supported in TGM (Token God Mode) endpoints."},"TGMWhoBoughtSoldType":{"type":"string","enum":["BUY","SELL"],"title":"TGMWhoBoughtSoldType","description":"TGM who bought/sold type."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMWhoBoughtSoldFilters":{"properties":{"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Include smart money labels for traders"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels for traders"},"address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Address","description":"Trader address filter"},"address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Address Label","description":"Trader label filter"},"bought_token_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Bought token volume range filter"},"sold_token_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Sold token volume range filter"},"token_trade_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total token trade volume range filter"},"bought_volume_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Bought volume range filter in USD"},"sold_volume_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Sold volume range filter in USD"},"trade_volume_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total trade volume range filter in USD"}},"additionalProperties":false,"type":"object","title":"TGMWhoBoughtSoldFilters","description":"Filters for TGM who bought/sold endpoint.\n\nThese filters control which traders and trade data are included."},"LabelType":{"type":"string","enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"title":"LabelType","description":"Filter by entity label type."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"TGMWhoBoughtSoldSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMWhoBoughtSoldSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMWhoBoughtSoldSortOrder"},"TGMWhoBoughtSoldSortField":{"type":"string","enum":["bought_volume_usd","sold_volume_usd","token_trade_volume","trade_volume_usd","bought_token_volume","sold_token_volume"],"title":"TGMWhoBoughtSoldSortField","description":"Sortable fields for TGM who-bought-sold endpoint."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMWhoBoughtSoldResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMWhoBoughtSold"},"type":"array","title":"Data","description":"List of TGM who bought/sold records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TGMWhoBoughtSoldResponse","description":"Response model for TGM who bought/sold endpoint.\n\nContains a list of address records with pagination and metadata."},"TGMWhoBoughtSold":{"properties":{"address":{"type":"string","title":"Address","description":"The address that did the trades"},"address_label":{"anyOf":[{"type":"string"}],"title":"Address Label","description":"Label associated with the address"},"bought_token_volume":{"anyOf":[{"type":"number"}],"title":"Bought Token Volume","description":"The aggregate bought token volume for the address"},"sold_token_volume":{"anyOf":[{"type":"number"}],"title":"Sold Token Volume","description":"The aggregate sold token volume for the address"},"token_trade_volume":{"anyOf":[{"type":"number"}],"title":"Token Trade Volume","description":"The net token trade volume for the address"},"bought_volume_usd":{"anyOf":[{"type":"number"}],"title":"Bought Volume Usd","description":"The aggregate bought volume in USD for the address"},"sold_volume_usd":{"anyOf":[{"type":"number"}],"title":"Sold Volume Usd","description":"The aggregate sold volume in USD for the address"},"trade_volume_usd":{"anyOf":[{"type":"number"}],"title":"Trade Volume Usd","description":"The net trade volume in USD for the address"}},"type":"object","required":["address"],"title":"TGMWhoBoughtSold","description":"Individual TGM who bought/sold record.\n\nRepresents a single address with aggregated trade volumes."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/who-bought-sold":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) who bought/sold data","description":"This endpoint provides an aggregated summary of trade volumes in USD for addresses. It can be used to identify addresses that are net buyers or sellers of a token within a time period.","operationId":"get_tgm_who_bought_sold_api_v1_tgm_who_bought_sold_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMWhoBoughtSoldRequest"}}},"required":true},"responses":{"200":{"description":"TGM who bought/sold data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMWhoBoughtSoldResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # DEX Trades {% hint style="info" %} Native SOL is not supported by this endpoint. Native-token coverage is not equivalent to contract-token coverage; see [Native Tokens](/reference/native-tokens). {% endhint %} ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it. ## Get "Token God Mode" (TGM) DEX trades data > Access individual DEX trading transactions for a specific token. Shows detailed trade-by-trade data including trader labels, amounts, and prices. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMDexTradesRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TGMChain","description":"Blockchain chain"},"token_address":{"type":"string","title":"Token Address","description":"Token address"},"only_smart_money":{"type":"boolean","title":"Only Smart Money","description":"Returns only the DEX Trades made by Smart Money wallets","default":false},"date":{"$ref":"#/components/schemas/DateRange","description":"ISO 8601 date-time range object with optional from and to fields"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMDexTradesFilters"}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMDexTradesSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"block_timestamp\", \"direction\": \"DESC\"}] - Sort by timestamp descending\n- [{\"field\": \"estimated_value_usd\", \"direction\": \"ASC\"}] - Sort by estimated value ascending\n- [{\"field\": \"token_amount\", \"direction\": \"DESC\"}] - Sort by token amount descending"}},"additionalProperties":false,"type":"object","required":["chain","token_address","date"],"title":"TGMDexTradesRequest","description":"Request model for TGM dex-trades endpoint.\n\nThis endpoint provides all DEX trades for a specific token with optional filtering\nfor smart money wallets only."},"TGMChain":{"type":"string","enum":["arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","hyperliquid","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"TGMChain","description":"Chains supported in TGM (Token God Mode) endpoints."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMDexTradesFilters":{"properties":{"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Include smart money labels for counterparties"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels for counterparties"},"block_timestamp":{"anyOf":[{"$ref":"#/components/schemas/DateRangeFilter"}],"description":"Date range filter for trade timestamps"},"transaction_hash":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Transaction Hash","description":"Transaction hash filter"},"trader_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address","description":"Trader address filter"},"trader_address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address Label","description":"Trader name filter"},"token_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Token Address","description":"Token address filter"},"action":{"anyOf":[{"$ref":"#/components/schemas/TGMWhoBoughtSoldType"}],"description":"Action filter (BUY/SELL)"},"token_name":{"anyOf":[{"type":"string"}],"title":"Token Name","description":"Token name filter"},"token_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token amount range filter"},"traded_token_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Traded Token Address","description":"Traded token address filter"},"traded_token_name":{"anyOf":[{"type":"string"}],"title":"Traded Token Name","description":"Traded token name filter"},"traded_token_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Traded token amount range filter"},"estimated_swap_price_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Estimated swap price range filter in USD"},"estimated_value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Estimated value range filter in USD"}},"additionalProperties":false,"type":"object","title":"TGMDexTradesFilters","description":"Filters for TGM DEX trades endpoint.\n\nThese filters control which DEX trades are included in the analysis."},"LabelType":{"type":"string","enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"title":"LabelType","description":"Filter by entity label type."},"DateRangeFilter":{"properties":{"from":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"From","description":"Start date (inclusive), ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"To","description":"End date (inclusive), ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRangeFilter","description":"Filter for date ranges with optional from/to bounds. - Date range"},"TGMWhoBoughtSoldType":{"type":"string","enum":["BUY","SELL"],"title":"TGMWhoBoughtSoldType","description":"TGM who bought/sold type."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"TGMDexTradesSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMDexTradesSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMDexTradesSortOrder"},"TGMDexTradesSortField":{"type":"string","enum":["block_timestamp","transaction_hash","trader_address","trader_address_label","token_address","action","token_name","token_amount","traded_token_address","traded_token_name","traded_token_amount","estimated_swap_price_usd","estimated_value_usd"],"title":"TGMDexTradesSortField","description":"Enum for sortable fields in TGM DEX trades."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMDexTradesResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMDexTrade"},"type":"array","title":"Data","description":"List of TGM DEX trade records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TGMDexTradesResponse","description":"Response model for TGM dex-trades endpoint.\n\nContains a list of DEX trade records with pagination and metadata."},"TGMDexTrade":{"properties":{"block_timestamp":{"type":"string","title":"Block Timestamp","description":"Block timestamp of the trade"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Transaction hash"},"trader_address":{"type":"string","title":"Trader Address","description":"Trader's address"},"trader_address_label":{"anyOf":[{"type":"string"}],"title":"Trader Address Label","description":"Name of the trader, based on nansen_label"},"action":{"$ref":"#/components/schemas/TGMWhoBoughtSoldType","description":"The action taken by the trader. Either 'BUY' or 'SELL'"},"token_address":{"type":"string","title":"Token Address","description":"Address of token"},"token_name":{"type":"string","title":"Token Name","description":"The name of the token"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"The amount of the specified token traded"},"traded_token_address":{"type":"string","title":"Traded Token Address","description":"Address of token"},"traded_token_name":{"type":"string","title":"Traded Token Name","description":"The name of the token traded for the specified token"},"traded_token_amount":{"anyOf":[{"type":"number"}],"title":"Traded Token Amount","description":"The amount of the token traded for the specified token"},"estimated_swap_price_usd":{"anyOf":[{"type":"number"}],"title":"Estimated Swap Price Usd","description":"Estimated swap price in USD, derived from the counterpart token's USD value. Falls back to the daily median token price if the counterpart price is unavailable."},"estimated_value_usd":{"anyOf":[{"type":"number"}],"title":"Estimated Value Usd","description":"The estimated value of the trade in USD"}},"type":"object","required":["block_timestamp","transaction_hash","trader_address","action","token_address","token_name","token_amount","traded_token_address","traded_token_name","traded_token_amount","estimated_swap_price_usd","estimated_value_usd"],"title":"TGMDexTrade","description":"Individual TGM dex trade record.\n\nRepresents a single DEX trade for a specific token."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/dex-trades":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) DEX trades data","description":"Access individual DEX trading transactions for a specific token. Shows detailed trade-by-trade data including trader labels, amounts, and prices.","operationId":"get_tgm_dex_trades_api_v1_tgm_dex_trades_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMDexTradesRequest"}}},"required":true},"responses":{"200":{"description":"TGM DEX trades data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMDexTradesResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Token Transfers {% hint style="info" %} Native-token queries are supported only for Bitcoin on this endpoint. Other chains require a contract token address. See [Native Tokens](/reference/native-tokens). {% endhint %} ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it. ## Get "Token God Mode" (TGM) transfers data > Track all token transfer activity including direct transfers, DEX trades, and CEX movements. This endpoint is particularly useful for monitoring exchange flows - both centralized (CEX) and decentralized (DEX) - to identify accumulation or distribution patterns. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMTransfersRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TGMTransfersChain","description":"Blockchain chain"},"token_address":{"type":"string","title":"Token Address","description":"Token address"},"date":{"$ref":"#/components/schemas/DateRangeMaxOneYear","description":"ISO 8601 date-time range object with from and to fields (max 1 year)."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMTransfersFilters"}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMTransfersSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"transfer_value_usd\", \"direction\": \"ASC\"}] - Sort by transfer value ascending\n- [{\"field\": \"transfer_amount\", \"direction\": \"DESC\"}] - Sort by transfer amount descending"}},"additionalProperties":false,"type":"object","required":["chain","token_address","date"],"title":"TGMTransfersRequest","description":"Request model for TGM transfers endpoint.\n\nThis endpoint provides top token transfers for a specific token, with support for ERC-20 tokens. The model selection is dynamic based\non the token address."},"TGMTransfersChain":{"type":"string","enum":["arbitrum","arc","avalanche","base","bitcoin","bnb","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"TGMTransfersChain","description":"Chains supported for TGM transfers endpoint."},"DateRangeMaxOneYear":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRangeMaxOneYear","description":"Date range model with a maximum duration of 1 year.\n\nInherits all functionality from DateRange but adds validation to ensure\nthe date range does not exceed 366 days (to account for leap years).\n\nThis limit ensures optimal query performance."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMTransfersFilters":{"properties":{"include_dex":{"anyOf":[{"type":"boolean"}],"title":"Include Dex","description":"Whether to include DEX transfers"},"include_cex":{"anyOf":[{"type":"boolean"}],"title":"Include Cex","description":"Whether to include CEX transfers"},"non_exchange_transfers":{"anyOf":[{"type":"boolean"}],"title":"Non Exchange Transfers","description":"Whether to include non-exchange transfers"},"only_smart_money":{"anyOf":[{"type":"boolean"}],"title":"Only Smart Money","description":"Whether to include only smart money transfers"},"from_include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"From Include Smart Money Labels","description":"Include smart money labels for from address"},"from_exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"From Exclude Smart Money Labels","description":"Exclude smart money labels for from address"},"to_include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"To Include Smart Money Labels","description":"Include smart money labels for to address"},"to_exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"To Exclude Smart Money Labels","description":"Exclude smart money labels for to address"},"transaction_hash":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Transaction Hash","description":"Transaction hash filter"},"from_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"From Address","description":"From address filter"},"to_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"To Address","description":"To address filter"},"from_address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"From Address Label","description":"From address label filter"},"to_address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"To Address Label","description":"To address label filter"},"transaction_type":{"anyOf":[{"type":"string"}],"title":"Transaction Type","description":"Transaction type filter"},"transfer_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Transfer amount range filter"},"transfer_value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Transfer value range filter in USD"}},"additionalProperties":false,"type":"object","title":"TGMTransfersFilters","description":"Filters for TGM transfers endpoint.\n\nThese filters control which transfers are included in the analysis."},"LabelType":{"type":"string","enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"title":"LabelType","description":"Filter by entity label type."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"TGMTransfersSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMTransfersSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMTransfersSortOrder"},"TGMTransfersSortField":{"type":"string","enum":["block_timestamp","transaction_hash","from_address","to_address","from_address_label","to_address_label","transaction_type","transfer_amount","transfer_value_usd"],"title":"TGMTransfersSortField","description":"Enum for sortable fields in TGM transfers."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMTransfersResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMTransfer"},"type":"array","title":"Data","description":"List of TGM transfer records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TGMTransfersResponse","description":"Response model for TGM transfers endpoint.\n\nContains a list of transfer records with pagination and metadata."},"TGMTransfer":{"properties":{"block_timestamp":{"type":"string","title":"Block Timestamp","description":"The block timestamp for the transaction"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"The transaction hash for the transaction"},"from_address":{"type":"string","title":"From Address","description":"from address"},"to_address":{"type":"string","title":"To Address","description":"to address"},"from_address_label":{"anyOf":[{"type":"string"}],"title":"From Address Label","description":"from address label"},"to_address_label":{"anyOf":[{"type":"string"}],"title":"To Address Label","description":"to address label"},"transaction_type":{"anyOf":[{"type":"string"}],"title":"Transaction Type","description":"Transaction type"},"transfer_amount":{"anyOf":[{"type":"number"}],"title":"Transfer Amount","description":"value of the token traded"},"transfer_value_usd":{"anyOf":[{"type":"number"}],"title":"Transfer Value Usd","description":"value of the token traded in USD"}},"type":"object","required":["block_timestamp","transaction_hash","from_address","to_address"],"title":"TGMTransfer","description":"Individual TGM transfer record.\n\nRepresents a single token transfer with transaction details and participant information."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/transfers":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) transfers data","description":"Track all token transfer activity including direct transfers, DEX trades, and CEX movements. This endpoint is particularly useful for monitoring exchange flows - both centralized (CEX) and decentralized (DEX) - to identify accumulation or distribution patterns.","operationId":"get_tgm_transfers_api_v1_tgm_transfers_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMTransfersRequest"}}},"required":true},"responses":{"200":{"description":"TGM transfers data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMTransfersResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Jupiter DCAs {% hint style="warning" %} Native SOL is not supported by this endpoint. Use an SPL token address. See [Native Tokens](/reference/native-tokens). {% endhint %} ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Only the trailing **14 days** of DCA activity is queryable — shorter than the chain-level history — and there is no date-range parameter. ## Get "Token God Mode" (TGM) Jupiter DCA data > This endpoint provides Jupiter DCA orders with stats per vault for a specific token.\ > Jupiter DCA (Dollar Cost Averaging) is only available on Solana and allows users to automate token purchases over time. Returns comprehensive data about DCA vaults including deposit amounts, redemption status, and trader information. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMJupDcaRequest":{"properties":{"token_address":{"type":"string","title":"Token Address","description":"Token address on Solana"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMJupDcaFilters"}],"description":"Additional filters to apply to the query."}},"additionalProperties":false,"type":"object","required":["token_address"],"title":"TGMJupDcaRequest","description":"Request model for TGM Jupiter DCA endpoint.\n\nThis endpoint provides Jupiter DCA orders with stats per vault for a specific token.\nOnly supports Solana chain as Jupiter DCA is exclusive to Solana."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMJupDcaFilters":{"properties":{"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Include smart money labels for traders"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels for traders"},"trader_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address","description":"Trader address filter"},"trader_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Label","description":"Trader label filter"},"creation_hash":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Creation Hash","description":"Creation transaction hash filter"},"dca_vault_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Dca Vault Address","description":"DCA vault address filter"},"input_mint_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Input Mint Address","description":"Input token mint address filter"},"output_mint_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Output Mint Address","description":"Output token mint address filter"},"deposit_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Deposit amount range filter"},"deposit_spent":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Deposit spent amount range filter"},"other_token_redeemed":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Other token redeemed amount range filter"},"status":{"anyOf":[{"$ref":"#/components/schemas/TGMJupDcaStatus"}],"description":"DCA vault status filter"},"token_input":{"anyOf":[{"type":"string"}],"title":"Token Input","description":"Input token symbol filter"},"token_output":{"anyOf":[{"type":"string"}],"title":"Token Output","description":"Output token symbol filter"},"deposit_usd_value":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Deposit USD value range filter"}},"additionalProperties":false,"type":"object","title":"TGMJupDcaFilters","description":"Filters for TGM Jupiter DCA endpoint.\n\nThese filters control which Jupiter DCA orders are included in the analysis."},"LabelType":{"type":"string","enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"title":"LabelType","description":"Filter by entity label type."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"TGMJupDcaStatus":{"type":"string","enum":["Active","Closed"],"title":"TGMJupDcaStatus","description":"Enum for TGM Jupiter DCA status values."},"TGMJupDcaResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMJupDca"},"type":"array","title":"Data","description":"List of TGM Jupiter DCA records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TGMJupDcaResponse","description":"Response model for TGM Jupiter DCA endpoint.\n\nContains a list of Jupiter DCA records with pagination and metadata."},"TGMJupDca":{"properties":{"since_timestamp":{"anyOf":[{"type":"string"}],"title":"Since Timestamp","description":"The timestamp of the earliest transaction"},"last_timestamp":{"anyOf":[{"type":"string"}],"title":"Last Timestamp","description":"The timestamp of the latest transaction"},"trader_address":{"type":"string","title":"Trader Address","description":"The address of the trader"},"creation_hash":{"anyOf":[{"type":"string"}],"title":"Creation Hash","description":"The transaction hash at the time of creation"},"trader_label":{"anyOf":[{"type":"string"}],"title":"Trader Label","description":"The label of the trader obtained from Nansen's multichain data"},"dca_vault_address":{"anyOf":[{"type":"string"}],"title":"Dca Vault Address","description":"The address of the DCA vault"},"input_mint_address":{"anyOf":[{"type":"string"}],"title":"Input Mint Address","description":"The mint address of the input token"},"output_mint_address":{"anyOf":[{"type":"string"}],"title":"Output Mint Address","description":"The mint address of the output token"},"deposit_amount":{"anyOf":[{"type":"number"}],"title":"Deposit Amount","description":"The amount deposited into the DCA vault"},"deposit_spent":{"anyOf":[{"type":"number"}],"title":"Deposit Spent","description":"The amount spent from the deposit"},"other_token_redeemed":{"anyOf":[{"type":"number"}],"title":"Other Token Redeemed","description":"The amount of other tokens redeemed"},"status":{"anyOf":[{"$ref":"#/components/schemas/TGMJupDcaStatus"}],"description":"The status of the DCA vault"},"token_input":{"anyOf":[{"type":"string"}],"title":"Token Input","description":"The symbol of the input token"},"token_output":{"anyOf":[{"type":"string"}],"title":"Token Output","description":"The symbol of the output token"},"deposit_usd_value":{"anyOf":[{"type":"number"}],"title":"Deposit Usd Value","description":"The USD value of the deposit"}},"type":"object","required":["trader_address"],"title":"TGMJupDca","description":"Individual TGM Jupiter DCA record.\n\nRepresents a single Jupiter DCA order with stats per vault."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/jup-dca":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) Jupiter DCA data","description":"This endpoint provides Jupiter DCA orders with stats per vault for a specific token.\nJupiter DCA (Dollar Cost Averaging) is only available on Solana and allows users to automate token purchases over time. Returns comprehensive data about DCA vaults including deposit amounts, redemption status, and trader information.","operationId":"get_tgm_jup_dca_api_v1_tgm_jup_dca_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMJupDcaRequest"}}},"required":true},"responses":{"200":{"description":"TGM Jupiter DCA data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMJupDcaResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # PnL Leaderboard {% hint style="warning" %} This endpoint does not support native tokens on any chain. Use a contract token address. See [Native Tokens](/reference/native-tokens) for endpoint-specific coverage. {% endhint %} {% hint style="warning" %} **Update:** The `premium_labels` parameter on this endpoint now defaults to `false`, as previously announced in the API changelog. Requests that omit the parameter return free-tier labels at the standard credit cost. Passing `premium_labels=true` returns premium labels (Smart Money, Fund, etc.), is billed at **150 credits per call**, and requires a paid plan. See the API changelog for details. {% endhint %} ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Results are served from a server-side cache: once a requested date range has fully settled (about two days after it closes) it is cached for up to **7 days**, while ranges that include today or a recently-closed window use a short cache of up to **5 minutes**. ## Get "Token God Mode" (TGM) PnL leaderboard data > Rank traders by their profit/loss performance for a specific token. Shows both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages and trading patterns. This endpoint can be used to analyze the realized and unrealized profit for each trader who traded the input token.\ > \ > \*\*Label Tier Control (\`premium\_labels\`):\*\*\ > When omitted or set to \`false\` (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing \`premium\_labels=true\` returns premium labels (Smart Money, Fund, and other advanced labels), is billed at \*\*150 credits per call\*\*, and requires a paid plan. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMPnlLeaderboardRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TGMPnLLeaderboardChain","description":"Blockchain chain"},"token_address":{"type":"string","title":"Token Address","description":"Token address"},"date":{"$ref":"#/components/schemas/DateRange","description":"ISO 8601 date-time range object with optional from and to fields"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMPnlLeaderboardFilters"}],"description":"Additional filters to apply to the query."},"premium_labels":{"anyOf":[{"type":"boolean"}],"title":"Premium Labels","description":"Controls label tier in the response. When null/omitted or false (the default), returns free-tier labels at the standard credit cost for this endpoint. When true, returns premium labels (Smart Money, Fund, and other advanced labels), is billed at 150 credits per call, and requires a paid plan."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMPnlLeaderboardSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering"}},"additionalProperties":false,"type":"object","required":["chain","token_address","date"],"title":"TGMPnlLeaderboardRequest","description":"Request model for TGM PnL leaderboard endpoint.\nThis endpoint provides a token PnL leaderboard showing the most profitable\ntraders for a specific token within a given date range."},"TGMPnLLeaderboardChain":{"type":"string","enum":["arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","hyperliquid","linea","mantle","monad","optimism","plasma","polygon","robinhood","sei","solana","sonic","sui"],"title":"TGMPnLLeaderboardChain","description":"Chains supported for TGM PnL leaderboard endpoint."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMPnlLeaderboardFilters":{"properties":{"trader_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address","description":"Trader address filter"},"trader_address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address Label","description":"Trader name filter"},"token_price":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token price range filter"},"pnl_usd_realised":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Realized PnL range filter in USD"},"pnl_usd_unrealised":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Unrealized PnL range filter in USD"},"holding_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Holding amount range filter"},"holding_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Holding value range filter in USD"},"max_balance_held":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Maximum balance held range filter"},"max_balance_held_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Maximum balance held range filter in USD"},"still_holding_balance_ratio":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Still holding balance ratio range filter"},"nof_trades":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Number of trades range filter"}},"additionalProperties":false,"type":"object","title":"TGMPnlLeaderboardFilters","description":"Filters for TGM PnL leaderboard endpoint.\n\nThese filters control which traders are included in the leaderboard."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"TGMPnlLeaderboardSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMPnlLeaderboardSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMPnlLeaderboardSortOrder"},"TGMPnlLeaderboardSortField":{"type":"string","enum":["pnl_usd_realised","pnl_usd_unrealised","pnl_usd_total","roi_percent_total","roi_percent_realised","roi_percent_unrealised","holding_amount","holding_usd","max_balance_held","max_balance_held_usd","still_holding_balance_ratio","netflow_amount_usd","netflow_amount","nof_trades"],"title":"TGMPnlLeaderboardSortField","description":"Enum for sortable fields in TGM PnL leaderboard."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMPnlLeaderboardResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMPnlLeaderboard"},"type":"array","title":"Data","description":"List of TGM PnL leaderboard records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TGMPnlLeaderboardResponse","description":"Response model for TGM PnL leaderboard endpoint.\nContains a list of PnL leaderboard records with pagination and metadata."},"TGMPnlLeaderboard":{"properties":{"trader_address":{"type":"string","title":"Trader Address","description":"Hexadecimal representation of the trader's address."},"trader_address_label":{"anyOf":[{"type":"string"}],"title":"Trader Address Label","description":"Nansen name of the trader"},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Token price in USD at date_to. Uses latest spot price if date_to is today or later, otherwise the daily median price for that date."},"pnl_usd_realised":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Realised","description":"Realised profit and loss in USD."},"pnl_usd_unrealised":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Unrealised","description":"Unrealised profit and loss in USD."},"holding_amount":{"anyOf":[{"type":"number"}],"title":"Holding Amount","description":"Current token balance"},"holding_usd":{"anyOf":[{"type":"number"}],"title":"Holding Usd","description":"USD value of token balance"},"max_balance_held":{"anyOf":[{"type":"number"}],"title":"Max Balance Held","description":"Maximum amount of tokens held at some point in time."},"max_balance_held_usd":{"anyOf":[{"type":"number"}],"title":"Max Balance Held Usd","description":"Maximum amount of tokens in current USD value, held at some point in time."},"still_holding_balance_ratio":{"anyOf":[{"type":"number"}],"title":"Still Holding Balance Ratio","description":"The ratio of current holdings to max balance held."},"netflow_amount_usd":{"anyOf":[{"type":"number"}],"title":"Netflow Amount Usd","description":"Netflow amount in USD."},"netflow_amount":{"anyOf":[{"type":"number"}],"title":"Netflow Amount","description":"Netflow amount."},"roi_percent_total":{"anyOf":[{"type":"number"}],"title":"Roi Percent Total","description":"Total ROI."},"roi_percent_realised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Realised","description":"Realised ROI."},"roi_percent_unrealised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Unrealised","description":"Unrealised ROI."},"pnl_usd_total":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Total","description":"Total PNL in USD."},"nof_trades":{"anyOf":[{"type":"integer"}],"title":"Nof Trades","description":"Number of trades."}},"type":"object","required":["trader_address"],"title":"TGMPnlLeaderboard","description":"Individual TGM PnL leaderboard record.\nRepresents a single trader's PnL performance for a specific token."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/pnl-leaderboard":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) PnL leaderboard data","description":"Rank traders by their profit/loss performance for a specific token. Shows both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages and trading patterns. This endpoint can be used to analyze the realized and unrealized profit for each trader who traded the input token.\n\n**Label Tier Control (`premium_labels`):**\nWhen omitted or set to `false` (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing `premium_labels=true` returns premium labels (Smart Money, Fund, and other advanced labels), is billed at **150 credits per call**, and requires a paid plan.","operationId":"get_tgm_pnl_leaderboard_api_v1_tgm_pnl_leaderboard_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPnlLeaderboardRequest"}}},"required":true},"responses":{"200":{"description":"TGM PnL leaderboard data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPnlLeaderboardResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Perp Screener ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Covers the Hyperliquid perpetuals dataset (reliable from **May 2025**), not per-chain history — see the Hyperliquid note on the coverage page. ## Get Perpetual Contract Screening Data > Discover and screen perpetual contracts on Hyperliquid with advanced filtering capabilities. This endpoint helps identify trending perpetual contracts, trading activity, funding rates, and smart money movements by combining metrics like volume, open interest, funding rates, and position data.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*Which perpetual contracts are experiencing significant trading volume and activity?\*\*\ > 2\. \*\*How do funding rates correlate with trading patterns and smart money positions?\*\*\ > 3\. \*\*What perpetual contracts show strong fundamentals in terms of open interest and trading patterns?\*\*\ > 4\. \*\*Which perpetual contracts are attracting smart money participation with long/short positions?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"PerpScreenerRequest":{"properties":{"date":{"$ref":"#/components/schemas/DateRange","description":"Date range for the perp screener"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/PerpScreenerFilters"}],"description":"Additional filters to apply"},"include_price_change":{"type":"boolean","title":"Include Price Change","description":"Return previous_price_usd, window_end_price_usd and price_change for notable-label trader cohorts even when not sorting or filtering by price. These fields are otherwise null unless price_change or previous_price_usd is used for sorting, or previous_price_usd is used for filtering. All and Smart Money results always include these fields.","default":false},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/PerpScreenerSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"volume\", \"direction\": \"DESC\"}] - Sort by volume descending\n- [{\"field\": \"net_position_change\", \"direction\": \"DESC\"}] - Sort by net_position_change descending\n- [{\"field\": \"buy_sell_pressure\", \"direction\": \"DESC\"}] - Sort by buy/sell pressure descending\n- [{\"field\": \"price_change\", \"direction\": \"DESC\"}] - Top gainers first\n\nAvailable sort fields depend on trader_type: buy_sell_pressure only applies to\ntrader_type all, net_position_change to the other trader types. price_change\napplies to every trader type. Rows with a null price_change (outcome contracts,\nmissing prices) sort last in both directions, and token_symbol ASC\nis added as a final tie-breaker so pages don't overlap.\n\nDefault behavior:\n- trader_type all (or unset): sorts by buy_sell_pressure DESC\n- all other trader types: sorts by net_position_change DESC"}},"additionalProperties":false,"type":"object","required":["date"],"title":"PerpScreenerRequest","description":"Request model for Perp Screener endpoint."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"PerpScreenerFilters":{"properties":{"trader_type":{"anyOf":[{"$ref":"#/components/schemas/PerpTraderType"}],"description":"Filter by trader type. Overrides only_smart_money when provided. Values: all, sm, whale, public_figure, high_winrate_hl_perps_trader."},"only_smart_money":{"anyOf":[{"type":"boolean"}],"title":"Only Smart Money","description":"Deprecated: Use 'trader_type=sm' instead.","default":false,"deprecated":true},"sectors_filter":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Sectors Filter","description":"Filter by sector in category:subcategory format (e.g. Crypto:DeFi, Crypto:AI, TradFi:Stocks). Values in any other format are rejected. Note: this differs from the token screener's sectors filter, which uses bare sector names. Applied server-side."},"sm_label_filter":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Sm Label Filter","description":"Filter by Nansen smart money label. Applies when trader_type is all or sm; ignored for other trader types. Applied server-side."},"trader_label_filter":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Trader Label Filter","description":"Filter by Hyperliquid perps trader label (e.g. HL Perps Whale, HL Perps Swing Trader). Applies when trader_type is all or sm; ignored for other trader types. Applied server-side."},"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","description":"Asset symbol filter (e.g., BTC, ETH)"},"volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total traded notional in USD range filter"},"buy_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total USD value of market buy trades range filter"},"sell_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total USD value of market sell trades range filter"},"buy_sell_pressure":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Net USD flow range filter"},"trader_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of unique traders range filter"},"mark_price":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Latest mark price range filter"},"funding":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Latest funding rate range filter"},"previous_price_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Window-start mark price range filter: the close of the last complete 5-minute bucket ending at or before date.from (UTC). Rows with a null start price match only a filter with no max and a min of 0 or less."},"open_interest":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Latest open interest range filter"},"smart_money_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total traded notional in USD by Smart Money range filter"},"smart_money_buy_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total USD value of Smart Money market buy trades range filter"},"smart_money_sell_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total USD value of Smart Money market sell trades range filter"},"net_position_change":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Net USD flow (buy_market_vol - sell_market_vol) range filter"},"current_smart_money_position_longs_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Aggregate USD value of Smart Money long positions range filter"},"current_smart_money_position_shorts_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Aggregate USD value of Smart Money short positions range filter"},"smart_money_longs_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of Smart Money accounts with net long position range filter"},"smart_money_shorts_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of Smart Money accounts with net short position range filter"}},"additionalProperties":false,"type":"object","title":"PerpScreenerFilters","description":"Filters for perp screener endpoints.\n\nThese filters control which perpetual contracts are included in the screening\nresults based on various criteria."},"PerpTraderType":{"type":"string","enum":["all","sm","whale","public_figure","high_winrate_hl_perps_trader"],"title":"PerpTraderType","description":"Trader type for perp screener."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"PerpScreenerSortOrder":{"properties":{"field":{"anyOf":[{"$ref":"#/components/schemas/PerpScreenerSortFieldDefault"},{"$ref":"#/components/schemas/PerpScreenerSortFieldSmartMoney"},{"$ref":"#/components/schemas/PerpScreenerSortFieldNotableLabel"}],"title":"Field","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"PerpScreenerSortOrder"},"PerpScreenerSortFieldDefault":{"type":"string","enum":["token_symbol","volume","buy_volume","sell_volume","buy_sell_pressure","trader_count","mark_price","funding","previous_price_usd","price_change","open_interest"],"title":"PerpScreenerSortFieldDefault","description":"Sort fields available for default perp screener data (only_smart_money=False)."},"PerpScreenerSortFieldSmartMoney":{"type":"string","enum":["token_symbol","smart_money_volume","smart_money_buy_volume","smart_money_sell_volume","net_position_change","trader_count","mark_price","funding","previous_price_usd","price_change","open_interest","current_smart_money_position_longs_usd","current_smart_money_position_shorts_usd","smart_money_longs_count","smart_money_shorts_count"],"title":"PerpScreenerSortFieldSmartMoney","description":"Sort fields available for smart money perp screener data (only_smart_money=True)."},"PerpScreenerSortFieldNotableLabel":{"type":"string","enum":["token_symbol","volume","buy_volume","sell_volume","net_position_change","trader_count","mark_price","funding","previous_price_usd","price_change","open_interest","current_position_longs_usd","current_position_shorts_usd","longs_count","shorts_count"],"title":"PerpScreenerSortFieldNotableLabel","description":"Sort fields available for notable-label perp screener data (trader_type whale/public_figure/high_winrate_hl_perps_trader)."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"PerpScreenerResponse":{"properties":{"data":{"items":{"anyOf":[{"$ref":"#/components/schemas/PerpScreenerDataDefault"},{"$ref":"#/components/schemas/PerpScreenerDataSmartMoney"},{"$ref":"#/components/schemas/PerpScreenerDataNotableLabel"}]},"type":"array","title":"Data","description":"List of perp screening results"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"PerpScreenerResponse","description":"Response model for perp screener endpoint."},"PerpScreenerDataDefault":{"properties":{"volume":{"anyOf":[{"type":"number"}],"title":"Volume","description":"Total traded notional in USD over the recent window."},"buy_volume":{"anyOf":[{"type":"number"}],"title":"Buy Volume","description":"Total USD value of market buy trades over the recent window."},"sell_volume":{"anyOf":[{"type":"number"}],"title":"Sell Volume","description":"Total USD value of market sell trades over the recent window."},"buy_sell_pressure":{"anyOf":[{"type":"number"}],"title":"Buy Sell Pressure","description":"Changes in position by Market Orders. Buys and sells through market orders (top of orderbook) indicate a rush into adjusting the position."},"trader_count":{"anyOf":[{"type":"integer"}],"title":"Trader Count","description":"Number of unique traders active over the recent window."},"token_symbol":{"type":"string","title":"Token Symbol","description":"Asset symbol (e.g., BTC, ETH) on Hyperliquid."},"mark_price":{"anyOf":[{"type":"number"}],"title":"Mark Price","description":"Latest mark price for the coin."},"funding":{"anyOf":[{"type":"number"}],"title":"Funding","description":"Latest funding rate/value for the coin."},"open_interest":{"anyOf":[{"type":"number"}],"title":"Open Interest","description":"Latest open interest for the coin."},"previous_price_usd":{"anyOf":[{"type":"number"}],"title":"Previous Price Usd","description":"Window-start mark price: the close of the last complete 5-minute bucket ending at or before date.from (UTC). A 09:00 or 09:02 start uses the 08:55 to 09:00 bucket. Null when that bucket is missing or its price is not positive; no later or earlier price substitutes. HIP-3 markets (symbols like xyz:NAME) have no mark history before 2026-03-12, so their closes before then are the last trade in the bucket."},"window_end_price_usd":{"anyOf":[{"type":"number"}],"title":"Window End Price Usd","description":"Window-end mark price: the close of the last complete 5-minute bucket ending at or before date.to, capped at now (UTC). For a window ending now this is the latest complete bucket, not the live mark_price. Null when that bucket is missing or its price is not positive. HIP-3 markets (symbols like xyz:NAME) have no mark history before 2026-03-12, so their closes before then are the last trade in the bucket."},"price_change":{"anyOf":[{"type":"number"}],"title":"Price Change","description":"Signed ratio change over the date window, window_end_price_usd / previous_price_usd - 1 (0.05 = +5%, -0.2 = -20%). Both prices are 5-minute Hyperliquid closes at the window boundaries and do not depend on which traders were active, so a coin and window have the same value in every trader_type. A historical window uses its own end price, not the latest mark. Null for outcome contracts (symbols starting with '#') and when either boundary price is missing, zero, or negative."}},"type":"object","required":["token_symbol"],"title":"PerpScreenerDataDefault","description":"Data model for perp screener results when only_smart_money is False."},"PerpScreenerDataSmartMoney":{"properties":{"smart_money_volume":{"anyOf":[{"type":"number"}],"title":"Smart Money Volume","description":"Total traded notional in USD by Smart Money over the window."},"smart_money_buy_volume":{"anyOf":[{"type":"number"}],"title":"Smart Money Buy Volume","description":"Total USD value of Smart Money market buy trades over the window."},"smart_money_sell_volume":{"anyOf":[{"type":"number"}],"title":"Smart Money Sell Volume","description":"Total USD value of Smart Money market sell trades over the window."},"net_position_change":{"anyOf":[{"type":"number"}],"title":"Net Position Change","description":"Net USD flow (buy_market_vol - sell_market_vol) over the window."},"trader_count":{"anyOf":[{"type":"integer"}],"title":"Trader Count","description":"Number of unique Smart Money traders active over the window."},"token_symbol":{"type":"string","title":"Token Symbol","description":"Asset symbol (e.g., BTC, ETH) on Hyperliquid."},"mark_price":{"anyOf":[{"type":"number"}],"title":"Mark Price","description":"Latest mark price for the coin."},"funding":{"anyOf":[{"type":"number"}],"title":"Funding","description":"Latest funding rate/value for the coin."},"previous_price_usd":{"anyOf":[{"type":"number"}],"title":"Previous Price Usd","description":"Window-start mark price: the close of the last complete 5-minute bucket ending at or before date.from (UTC). A 09:00 or 09:02 start uses the 08:55 to 09:00 bucket. Null when that bucket is missing or its price is not positive; no later or earlier price substitutes. HIP-3 markets (symbols like xyz:NAME) have no mark history before 2026-03-12, so their closes before then are the last trade in the bucket."},"window_end_price_usd":{"anyOf":[{"type":"number"}],"title":"Window End Price Usd","description":"Window-end mark price: the close of the last complete 5-minute bucket ending at or before date.to, capped at now (UTC). For a window ending now this is the latest complete bucket, not the live mark_price. Null when that bucket is missing or its price is not positive. HIP-3 markets (symbols like xyz:NAME) have no mark history before 2026-03-12, so their closes before then are the last trade in the bucket."},"price_change":{"anyOf":[{"type":"number"}],"title":"Price Change","description":"Signed ratio change over the date window, window_end_price_usd / previous_price_usd - 1 (0.05 = +5%, -0.2 = -20%). Both prices are 5-minute Hyperliquid closes at the window boundaries and do not depend on which traders were active, so a coin and window have the same value in every trader_type. A historical window uses its own end price, not the latest mark. Null for outcome contracts (symbols starting with '#') and when either boundary price is missing, zero, or negative."},"open_interest":{"anyOf":[{"type":"number"}],"title":"Open Interest","description":"Latest open interest in USD (open_interest × mark_price)."},"current_smart_money_position_longs_usd":{"anyOf":[{"type":"number"}],"title":"Current Smart Money Position Longs Usd","description":"Aggregate USD value of Smart Money long positions for the coin."},"current_smart_money_position_shorts_usd":{"anyOf":[{"type":"number"}],"title":"Current Smart Money Position Shorts Usd","description":"Aggregate USD value of Smart Money short positions for the coin (negative)."},"smart_money_longs_count":{"anyOf":[{"type":"integer"}],"title":"Smart Money Longs Count","description":"Number of Smart Money accounts with a net long position."},"smart_money_shorts_count":{"anyOf":[{"type":"integer"}],"title":"Smart Money Shorts Count","description":"Number of Smart Money accounts with a net short position."}},"type":"object","required":["token_symbol"],"title":"PerpScreenerDataSmartMoney","description":"Data model for perp screener results when only_smart_money is True."},"PerpScreenerDataNotableLabel":{"properties":{"volume":{"anyOf":[{"type":"number"}],"title":"Volume","description":"Total traded notional in USD by the selected trader cohort over the window."},"buy_volume":{"anyOf":[{"type":"number"}],"title":"Buy Volume","description":"Total USD value of buys by the selected trader cohort over the window."},"sell_volume":{"anyOf":[{"type":"number"}],"title":"Sell Volume","description":"Total USD value of sells by the selected trader cohort over the window."},"net_position_change":{"anyOf":[{"type":"number"}],"title":"Net Position Change","description":"Net USD flow (buys minus sells) by the selected trader cohort over the window."},"trader_count":{"anyOf":[{"type":"integer"}],"title":"Trader Count","description":"Number of unique cohort traders active over the window."},"token_symbol":{"type":"string","title":"Token Symbol","description":"Asset symbol (e.g., BTC, ETH) on Hyperliquid."},"mark_price":{"anyOf":[{"type":"number"}],"title":"Mark Price","description":"Latest mark price for the coin."},"funding":{"anyOf":[{"type":"number"}],"title":"Funding","description":"Latest funding rate/value for the coin."},"previous_price_usd":{"anyOf":[{"type":"number"}],"title":"Previous Price Usd","description":"Window-start mark price: the close of the last complete 5-minute bucket ending at or before date.from (UTC). A 09:00 or 09:02 start uses the 08:55 to 09:00 bucket. Null when that bucket is missing or its price is not positive; no later or earlier price substitutes. HIP-3 markets (symbols like xyz:NAME) have no mark history before 2026-03-12, so their closes before then are the last trade in the bucket. Null unless price fields are requested with include_price_change, sorting or filtering."},"window_end_price_usd":{"anyOf":[{"type":"number"}],"title":"Window End Price Usd","description":"Window-end mark price: the close of the last complete 5-minute bucket ending at or before date.to, capped at now (UTC). For a window ending now this is the latest complete bucket, not the live mark_price. Null when that bucket is missing or its price is not positive. HIP-3 markets (symbols like xyz:NAME) have no mark history before 2026-03-12, so their closes before then are the last trade in the bucket. Null unless price fields are requested with include_price_change, sorting or filtering."},"price_change":{"anyOf":[{"type":"number"}],"title":"Price Change","description":"Signed ratio change over the date window, window_end_price_usd / previous_price_usd - 1 (0.05 = +5%, -0.2 = -20%). Both prices are 5-minute Hyperliquid closes at the window boundaries and do not depend on which traders were active, so a coin and window have the same value in every trader_type. A historical window uses its own end price, not the latest mark. Null for outcome contracts (symbols starting with '#') and when either boundary price is missing, zero, or negative. Null unless price fields are requested with include_price_change, sorting or filtering."},"open_interest":{"anyOf":[{"type":"number"}],"title":"Open Interest","description":"Latest open interest for the coin."},"current_position_longs_usd":{"anyOf":[{"type":"number"}],"title":"Current Position Longs Usd","description":"Aggregate USD value of cohort long positions for the coin."},"current_position_shorts_usd":{"anyOf":[{"type":"number"}],"title":"Current Position Shorts Usd","description":"Aggregate USD value of cohort short positions for the coin (negative)."},"longs_count":{"anyOf":[{"type":"integer"}],"title":"Longs Count","description":"Number of cohort accounts with a net long position."},"shorts_count":{"anyOf":[{"type":"integer"}],"title":"Shorts Count","description":"Number of cohort accounts with a net short position."}},"type":"object","required":["token_symbol"],"title":"PerpScreenerDataNotableLabel","description":"Data model for perp screener when trader_type is whale, public_figure or high_winrate_hl_perps_trader."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/perp-screener":{"post":{"tags":["Token Screener"],"summary":"Get Perpetual Contract Screening Data","description":"Discover and screen perpetual contracts on Hyperliquid with advanced filtering capabilities. This endpoint helps identify trending perpetual contracts, trading activity, funding rates, and smart money movements by combining metrics like volume, open interest, funding rates, and position data.\n\n**What it helps to answer:**\n\n1. **Which perpetual contracts are experiencing significant trading volume and activity?**\n2. **How do funding rates correlate with trading patterns and smart money positions?**\n3. **What perpetual contracts show strong fundamentals in terms of open interest and trading patterns?**\n4. **Which perpetual contracts are attracting smart money participation with long/short positions?**","operationId":"get_perp_screener_api_v1_perp_screener_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpScreenerRequest"}}},"required":true},"responses":{"200":{"description":"Perpetual contract screening data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpScreenerResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Perp PnL Leaderboard {% hint style="warning" %} **Update:** The `premium_labels` parameter on this endpoint now defaults to `false`, as previously announced in the API changelog. Requests that omit the parameter return free-tier labels at the standard credit cost. Passing `premium_labels=true` returns premium labels (Smart Money, Fund, etc.), is billed at **150 credits per call**, and requires a paid plan. See the API changelog for details. {% endhint %} ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Covers the Hyperliquid perpetuals dataset (reliable from **May 2025**), not per-chain history — see the Hyperliquid note on the coverage page. ## Get "Token God Mode" (TGM) perp PnL leaderboard data > Rank traders by their profit/loss performance for a specific perpetual contract on Hyperliquid. Shows both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages and trading patterns. This endpoint can be used to analyze the realized and unrealized profit for each trader who traded the input perpetual contract.\ > \ > \*\*Key Features:\*\*\ > \- Hyperliquid perpetual contracts only (no chain field needed)\ > \- Realized and unrealized PnL tracking\ > \- ROI calculations and trading patterns\ > \- Position size and balance tracking\ > \ > \*\*Request Format:\*\*\ > \- \`token\_symbol\`: Perpetual contract symbol (e.g., "BTC", "ETH", "SOL")\ > \- \`date\`: Date range for analysis\ > \- \`filters\`: Optional filters for trader addresses, PnL ranges, etc.\ > \- \`pagination\`: Page and per\_page parameters\ > \ > \*\*Label Tier Control (\`premium\_labels\`):\*\*\ > When omitted or set to \`false\` (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing \`premium\_labels=true\` returns premium labels (Smart Money, Fund, and other advanced labels), is billed at \*\*150 credits per call\*\*, and requires a paid plan. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMPerpPnlLeaderboardRequest":{"properties":{"token_symbol":{"type":"string","title":"Token Symbol","description":"Perpetual contract symbol (e.g., BTC, ETH, SOL)"},"date":{"$ref":"#/components/schemas/DateRange","description":"ISO 8601 date-time range object with optional from and to fields"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMPerpPnlLeaderboardFilters"}],"description":"Additional filters to apply to the query."},"premium_labels":{"anyOf":[{"type":"boolean"}],"title":"Premium Labels","description":"Controls label tier in the response. When null/omitted or false (the default), returns free-tier labels at the standard credit cost for this endpoint. When true, returns premium labels (Smart Money, Fund, and other advanced labels), is billed at 150 credits per call, and requires a paid plan."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMPerpPnlLeaderboardSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering"}},"type":"object","required":["token_symbol","date"],"title":"TGMPerpPnlLeaderboardRequest","description":"Request model for TGM Perp PnL leaderboard endpoint.\nSimplified version that only supports Hyperliquid perpetual contracts."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMPerpPnlLeaderboardFilters":{"properties":{"trader_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address","description":"Trader address filter"},"trader_address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address Label","description":"Trader name filter"},"token_price":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token price range filter"},"pnl_usd_realised":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Realized PnL range filter in USD"},"pnl_usd_unrealised":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Unrealized PnL range filter in USD"},"holding_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Holding amount range filter"},"position_value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Position value range filter in USD (+ve = Long position, -ve = Short position, 0 = Flat)"},"max_balance_held":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Maximum balance held range filter"},"max_balance_held_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Maximum balance held range filter in USD"},"still_holding_balance_ratio":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Still holding balance ratio range filter"},"nof_trades":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Number of trades range filter. Counts trades since the start of the requested date range."},"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Include smart money labels"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels"}},"additionalProperties":false,"type":"object","title":"TGMPerpPnlLeaderboardFilters","description":"Filters for TGM Perp PnL leaderboard endpoint.\n\nThese filters control which traders are included in the leaderboard."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Filter by smart money label type."},"TGMPerpPnlLeaderboardSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMPerpPnlLeaderboardSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMPerpPnlLeaderboardSortOrder"},"TGMPerpPnlLeaderboardSortField":{"type":"string","enum":["pnl_usd_realised","pnl_usd_unrealised","pnl_usd_total","roi_percent_total","roi_percent_realised","roi_percent_unrealised","holding_amount","position_value_usd","max_balance_held","max_balance_held_usd","still_holding_balance_ratio","netflow_amount_usd","netflow_amount","nof_trades"],"title":"TGMPerpPnlLeaderboardSortField","description":"Enum for sortable fields in TGM Perp PnL leaderboard."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMPerpPnlLeaderboardResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMPerpPnlLeaderboard"},"type":"array","title":"Data","description":"List of TGM Perp PnL leaderboard records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TGMPerpPnlLeaderboardResponse","description":"Response model for TGM Perp PnL leaderboard endpoint.\nContains a list of PnL leaderboard records with pagination and metadata."},"TGMPerpPnlLeaderboard":{"properties":{"trader_address":{"type":"string","title":"Trader Address","description":"Hexadecimal representation of the trader's address."},"trader_address_label":{"anyOf":[{"type":"string"}],"title":"Trader Address Label","description":"Nansen name of the trader"},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Token price in USD at date_to. Uses latest spot price if date_to is today or later, otherwise the daily median price for that date."},"pnl_usd_realised":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Realised","description":"Realised profit and loss in USD."},"pnl_usd_unrealised":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Unrealised","description":"Unrealised profit and loss in USD."},"holding_amount":{"anyOf":[{"type":"number"}],"title":"Holding Amount","description":"Current token balance"},"position_value_usd":{"anyOf":[{"type":"number"}],"title":"Position Value Usd","description":"Position value in USD (+ve = Long position, -ve = Short position, 0 = Flat)"},"max_balance_held":{"anyOf":[{"type":"number"}],"title":"Max Balance Held","description":"Maximum amount of tokens held at some point in time."},"max_balance_held_usd":{"anyOf":[{"type":"number"}],"title":"Max Balance Held Usd","description":"Maximum amount of tokens in current USD value, held at some point in time."},"still_holding_balance_ratio":{"anyOf":[{"type":"number"}],"title":"Still Holding Balance Ratio","description":"The ratio of current holdings to max balance held."},"netflow_amount_usd":{"anyOf":[{"type":"number"}],"title":"Netflow Amount Usd","description":"Netflow amount in USD."},"netflow_amount":{"anyOf":[{"type":"number"}],"title":"Netflow Amount","description":"Netflow amount."},"roi_percent_total":{"anyOf":[{"type":"number"}],"title":"Roi Percent Total","description":"Total ROI."},"roi_percent_realised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Realised","description":"Realised ROI."},"roi_percent_unrealised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Unrealised","description":"Unrealised ROI."},"pnl_usd_total":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Total","description":"Total PNL in USD."},"nof_trades":{"anyOf":[{"type":"integer"}],"title":"Nof Trades","description":"Number of trades since the start of the requested date range, on the same window as the realised PnL."}},"type":"object","required":["trader_address"],"title":"TGMPerpPnlLeaderboard","description":"Individual TGM Perp PnL leaderboard record.\nRepresents a single trader's PnL performance for a specific perpetual contract."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/perp-pnl-leaderboard":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) perp PnL leaderboard data","description":"Rank traders by their profit/loss performance for a specific perpetual contract on Hyperliquid. Shows both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages and trading patterns. This endpoint can be used to analyze the realized and unrealized profit for each trader who traded the input perpetual contract.\n\n**Key Features:**\n- Hyperliquid perpetual contracts only (no chain field needed)\n- Realized and unrealized PnL tracking\n- ROI calculations and trading patterns\n- Position size and balance tracking\n\n**Request Format:**\n- `token_symbol`: Perpetual contract symbol (e.g., \"BTC\", \"ETH\", \"SOL\")\n- `date`: Date range for analysis\n- `filters`: Optional filters for trader addresses, PnL ranges, etc.\n- `pagination`: Page and per_page parameters\n\n**Label Tier Control (`premium_labels`):**\nWhen omitted or set to `false` (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing `premium_labels=true` returns premium labels (Smart Money, Fund, and other advanced labels), is billed at **150 credits per call**, and requires a paid plan.","operationId":"get_tgm_perp_pnl_leaderboard_api_v1_tgm_perp_pnl_leaderboard_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPerpPnlLeaderboardRequest"}}},"required":true},"responses":{"200":{"description":"TGM Perp PnL leaderboard data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPerpPnlLeaderboardResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Perp Positions ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Returns a **current, point-in-time snapshot** of open positions for the token — there is no date-range parameter or historical look-back, and values reflect within the standard live latency. ## Get "Token God Mode" (TGM) perp positions data > Retrieve current perpetual positions for a specific token on Hyperliquid. Shows active positions with detailed metrics including entry price, mark price, leverage, PnL, and liquidation price.\ > \ > \*\*Key Features:\*\*\ > \- Hyperliquid perpetual contracts only (no chain field needed)\ > \- Real-time position tracking with live PnL calculations\ > \- Leverage and margin information\ > \- Smart money filtering capabilities\ > \- Support for both Long and Short positions\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*What are the current perp positions for a specific token?\*\*\ > 2\. \*\*Which addresses have the largest positions by value?\*\*\ > 3\. \*\*What are the unrealized gains/losses on current positions?\*\*\ > 4\. \*\*What leverage levels are traders using?\*\*\ > 5\. \*\*Which smart money wallets are holding positions?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMPerpPositionsRequest":{"properties":{"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"label_type":{"$ref":"#/components/schemas/TGMPerpPositionsLabel","description":"Label type filter","default":"all_traders"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMPerpPositionsFilters"}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMPerpPositionsSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"position_value_usd\", \"direction\": \"DESC\"}] - Sort by position value USD descending\n- [{\"field\": \"upnl_usd\", \"direction\": \"ASC\"}] - Sort by unrealized PnL ascending\n- [{\"field\": \"leverage\", \"direction\": \"DESC\"}] - Sort by leverage descending\n- [{\"field\": \"size_base\", \"direction\": \"DESC\"}] - Sort by absolute position size descending, longs and shorts together\n\n`position_size` is signed (a short is negative), so a sort on it ranks every long above every short. `size_base` sorts both sides by the size of the position."}},"additionalProperties":false,"type":"object","required":["token_symbol"],"title":"TGMPerpPositionsRequest","description":"Request model for TGM perp positions endpoint.\n\nThis endpoint provides perp positions data for a specific token."},"TGMPerpPositionsLabel":{"type":"string","enum":["smart_money","all_traders","whale","public_figure"],"title":"TGMPerpPositionsLabel","description":"TGM perp positions label types."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMPerpPositionsFilters":{"properties":{"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Include smart money labels for traders"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels for traders"},"address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Address","description":"Trader address filter"},"address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Address Label","description":"Trader label filter"},"side":{"anyOf":[{"$ref":"#/components/schemas/PositionSide"},{"items":{"$ref":"#/components/schemas/PositionSide"},"type":"array"},{"type":"null"}],"title":"Side","description":"Position side filter (Long or Short)"},"position_value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Position value range filter in USD"},"position_size":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Position size range filter (token amount)"},"entry_price":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Entry price range filter"},"upnl_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Unrealized PnL range filter in USD"},"funding_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Funding range filter in USD"}},"additionalProperties":false,"type":"object","title":"TGMPerpPositionsFilters","description":"Filters for TGM perp positions endpoint.\n\nThese filters control which perp positions are included in the analysis."},"LabelType":{"type":"string","enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"title":"LabelType","description":"Filter by entity label type."},"PositionSide":{"type":"string","enum":["Long","Short"],"title":"PositionSide","description":"Shared enum for position side direction."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"TGMPerpPositionsSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMPerpPositionsSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMPerpPositionsSortOrder"},"TGMPerpPositionsSortField":{"type":"string","enum":["address","address_label","side","position_value_usd","position_size","size_base","leverage","entry_price","mark_price","liquidation_price","funding_usd","upnl_usd"],"title":"TGMPerpPositionsSortField","description":"Enum for sortable fields in TGM perp positions."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMPerpPositionsResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMPerpPosition"},"type":"array","title":"Data","description":"List of TGM perp position records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TGMPerpPositionsResponse","description":"Response model for TGM perp positions endpoint.\n\nContains a list of perp position records with pagination and metadata."},"TGMPerpPosition":{"properties":{"address":{"anyOf":[{"type":"string"}],"title":"Address","description":"The wallet address of the trader."},"address_label":{"anyOf":[{"type":"string"}],"title":"Address Label","description":"Wallet or labeled entity holding the position."},"side":{"anyOf":[{"$ref":"#/components/schemas/PositionSide"}],"description":"Position direction (Long/Short)"},"position_value_usd":{"anyOf":[{"type":"number"}],"title":"Position Value Usd","description":"USD notional size of the position."},"position_size":{"anyOf":[{"type":"number"}],"title":"Position Size","description":"The position size (token amount)."},"leverage":{"type":"string","title":"Leverage","description":"The leverage applied to the position."},"leverage_type":{"anyOf":[{"type":"string"}],"title":"Leverage Type","description":"The type of leverage used, e.g., cross or isolated."},"entry_price":{"anyOf":[{"type":"number"}],"title":"Entry Price","description":"Average price where the position was opened."},"mark_price":{"anyOf":[{"type":"number"}],"title":"Mark Price","description":"The current mark price of the asset."},"liquidation_price":{"anyOf":[{"type":"number"}],"title":"Liquidation Price","description":"The price at which the position would be liquidated."},"funding_usd":{"anyOf":[{"type":"number"}],"title":"Funding Usd","description":"Net funding paid (-) or received (+) since entry."},"upnl_usd":{"anyOf":[{"type":"number"}],"title":"Upnl Usd","description":"Unrealized profit/loss including funding."}},"type":"object","required":["leverage"],"title":"TGMPerpPosition","description":"Individual TGM perp position record.\n\nRepresents a single perp position."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/perp-positions":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) perp positions data","description":"Retrieve current perpetual positions for a specific token on Hyperliquid. Shows active positions with detailed metrics including entry price, mark price, leverage, PnL, and liquidation price.\n\n**Key Features:**\n- Hyperliquid perpetual contracts only (no chain field needed)\n- Real-time position tracking with live PnL calculations\n- Leverage and margin information\n- Smart money filtering capabilities\n- Support for both Long and Short positions\n\n**What it helps to answer:**\n\n1. **What are the current perp positions for a specific token?**\n2. **Which addresses have the largest positions by value?**\n3. **What are the unrealized gains/losses on current positions?**\n4. **What leverage levels are traders using?**\n5. **Which smart money wallets are holding positions?**","operationId":"get_tgm_perp_positions_api_v1_tgm_perp_positions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPerpPositionsRequest"}}},"required":true},"responses":{"200":{"description":"TGM perp positions data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPerpPositionsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Perp Trades ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Covers the Hyperliquid perpetuals dataset (reliable from **May 2025**), not per-chain history — see the Hyperliquid note on the coverage page. ## Get "Token God Mode" (TGM) perp trades data > Retrieve perpetual trade data for a specific token on Hyperliquid. Shows individual trades with detailed information including trader address, trade side (Long/Short), action type (Add/Reduce/Open/Close), order type (Market/Limit), and trade metrics.\ > \ > \*\*Key Features:\*\*\ > \- Hyperliquid perpetual contracts only\ > \- Smart money filtering capabilities\ > \- Detailed trade breakdown with parsed action fields\ > \- Support for both Long and Short position trading\ > \- Market and Limit order types\ > \ > \*\*Request Parameters:\*\*\ > \- \`token\_symbol\`: Token symbol to fetch trades for (e.g., "BTC", "ETH")\ > \- \`date\`: Date range for the trades\ > \- \`filters\`: Additional filters for side, action, order\_type, etc.\ > \- \`pagination\`: Page and per\_page parameters ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMPerpTradesRequest":{"properties":{"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"date":{"$ref":"#/components/schemas/DateRange","description":"ISO 8601 date-time range object with optional from and to fields"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMPerpTradesFilters"}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMPerpTradesSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"block_timestamp\", \"direction\": \"DESC\"}] - Sort by timestamp descending\n- [{\"field\": \"value_usd\", \"direction\": \"DESC\"}] - Sort by trade value descending\n\nDefault: block_timestamp DESC, transaction_hash ASC, trader_address ASC (ensures stable pagination and prevents duplicate rows)"}},"additionalProperties":false,"type":"object","required":["token_symbol","date"],"title":"TGMPerpTradesRequest","description":"Request model for TGM perp trades endpoint.\n\nThis endpoint provides perp trades data for a specific token."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMPerpTradesFilters":{"properties":{"trader_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address","description":"Trader address filter"},"trader_address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address Label","description":"Trader label filter"},"side":{"anyOf":[{"$ref":"#/components/schemas/PositionSide"},{"items":{"$ref":"#/components/schemas/PositionSide"},"type":"array"},{"type":"null"}],"title":"Side","description":"Position side filter (Long or Short)"},"action":{"anyOf":[{"$ref":"#/components/schemas/PerpActionType"},{"items":{"$ref":"#/components/schemas/PerpActionType"},"type":"array"},{"type":"null"}],"title":"Action","description":"Action filter with combined buy/sell direction (e.g., 'Buy - Add Long', 'Sell - Reduce Long')"},"order_type":{"anyOf":[{"$ref":"#/components/schemas/OrderType"},{"items":{"$ref":"#/components/schemas/OrderType"},"type":"array"},{"type":"null"}],"title":"Order Type","description":"Order type filter (MARKET or LIMIT)"},"token_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token amount range filter"},"price_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Price range filter in USD"},"value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Trade value range filter in USD"},"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Include smart money labels"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels"}},"additionalProperties":false,"type":"object","title":"TGMPerpTradesFilters","description":"Filters for TGM perp trades endpoint.\n\nThese filters control which perp trades are included in the results."},"PositionSide":{"type":"string","enum":["Long","Short"],"title":"PositionSide","description":"Shared enum for position side direction."},"PerpActionType":{"type":"string","enum":["Buy - Add Long","Buy - Reduce Short","Buy - Open Long","Buy - Close Short","Sell - Add Short","Sell - Reduce Long","Sell - Open Short","Sell - Close Long"],"title":"PerpActionType","description":"Shared enum for perpetual trade action types (combined buy/sell with position actions)."},"OrderType":{"type":"string","enum":["MARKET","LIMIT"],"title":"OrderType","description":"Order type."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Filter by smart money label type."},"TGMPerpTradesSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMPerpTradesSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMPerpTradesSortOrder"},"TGMPerpTradesSortField":{"type":"string","enum":["block_timestamp","token_amount","value_usd","transaction_hash","trader_address"],"title":"TGMPerpTradesSortField","description":"Enum for sortable fields in TGM perp trades."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMPerpTradesResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMPerpTrade"},"type":"array","title":"Data","description":"List of TGM perp trade records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TGMPerpTradesResponse","description":"Response model for TGM perp trades endpoint.\n\nContains a list of perp trade records with pagination and metadata."},"TGMPerpTrade":{"properties":{"trader_address_label":{"anyOf":[{"type":"string"}],"title":"Trader Address Label","description":"The label associated with the trader"},"trader_address":{"type":"string","title":"Trader Address","description":"The trader's address"},"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","description":"The symbol of the token"},"side":{"anyOf":[{"$ref":"#/components/schemas/PositionSide"}],"description":"The side of the position (Long or Short)"},"action":{"type":"string","title":"Action","description":"The action taken by the trader (Add, Reduce, Open, Close)"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"The amount of the specified token traded"},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Average fill price in USD across all fills in the trade, from exchange data."},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"The value in USD"},"type":{"$ref":"#/components/schemas/OrderType","description":"The order type (MARKET or LIMIT)"},"block_timestamp":{"type":"string","title":"Block Timestamp","description":"The block timestamp for the transaction"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"A representative transaction hash for this trade. Note: A single row may aggregate multiple fills that occurred at the same timestamp. If the trader had fills across multiple transactions at the exact same millisecond, only one transaction_hash is shown. The token_amount and value_usd reflect the total across all fills."}},"type":"object","required":["trader_address","action","type","block_timestamp","transaction_hash"],"title":"TGMPerpTrade","description":"Individual TGM perp trade record.\n\nRepresents a single perp trade with parsed action fields."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/perp-trades":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) perp trades data","description":"Retrieve perpetual trade data for a specific token on Hyperliquid. Shows individual trades with detailed information including trader address, trade side (Long/Short), action type (Add/Reduce/Open/Close), order type (Market/Limit), and trade metrics.\n\n**Key Features:**\n- Hyperliquid perpetual contracts only\n- Smart money filtering capabilities\n- Detailed trade breakdown with parsed action fields\n- Support for both Long and Short position trading\n- Market and Limit order types\n\n**Request Parameters:**\n- `token_symbol`: Token symbol to fetch trades for (e.g., \"BTC\", \"ETH\")\n- `date`: Date range for the trades\n- `filters`: Additional filters for side, action, order_type, etc.\n- `pagination`: Page and per_page parameters","operationId":"get_tgm_perp_trades_api_v1_tgm_perp_trades_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPerpTradesRequest"}}},"required":true},"responses":{"200":{"description":"TGM perp trades data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPerpTradesResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Portfolio DeFi Holdings API tracks active positions across DeFi protocols. ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Returns a **current, point-in-time snapshot** of active DeFi positions across all chains and protocols — there is no date-range parameter or historical look-back; balances, rewards, and debt update continuously off on-chain activity and reflect within the standard live latency. ## Get Portfolio DeFi Holdings Data > Get simplified DeFi holdings for a wallet address with aggregated tokens\ > and protocol summaries in a user-friendly format. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"}},"schemas":{"PortfolioDefiHoldingsRequest":{"properties":{"wallet_address":{"type":"string","title":"Wallet Address","description":"Wallet address to get DeFi holdings for"},"address":{"anyOf":[{"type":"string"}],"title":"Address","description":"Deprecated: Use 'wallet_address' instead. Alias of `wallet_address`. If you send both fields, they must contain the same address.","deprecated":true}},"type":"object","required":["wallet_address"],"title":"PortfolioDefiHoldingsRequest","description":"Request model for portfolio DeFi holdings endpoint."},"PortfolioDefiHoldingsResponse":{"properties":{"summary":{"$ref":"#/components/schemas/HoldingsSummary","description":"Overall portfolio summary"},"protocols":{"items":{"$ref":"#/components/schemas/ProtocolHolding"},"type":"array","title":"Protocols","description":"Protocol-specific holdings with token breakdown"}},"type":"object","required":["summary","protocols"],"title":"PortfolioDefiHoldingsResponse","description":"Response model for portfolio DeFi holdings endpoint."},"HoldingsSummary":{"properties":{"total_value_usd":{"type":"number","title":"Total Value Usd","description":"Total USD value of all holdings"},"total_assets_usd":{"type":"number","title":"Total Assets Usd","description":"Total USD value of all assets"},"total_debts_usd":{"type":"number","title":"Total Debts Usd","description":"Total USD value of all debts"},"total_rewards_usd":{"type":"number","title":"Total Rewards Usd","description":"Total USD value of all rewards"},"token_count":{"type":"integer","title":"Token Count","description":"Total number of unique tokens"},"protocol_count":{"type":"integer","title":"Protocol Count","description":"Total number of protocols"}},"type":"object","required":["total_value_usd","total_assets_usd","total_debts_usd","total_rewards_usd","token_count","protocol_count"],"title":"HoldingsSummary","description":"Summary statistics for DeFi holdings."},"ProtocolHolding":{"properties":{"protocol_name":{"type":"string","title":"Protocol Name","description":"User-friendly protocol name"},"chain":{"type":"string","title":"Chain","description":"Blockchain network"},"total_value_usd":{"type":"number","title":"Total Value Usd","description":"Total USD value in this protocol"},"total_assets_usd":{"type":"number","title":"Total Assets Usd","description":"Total USD value of assets in this protocol"},"total_debts_usd":{"type":"number","title":"Total Debts Usd","description":"Total USD value of debts in this protocol"},"total_rewards_usd":{"type":"number","title":"Total Rewards Usd","description":"Total USD value of rewards in this protocol"},"tokens":{"items":{"$ref":"#/components/schemas/ProtocolToken"},"type":"array","title":"Tokens","description":"Token holdings in this protocol"}},"type":"object","required":["protocol_name","chain","total_value_usd","total_assets_usd","total_debts_usd","total_rewards_usd","tokens"],"title":"ProtocolHolding","description":"Holdings summary for a specific protocol."},"ProtocolToken":{"properties":{"address":{"anyOf":[{"type":"string"}],"title":"Address","description":"Token contract address (null for native tokens)"},"symbol":{"anyOf":[{"type":"string"}],"title":"Symbol","description":"Token symbol"},"amount":{"anyOf":[{"type":"number"}],"title":"Amount","description":"Token amount"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"USD value"},"position_type":{"type":"string","title":"Position Type","description":"Position type: deposit, stake, borrow, or mixed"}},"type":"object","required":["symbol","amount","value_usd","position_type"],"title":"ProtocolToken","description":"Individual token holding within a protocol."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/portfolio/defi-holdings":{"post":{"tags":["Portfolio"],"summary":"Get Portfolio DeFi Holdings Data","description":"Get simplified DeFi holdings for a wallet address with aggregated tokens\n and protocol summaries in a user-friendly format.","operationId":"portfolio_defi_holdings_v1_api_v1_portfolio_defi_holdings_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioDefiHoldingsRequest"}}},"required":true},"responses":{"200":{"description":"Portfolio DeFi holdings data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioDefiHoldingsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` ### Output Field Meanings #### Top-Level Fields | Field | Description | | -------------------- | --------------------------------------------------------------------------- | | `protocolsUsed` | Array of protocol names the wallet actively uses (e.g., "aave-v3-ethereum") | | `holdingsByProtocol` | Detailed breakdown of positions per protocol | | `success` | Boolean indicating API call success | | `totalProtocols` | Count of protocols with detected activity | #### Position Types within `holdingsByProtocol` | Type | Description | | --------------------- | -------------------------------------------------------------------------------------------- | | `deposits`/`lendings` | Assets supplied to lending protocols (Aave, Compound), including amounts, value, and rewards | | `borrows` | Borrowed assets with debt ratios and health factors | | `stakings` | Tokens staked for rewards (liquid staking, governance tokens) | | `positions` | Complex positions like LP tokens, derivatives, or structured products | | `locked` | Time-locked or vested tokens (e.g., vote-escrowed tokens) | | `rewards` | Claimable but unclaimed protocol rewards | | `farms` | Yield farming positions with staked LP tokens | #### Position Detail Structure | Field | Description | | --------- | --------------------------------------------------------------------------------- | | `type` | Position category (e.g., "lending", "common", "locked") | | `summary` | High-level metrics (asset value, rewards, debt) | | `detail` | Granular breakdown including individual token balances, prices, and price changes | ## Supported Protocols You can find the list of supported protocols on each supported chain by [clicking here](https://app.nansen.ai/portfolio/protocols). ## Usage Guide: Creating Complete Portfolio Overview Use the following steps to create a complete Portfolio Overview: **Step 1: Fetch DeFi Positions**\ Get active protocol positions, staking rewards, and lending activities. This shows how assets are being used in DeFi. **Step 2: Fetch Wallet Balances** [**(Link Here)**](https://docs.nansen.ai/api/profiler/balances#post-beta-profiler-address-balances)\ Retrieve all token holdings across chains, including idle tokens not actively deployed in protocols. **Step 3: Combine & Analyze** * Total Portfolio Value = DeFi positions + wallet balances * Strategy Analysis: Compare liquid vs. staked vs. lending positions * Chain Distribution: Identify multi-chain allocation patterns * Risk Assessment: Analyze borrowing ratios, protocol concentration # Chain Rank ## Get chain growth rankings > Get aggregated growth metrics for all supported chains, ranked by gas fees.\ > \ > Returns one entry per chain with transaction counts, DEX volume, active addresses,\ > revenue, and TVL for the selected time frame. Use \`chain\_type=evm\` to restrict\ > results to EVM-compatible chains.\ > \ > \*\*Time frames\*\*: \`7\` (7-day), \`30\` (30-day), \`365\` (365-day).\ > \ > \*\*Notes\*\*:\ > \- \`successful\_transaction\_count\` and \`successful\_transaction\_count\_percent\_change\` are \`null\` for algorand, bitcoin, and ton.\ > \- \`total\_dex\_volume\_usd\` and \`total\_dex\_volume\_usd\_percent\_change\` are \`null\` for algorand, aptos, bitcoin, near, stellar, and ton.\ > \- Results are sorted by \`total\_gas\_used\_usd\` descending. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"ChainRankRequest":{"properties":{"time_frame":{"$ref":"#/components/schemas/ChainRankTimeFrame","default":7},"chain_type":{"$ref":"#/components/schemas/ChainRankChainType","default":"all"}},"type":"object","title":"ChainRankRequest"},"ChainRankTimeFrame":{"type":"integer","enum":[7,30,365],"title":"ChainRankTimeFrame","description":"Supported time frames for chain rank queries."},"ChainRankChainType":{"type":"string","enum":["all","evm"],"title":"ChainRankChainType","description":"Chain type filter for chain rank queries."},"ChainRankListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ChainRankResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"ChainRankListResponse"},"ChainRankResponse":{"properties":{"chain":{"type":"string","title":"Chain"},"transaction_count":{"anyOf":[{"type":"integer"}],"title":"Transaction Count"},"transaction_count_percent_change":{"anyOf":[{"type":"number"}],"title":"Transaction Count Percent Change"},"successful_transaction_count":{"anyOf":[{"type":"integer"}],"title":"Successful Transaction Count"},"successful_transaction_count_percent_change":{"anyOf":[{"type":"number"}],"title":"Successful Transaction Count Percent Change"},"total_gas_used_usd":{"anyOf":[{"type":"number"}],"title":"Total Gas Used Usd"},"total_gas_used_usd_percent_change":{"anyOf":[{"type":"number"}],"title":"Total Gas Used Usd Percent Change"},"total_dex_volume_usd":{"anyOf":[{"type":"number"}],"title":"Total Dex Volume Usd"},"total_dex_volume_usd_percent_change":{"anyOf":[{"type":"number"}],"title":"Total Dex Volume Usd Percent Change"},"active_address_count_traces":{"anyOf":[{"type":"integer"}],"title":"Active Address Count Traces"},"active_address_count_traces_percent_change":{"anyOf":[{"type":"number"}],"title":"Active Address Count Traces Percent Change"},"active_address_count_txs":{"anyOf":[{"type":"integer"}],"title":"Active Address Count Txs"},"active_address_count_txs_percent_change":{"anyOf":[{"type":"number"}],"title":"Active Address Count Txs Percent Change"},"revenue_usd":{"anyOf":[{"type":"number"}],"title":"Revenue Usd"},"revenue_usd_percent_change":{"anyOf":[{"type":"number"}],"title":"Revenue Usd Percent Change"},"tvl_usd":{"anyOf":[{"type":"number"}],"title":"Tvl Usd"},"tvl_usd_percent_change":{"anyOf":[{"type":"number"}],"title":"Tvl Usd Percent Change"}},"type":"object","required":["chain"],"title":"ChainRankResponse"},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/chains/chain-rank":{"post":{"tags":["Growth"],"summary":"Get chain growth rankings","description":"Get aggregated growth metrics for all supported chains, ranked by gas fees.\n\nReturns one entry per chain with transaction counts, DEX volume, active addresses,\nrevenue, and TVL for the selected time frame. Use `chain_type=evm` to restrict\nresults to EVM-compatible chains.\n\n**Time frames**: `7` (7-day), `30` (30-day), `365` (365-day).\n\n**Notes**:\n- `successful_transaction_count` and `successful_transaction_count_percent_change` are `null` for algorand, bitcoin, and ton.\n- `total_dex_volume_usd` and `total_dex_volume_usd_percent_change` are `null` for algorand, aptos, bitcoin, near, stellar, and ton.\n- Results are sorted by `total_gas_used_usd` descending.","operationId":"get_chain_rank_api_v1_chains_chain_rank_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChainRankRequest"}}},"required":true},"responses":{"200":{"description":"Chain growth rankings data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChainRankListResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Agent ## Interact with the Nansen Research Agent in "fast" mode > Ask the Nansen AI agent a research question and receive a streamed answer backed by on-chain data. The \*\*fast\*\* variant uses a lighter model optimised for low-latency responses.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*Which tokens are smart money accumulating right now?\*\*\ > 2\. \*\*What is the current narrative driving activity in DeFi?\*\*\ > 3\. \*\*Which wallets are connected to a specific address?\*\*\ > 4\. \*\*What is the on-chain story behind a recent price move?\*\*\ > \ > \*\*SSE event types:\*\*\ > \ > The response is a \`text/event-stream\` with the following JSON event types:\ > \ > \| type | payload | description |\ > \|---|---|---|\ > \| \`delta\` | \`{"type": "delta", "text": "…"}\` | Incremental text chunk of the agent's answer. |\ > \| \`tool\_call\` | \`{"type": "tool\_call", "name": "…"}\` | Emitted once per unique Nansen tool the agent invokes. |\ > \| \`finish\` | \`{"type": "finish", "conversation\_id": "…", "tool\_calls": \[...]}\` | Final event. Contains the \`conversation\_id\` for follow-up requests and the full list of tools used. |\ > \| \`error\` | \`{"type": "error", "error": "…", "status\_code": …}\` | Emitted if the upstream agent service is unavailable or times out. |\ > \ > The stream terminates with a \`data: \[DONE]\` sentinel.\ > \ > \*\*Fast vs Expert:\*\* Use \`/agent/fast\` for quick factual lookups and simple questions. Use \`/agent/expert\` when you need deeper multi-step analysis or synthesis across multiple data sources. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"AgentResearchRequest":{"properties":{"text":{"type":"string","minLength":1,"title":"Text","description":"Research query or question for the Nansen AI agent."},"conversation_id":{"anyOf":[{"type":"string"}],"title":"Conversation Id","description":"Optional conversation ID for multi-turn interactions. Returned in the finish event of a previous response. Omit to start a new conversation."}},"type":"object","required":["text"],"title":"AgentResearchRequest","description":"Request model for Agent Research endpoints (fast and expert)."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/agent/fast":{"post":{"tags":["Agent"],"summary":"Interact with the Nansen Research Agent in \"fast\" mode","description":"Ask the Nansen AI agent a research question and receive a streamed answer backed by on-chain data. The **fast** variant uses a lighter model optimised for low-latency responses.\n\n**What it helps to answer:**\n\n1. **Which tokens are smart money accumulating right now?**\n2. **What is the current narrative driving activity in DeFi?**\n3. **Which wallets are connected to a specific address?**\n4. **What is the on-chain story behind a recent price move?**\n\n**SSE event types:**\n\nThe response is a `text/event-stream` with the following JSON event types:\n\n| type | payload | description |\n|---|---|---|\n| `delta` | `{\"type\": \"delta\", \"text\": \"…\"}` | Incremental text chunk of the agent's answer. |\n| `tool_call` | `{\"type\": \"tool_call\", \"name\": \"…\"}` | Emitted once per unique Nansen tool the agent invokes. |\n| `finish` | `{\"type\": \"finish\", \"conversation_id\": \"…\", \"tool_calls\": [...]}` | Final event. Contains the `conversation_id` for follow-up requests and the full list of tools used. |\n| `error` | `{\"type\": \"error\", \"error\": \"…\", \"status_code\": …}` | Emitted if the upstream agent service is unavailable or times out. |\n\nThe stream terminates with a `data: [DONE]` sentinel.\n\n**Fast vs Expert:** Use `/agent/fast` for quick factual lookups and simple questions. Use `/agent/expert` when you need deeper multi-step analysis or synthesis across multiple data sources.","operationId":"agent_fast_api_v1_agent_fast_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResearchRequest"}}},"required":true},"responses":{"200":{"description":"Server-Sent Events stream. Each event is a `data: {json}` line. See endpoint description for event schema.","content":{"application/json":{"schema":{}},"text/event-stream":{}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` ## Interact with the Nansen Research Agent in "expert" mode > Ask the Nansen AI agent a research question and receive a streamed answer backed by on-chain data. The \*\*expert\*\* variant uses a more capable model for deeper, multi-step analysis.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*Which tokens are smart money accumulating right now?\*\*\ > 2\. \*\*What is the current narrative driving activity in DeFi?\*\*\ > 3\. \*\*Which wallets are connected to a specific address?\*\*\ > 4\. \*\*What is the on-chain story behind a recent price move?\*\*\ > \ > \*\*SSE event types:\*\*\ > \ > The response is a \`text/event-stream\` with the following JSON event types:\ > \ > \| type | payload | description |\ > \|---|---|---|\ > \| \`delta\` | \`{"type": "delta", "text": "…"}\` | Incremental text chunk of the agent's answer. |\ > \| \`tool\_call\` | \`{"type": "tool\_call", "name": "…"}\` | Emitted once per unique Nansen tool the agent invokes. |\ > \| \`finish\` | \`{"type": "finish", "conversation\_id": "…", "tool\_calls": \[...]}\` | Final event. Contains the \`conversation\_id\` for follow-up requests and the full list of tools used. |\ > \| \`error\` | \`{"type": "error", "error": "…", "status\_code": …}\` | Emitted if the upstream agent service is unavailable or times out. |\ > \ > The stream terminates with a \`data: \[DONE]\` sentinel.\ > \ > \*\*Fast vs Expert:\*\* Use \`/agent/fast\` for quick factual lookups and simple questions. Use \`/agent/expert\` when you need deeper multi-step analysis or synthesis across multiple data sources. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"AgentResearchRequest":{"properties":{"text":{"type":"string","minLength":1,"title":"Text","description":"Research query or question for the Nansen AI agent."},"conversation_id":{"anyOf":[{"type":"string"}],"title":"Conversation Id","description":"Optional conversation ID for multi-turn interactions. Returned in the finish event of a previous response. Omit to start a new conversation."}},"type":"object","required":["text"],"title":"AgentResearchRequest","description":"Request model for Agent Research endpoints (fast and expert)."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/agent/expert":{"post":{"tags":["Agent"],"summary":"Interact with the Nansen Research Agent in \"expert\" mode","description":"Ask the Nansen AI agent a research question and receive a streamed answer backed by on-chain data. The **expert** variant uses a more capable model for deeper, multi-step analysis.\n\n**What it helps to answer:**\n\n1. **Which tokens are smart money accumulating right now?**\n2. **What is the current narrative driving activity in DeFi?**\n3. **Which wallets are connected to a specific address?**\n4. **What is the on-chain story behind a recent price move?**\n\n**SSE event types:**\n\nThe response is a `text/event-stream` with the following JSON event types:\n\n| type | payload | description |\n|---|---|---|\n| `delta` | `{\"type\": \"delta\", \"text\": \"…\"}` | Incremental text chunk of the agent's answer. |\n| `tool_call` | `{\"type\": \"tool_call\", \"name\": \"…\"}` | Emitted once per unique Nansen tool the agent invokes. |\n| `finish` | `{\"type\": \"finish\", \"conversation_id\": \"…\", \"tool_calls\": [...]}` | Final event. Contains the `conversation_id` for follow-up requests and the full list of tools used. |\n| `error` | `{\"type\": \"error\", \"error\": \"…\", \"status_code\": …}` | Emitted if the upstream agent service is unavailable or times out. |\n\nThe stream terminates with a `data: [DONE]` sentinel.\n\n**Fast vs Expert:** Use `/agent/fast` for quick factual lookups and simple questions. Use `/agent/expert` when you need deeper multi-step analysis or synthesis across multiple data sources.","operationId":"agent_expert_api_v1_agent_expert_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResearchRequest"}}},"required":true},"responses":{"200":{"description":"Server-Sent Events stream. Each event is a `data: {json}` line. See endpoint description for event schema.","content":{"application/json":{"schema":{}},"text/event-stream":{}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Trading Nansen's Trading API endpoints cover spot swaps and Hyperliquid perpetual trading. Both flows keep signing on your side: Nansen prepares unsigned transaction or action data, you sign locally, and you submit the signed payload. ## Choose a trading flow | I want to... | Start here | Endpoint reference | | --------------------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Swap tokens on Solana or Base, including supported cross-chain routes | [Spot Trading](/api/trade/spot-trading) | [Quote](/api/trade/spot-trading/quote), [Prepare](/api/trade/spot-trading/prepare), [Execute](/api/trade/spot-trading/execute), [Bridge Status](/api/trade/spot-trading/bridge-status) | | Open, manage or close Hyperliquid perpetual positions | [Perpetual Trading](/api/trade/perp-trading) | [Perpetual Trading reference](/api/trade/perp-trading/perpetual-trading-reference) | ## Spot Trading Use Spot Trading to quote and execute token swaps against onchain liquidity. It supports same-chain swaps and supported bridge routes between `solana` and `base`. The spot flow is: 1. [Quote](/api/trade/spot-trading/quote) a swap route. 2. [Prepare](/api/trade/spot-trading/prepare) the selected quote when a separate signable transaction is needed. 3. Sign locally. 4. [Execute](/api/trade/spot-trading/execute) the signed transaction. 5. [Check bridge status](/api/trade/spot-trading/bridge-status) for cross-chain routes. Read the [Spot Trading guide](/api/trade/spot-trading) for supported chains, amount units, signing details and availability. ## Perpetual Trading Use Perpetual Trading to place orders, manage positions, move USDC between balances, and bridge funds for Hyperliquid perpetuals. The perpetual trading flow is: 1. Prepare the action you want to take. 2. Sign the returned typed data locally. 3. Submit the signed action with [Submit a signed perp action](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-execute.md). Read the [Perpetual Trading guide](/api/trade/perp-trading) before placing orders. It covers builder-fee approval, funding, signing families, execution, error handling, costs and availability. # Spot Trading Nansen's Spot Trading API endpoints let you execute token swaps directly against onchain liquidity. Get a quote across aggregators, sign it with your own keys, and broadcast it -- same-chain or across chains. Your keys never leave your side: Nansen returns unsigned transaction data, you sign locally, and you send back the signed payload to broadcast. ### What can you do? With Spot Trading endpoints, you can: * **Get the best available quote:** compare routes across multiple aggregators in one call * **Swap on the same chain:** trade between the native token, USDC, and other supported tokens * **Bridge across chains:** move value between Solana and Base in a single quoted route * **Broadcast and track:** submit your signed transaction and follow a cross-chain transfer to completion ### Which endpoints can I use? | I want to... | Use this endpoint | Best for | | ------------------------------------------------- | ------------------------------------------------------ | ------------------------------------- | | Price a swap and compare routes | [Quote](/api/trade/spot-trading/quote) | Route discovery and pre-trade pricing | | Turn the quote I picked into something signable | [Prepare](/api/trade/spot-trading/prepare) | One signing path for every route | | Broadcast a transaction I have signed | [Execute](/api/trade/spot-trading/execute) | Trade submission | | Follow a cross-chain swap through to the far side | [Bridge Status](/api/trade/spot-trading/bridge-status) | Monitoring bridges after execution | ### The trading flow 1. **Quote** -- call Quote with the chain, token pair, amount, and your wallet address. You get back one or more quotes to compare. 2. **Prepare** -- send the quote you picked to Prepare. You get back a transaction built and ready to sign, with a fresh blockhash on Solana and a simulation already run against it. 3. **Sign** -- sign it locally with your own key. Nansen never receives your private key. 4. **Execute** -- send the signed payload to Execute. The response reports the transaction hash and status. 5. **Bridge Status** -- for a cross-chain swap, poll Bridge Status with the source-chain transaction hash until the destination side completes. Prepare is optional for same-chain swaps, whose quotes already carry signable transaction data, but it is **required for swaps out of Solana to another chain**. Preferring it everywhere means one signing path instead of one per route. ### Supported chains and pairs Trading supports `solana` and `base`, both same-chain and between the two. At least one side of a swap must be USDC or the chain's native token (SOL or ETH). To go from one non-native token to another, swap to USDC first and then out again. Cross-chain routes need a minimum trade size of roughly $5, and liquidity for a given pair and direction is not guaranteed -- if no aggregator can route it you will get a "no quotes available" response rather than a worse price. ### Amounts are in base units `amount` is always an integer string in the token's smallest unit, never a decimal: | You want to trade | Pass | | ----------------- | --------------------- | | 1 SOL | `1000000000` | | 1 ETH | `1000000000000000000` | | 1 USDC | `1000000` | ### Signing the transaction data The shape of the `transaction` object in a quote depends on the route, and your signing code needs to handle each case it will encounter: | Route | What you get | How to sign | | ---------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | Base, same-chain or outbound | A standard EVM transaction (`to`, `data`, `value`, `gas`, `chainId`) | Sign with any EVM signer; send the `0x`-prefixed signed hex to Execute | | Solana, same-chain | A serialized transaction in `data` | Deserialize, sign, and send the base64-encoded signed transaction to Execute | | Solana, outbound cross-chain | Routing instructions, not a transaction | **Not signable directly -- use Prepare** | Passing every quote through Prepare avoids this entirely: it returns one shape per chain regardless of route, and it applies the network fee floor that keeps Solana bridge transactions from being dropped while they wait to be included. ### Retrying safely Execute is the one step you cannot take back, and it has no duplicate-submission key: a retried request broadcasts a second trade. A network timeout is indistinguishable from a request that never arrived, so treat any Execute whose outcome you did not see as possibly broadcast and check the wallet before resubmitting. A swap that reached the chain and reverted comes back as a `Failed` status **with** a transaction hash, not as an error. The quote is spent either way -- request a fresh one rather than retrying that trade. ### Previewing without trading Prepare simulates the transaction and reports the result in `simulationPassed` **without broadcasting anything**. That is the way to check whether a trade would succeed before committing to it. Execute has no such mode: every call to Execute broadcasts, and a successful transaction is a real trade. ### Cost and limits Trading endpoints do **not** consume plan credits -- trading costs are the onchain and routing fees on the trade itself. They carry their own per-endpoint rate limits, sized for real trading rather than for bulk quote polling. ### Availability Trading is unavailable from some jurisdictions, and wallet addresses are screened against sanctions lists before a quote is returned or a transaction is broadcast. A blocked region or a blocked address returns `403`. # Get a DEX swap quote ## Get a DEX swap quote > Get a swap quote for a same-chain or cross-chain token swap.\ > \ > Supported chains: \`solana\`, \`base\`.\ > \ > \*\*Amount:\*\* must be in base units (integer string). Convert token amounts to base units before calling:\ > \- 1 SOL = 1000000000 lamports\ > \- 1 ETH = 1000000000000000000 wei\ > \- 1 USDC = 1000000 (6 decimals on both chains)\ > \ > \*\*Tokens:\*\* pass raw contract addresses. Common addresses:\ > \- SOL native: \`So11111111111111111111111111111111111111112\`\ > \- ETH native: \`0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\`\ > \- USDC (Solana): \`EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\`\ > \- USDC (Base): \`0x833589fcd6edb6e08f4c7c32d4f71b54bda02913\`\ > \ > \*\*Restriction:\*\* at least one side must be USDC or the native token (SOL/ETH).\ > Non-native to non-native swaps are not supported — swap to USDC first.\ > \ > \*\*Cross-chain:\*\* set \`to\_chain\` for bridge swaps. Minimum \~$5 per trade. Not every pair and\ > direction can be routed — when no aggregator has a route the response is a \`400\` rather than a\ > worse price.\ > \ > \*\*Signing:\*\* pass the quote you pick to \`/api/v1/trade/prepare\` to get a transaction ready to\ > sign. That gives you one signing path for every route and applies the network fee floor that\ > keeps Solana bridge transactions from being dropped.\ > \ > The \`transaction\` field on a quote is the raw payload from the routing provider, and its shape\ > varies: a standard EVM transaction on Base, a serialized transaction for Solana same-chain, and\ > routing instructions rather than a transaction for swaps out of Solana to another chain. Signing\ > it directly works only for the first two, so \*\*swaps out of Solana to another chain must go\ > through the prepare endpoint\*\*. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"}},"schemas":{"TradingQuoteResponse":{"properties":{"quotes":{"items":{},"type":"array","title":"Quotes","description":"Available swap quotes","default":[]}},"additionalProperties":true,"type":"object","title":"TradingQuoteResponse","description":"Available swap quotes, each with unsigned transaction data ready to sign."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/trade/quote":{"get":{"tags":["Trading"],"summary":"Get a DEX swap quote","description":"Get a swap quote for a same-chain or cross-chain token swap.\n\nSupported chains: `solana`, `base`.\n\n**Amount:** must be in base units (integer string). Convert token amounts to base units before calling:\n- 1 SOL = 1000000000 lamports\n- 1 ETH = 1000000000000000000 wei\n- 1 USDC = 1000000 (6 decimals on both chains)\n\n**Tokens:** pass raw contract addresses. Common addresses:\n- SOL native: `So11111111111111111111111111111111111111112`\n- ETH native: `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`\n- USDC (Solana): `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`\n- USDC (Base): `0x833589fcd6edb6e08f4c7c32d4f71b54bda02913`\n\n**Restriction:** at least one side must be USDC or the native token (SOL/ETH).\nNon-native to non-native swaps are not supported — swap to USDC first.\n\n**Cross-chain:** set `to_chain` for bridge swaps. Minimum ~$5 per trade. Not every pair and\ndirection can be routed — when no aggregator has a route the response is a `400` rather than a\nworse price.\n\n**Signing:** pass the quote you pick to `/api/v1/trade/prepare` to get a transaction ready to\nsign. That gives you one signing path for every route and applies the network fee floor that\nkeeps Solana bridge transactions from being dropped.\n\nThe `transaction` field on a quote is the raw payload from the routing provider, and its shape\nvaries: a standard EVM transaction on Base, a serialized transaction for Solana same-chain, and\nrouting instructions rather than a transaction for swaps out of Solana to another chain. Signing\nit directly works only for the first two, so **swaps out of Solana to another chain must go\nthrough the prepare endpoint**.","operationId":"get_trading_quote_api_v1_trade_quote_get","parameters":[{"name":"chain","in":"query","required":true,"schema":{"enum":["solana","base"],"type":"string","description":"Source chain: 'solana' or 'base'","title":"Chain"},"description":"Source chain: 'solana' or 'base'"},{"name":"to_chain","in":"query","required":false,"schema":{"anyOf":[{"enum":["solana","base"],"type":"string"}],"description":"Destination chain for cross-chain swap","title":"To Chain"},"description":"Destination chain for cross-chain swap"},{"name":"from_token","in":"query","required":true,"schema":{"type":"string","description":"Sell token address","title":"From Token"},"description":"Sell token address"},{"name":"to_token","in":"query","required":true,"schema":{"type":"string","description":"Buy token address","title":"To Token"},"description":"Buy token address"},{"name":"amount","in":"query","required":true,"schema":{"type":"string","description":"Amount in base units (integer string, e.g. '1000000000')","title":"Amount"},"description":"Amount in base units (integer string, e.g. '1000000000')"},{"name":"wallet_address","in":"query","required":true,"schema":{"type":"string","description":"Wallet address for quote personalisation","title":"Wallet Address"},"description":"Wallet address for quote personalisation"},{"name":"to_wallet_address","in":"query","required":false,"schema":{"anyOf":[{"type":"string"}],"description":"Destination wallet address for cross-chain swaps (required when bridging between EVM and Solana)","title":"To Wallet Address"},"description":"Destination wallet address for cross-chain swaps (required when bridging between EVM and Solana)"},{"name":"slippage","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Slippage in bps (default 50 = 0.5%)","default":50,"title":"Slippage"},"description":"Slippage in bps (default 50 = 0.5%)"}],"responses":{"200":{"description":"Swap quotes with unsigned transaction data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradingQuoteResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"$ref":"#/components/responses/BadRequestError","description":"Bad Request"},"401":{"$ref":"#/components/responses/UnauthorizedError","description":"Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenError","description":"Forbidden"},"404":{"$ref":"#/components/responses/NotFoundError","description":"Not Found"},"422":{"$ref":"#/components/responses/ValidationError","description":"Unprocessable Content"},"429":{"$ref":"#/components/responses/TooManyRequestsError","description":"Too Many Requests"},"500":{"$ref":"#/components/responses/InternalServerError","description":"Internal Server Error"},"502":{"$ref":"#/components/responses/BadGatewayError","description":"Bad Gateway"},"503":{"$ref":"#/components/responses/ServiceUnavailableError","description":"Service Unavailable"},"504":{"$ref":"#/components/responses/GatewayTimeoutError","description":"Gateway Timeout"}}}}}} ``` # Turn a quote into a signable transaction ## Turn a quote into a signable transaction > Turn a quote into a transaction you can sign.\ > \ > Pass one quote object from the quote endpoint, unmodified, together with the wallet that will\ > sign. The response carries a transaction built and ready to sign, with a fresh blockhash on\ > Solana and a simulation already run against it.\ > \ > \- \*\*Solana:\*\* \`transaction\` is a base64-encoded serialized \`VersionedTransaction\`. Deserialize,\ > sign, and send it to the execute endpoint base64-encoded.\ > \- \*\*EVM (Base):\*\* \`swapTxData\` holds the transaction fields to sign. When \`needsApproval\` is\ > true, sign and send \`approvalTxData\` first and wait for it to confirm.\ > \ > This step is optional for same-chain swaps, where the quote already carries signable\ > transaction data — but it is \*\*required for swaps out of Solana to another chain\*\*, whose quotes\ > carry routing instructions rather than a transaction. Preferring this endpoint everywhere means\ > one signing path instead of one per route, and it applies the network fee floor that keeps\ > Solana bridge transactions from being dropped while they wait to be included.\ > \ > The transaction is not broadcast here. Send the signed result to the execute endpoint. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"}},"schemas":{"TradingPrepareRequest":{"properties":{"chain":{"type":"string","enum":["base","solana"],"title":"Chain","description":"Chain the quote is on: 'solana' or 'base'"},"wallet_address":{"type":"string","title":"Wallet Address","description":"Wallet that will sign and send the transaction"},"quote":{"additionalProperties":true,"type":"object","title":"Quote","description":"One quote object, copied verbatim from the `quotes` array returned by the quote endpoint. Do not modify it — it carries the routing data needed to rebuild the transaction."},"skip_simulation":{"type":"boolean","title":"Skip Simulation","description":"Skip the pre-signing simulation. Simulation catches failures before you spend a signature, so leave this off unless you are re-preparing a quote you have already validated.","default":false}},"type":"object","required":["chain","wallet_address","quote"],"title":"TradingPrepareRequest","description":"A quote plus the wallet that will sign it."},"TradingPrepareResponse":{"properties":{"transaction":{"anyOf":[{"type":"string"}],"title":"Transaction","description":"Serialized unsigned transaction, base64-encoded (Solana only)"},"swapTxData":{"anyOf":[{"additionalProperties":true,"type":"object"}],"title":"Swaptxdata","description":"Unsigned transaction fields to sign and send (EVM only)"},"needsApproval":{"type":"boolean","title":"Needsapproval","description":"Whether the sell token needs an approval transaction first (EVM only)","default":false},"approvalTxData":{"anyOf":[{"additionalProperties":true,"type":"object"}],"title":"Approvaltxdata","description":"Unsigned approval transaction, present only when an approval is needed"},"simulationPassed":{"anyOf":[{"type":"boolean"}],"title":"Simulationpassed","description":"Whether the pre-signing simulation succeeded, or `null` when no simulation ran. Nothing is simulated when you set `skip_simulation`, and on EVM nothing is simulated while `needsApproval` is true, because a swap always fails simulation until the approval is confirmed."}},"additionalProperties":true,"type":"object","title":"TradingPrepareResponse","description":"A signable transaction built from a quote."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/trade/prepare":{"post":{"tags":["Trading"],"summary":"Turn a quote into a signable transaction","description":"Turn a quote into a transaction you can sign.\n\nPass one quote object from the quote endpoint, unmodified, together with the wallet that will\nsign. The response carries a transaction built and ready to sign, with a fresh blockhash on\nSolana and a simulation already run against it.\n\n- **Solana:** `transaction` is a base64-encoded serialized `VersionedTransaction`. Deserialize,\n sign, and send it to the execute endpoint base64-encoded.\n- **EVM (Base):** `swapTxData` holds the transaction fields to sign. When `needsApproval` is\n true, sign and send `approvalTxData` first and wait for it to confirm.\n\nThis step is optional for same-chain swaps, where the quote already carries signable\ntransaction data — but it is **required for swaps out of Solana to another chain**, whose quotes\ncarry routing instructions rather than a transaction. Preferring this endpoint everywhere means\none signing path instead of one per route, and it applies the network fee floor that keeps\nSolana bridge transactions from being dropped while they wait to be included.\n\nThe transaction is not broadcast here. Send the signed result to the execute endpoint.","operationId":"prepare_trading_api_v1_trade_prepare_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradingPrepareRequest"}}},"required":true},"responses":{"200":{"description":"An unsigned transaction ready to sign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradingPrepareResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Broadcast a signed swap transaction ## Broadcast a signed swap transaction > Broadcast a signed swap transaction.\ > \ > The caller is responsible for signing the transaction data returned by \`/api/v1/trade/quote\`.\ > \ > \- \*\*Solana:\*\* \`signed\_transaction\` is a base64-encoded serialized \`VersionedTransaction\`\ > \- \*\*EVM (Base):\*\* \`signed\_transaction\` is a \`0x\`-prefixed signed transaction hex\ > \ > The signed transaction is broadcast as-is; the response reports the resulting transaction hash and status.\ > \ > \*\*⚠️ This endpoint always broadcasts. There is no dry-run mode.\*\* Every call that passes\ > validation submits the transaction to the network, and a successful transaction is a real\ > executed trade that moves real funds. No request field prevents that.\ > \ > The transaction is always simulated first, and the broadcast is aborted if that simulation\ > fails — so a transaction that would revert does not reach the network. Simulation passing is\ > not a preview: it is what allows the broadcast to proceed.\ > \ > A retried request broadcasts again — a network timeout is indistinguishable from a request\ > that never arrived, so check the wallet before resubmitting rather than retrying blind.\ > \ > \`status\` is \`"Success"\` or \`"Failed"\`. A swap that reached the chain and reverted is a\ > \`"Failed"\` result with a transaction hash, not an error — the trade is spent either way,\ > so request a fresh quote rather than retrying this one. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"}},"schemas":{"TradingExecuteRequest":{"properties":{"signed_transaction":{"type":"string","title":"Signed Transaction","description":"Signed transaction: base64 for Solana, 0x hex for EVM"},"chain":{"type":"string","enum":["base","solana"],"title":"Chain","description":"Chain the transaction is for: 'solana' or 'base'"},"request_id":{"anyOf":[{"type":"string"}],"title":"Request Id","description":"Jupiter request ID (Solana only)"},"aggregator":{"anyOf":[{"type":"string","enum":["jupiter","okx","lifi","relay"]}],"title":"Aggregator","description":"Aggregator that produced the quote. Defaults to `jupiter` on Solana when `request_id` is supplied, matching how a Jupiter quote is executed."}},"additionalProperties":false,"type":"object","required":["signed_transaction","chain"],"title":"TradingExecuteRequest"},"TradingExecuteResponse":{"properties":{"txHash":{"anyOf":[{"type":"string"}],"title":"Txhash","description":"Transaction hash (EVM)"},"signature":{"anyOf":[{"type":"string"}],"title":"Signature","description":"Transaction signature (Solana)"},"status":{"anyOf":[{"type":"string"}],"title":"Status","description":"Transaction status"}},"additionalProperties":true,"type":"object","title":"TradingExecuteResponse","description":"Result of broadcasting a signed swap transaction."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/trade/execute":{"post":{"tags":["Trading"],"summary":"Broadcast a signed swap transaction","description":"Broadcast a signed swap transaction.\n\nThe caller is responsible for signing the transaction data returned by `/api/v1/trade/quote`.\n\n- **Solana:** `signed_transaction` is a base64-encoded serialized `VersionedTransaction`\n- **EVM (Base):** `signed_transaction` is a `0x`-prefixed signed transaction hex\n\nThe signed transaction is broadcast as-is; the response reports the resulting transaction hash and status.\n\n**⚠️ This endpoint always broadcasts. There is no dry-run mode.** Every call that passes\nvalidation submits the transaction to the network, and a successful transaction is a real\nexecuted trade that moves real funds. No request field prevents that.\n\nThe transaction is always simulated first, and the broadcast is aborted if that simulation\nfails — so a transaction that would revert does not reach the network. Simulation passing is\nnot a preview: it is what allows the broadcast to proceed.\n\nA retried request broadcasts again — a network timeout is indistinguishable from a request\nthat never arrived, so check the wallet before resubmitting rather than retrying blind.\n\n`status` is `\"Success\"` or `\"Failed\"`. A swap that reached the chain and reverted is a\n`\"Failed\"` result with a transaction hash, not an error — the trade is spent either way,\nso request a fresh quote rather than retrying this one.","operationId":"execute_trading_api_v1_trade_execute_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradingExecuteRequest"}}},"required":true},"responses":{"200":{"description":"Execution result including transaction hash","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradingExecuteResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Check cross-chain bridge status ## Check cross-chain bridge status > Check the status of a cross-chain bridge transaction started via the trading execute endpoint.\ > \ > Pass the source-chain transaction hash from the execute response, plus the source and\ > destination chains of the swap.\ > \ > \*\*Aggregator:\*\* pass the \`aggregator\` field from the quote you executed. Status checks\ > default to \`lifi\`, and Relay transactions are not found under that default — always set\ > \`aggregator=relay\` for Relay bridges. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"}},"schemas":{"TradingBridgeStatusResponse":{"properties":{"status":{"anyOf":[{"type":"string"}],"title":"Status","description":"Bridge transaction status"},"substatus":{"anyOf":[{"type":"string"}],"title":"Substatus","description":"Bridge substatus (e.g. 'REFUNDED')"}},"additionalProperties":true,"type":"object","title":"TradingBridgeStatusResponse","description":"Progress of a cross-chain bridge transaction."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/trade/bridge-status":{"get":{"tags":["Trading"],"summary":"Check cross-chain bridge status","description":"Check the status of a cross-chain bridge transaction started via the trading execute endpoint.\n\nPass the source-chain transaction hash from the execute response, plus the source and\ndestination chains of the swap.\n\n**Aggregator:** pass the `aggregator` field from the quote you executed. Status checks\ndefault to `lifi`, and Relay transactions are not found under that default — always set\n`aggregator=relay` for Relay bridges.","operationId":"get_bridge_status_api_v1_trade_bridge_status_get","parameters":[{"name":"tx_hash","in":"query","required":true,"schema":{"type":"string","description":"Source-chain transaction hash returned by the execute endpoint","title":"Tx Hash"},"description":"Source-chain transaction hash returned by the execute endpoint"},{"name":"from_chain","in":"query","required":true,"schema":{"enum":["solana","base"],"type":"string","description":"Source chain: 'solana' or 'base'","title":"From Chain"},"description":"Source chain: 'solana' or 'base'"},{"name":"to_chain","in":"query","required":true,"schema":{"enum":["solana","base"],"type":"string","description":"Destination chain: 'solana' or 'base'","title":"To Chain"},"description":"Destination chain: 'solana' or 'base'"},{"name":"aggregator","in":"query","required":false,"schema":{"anyOf":[{"enum":["lifi","relay"],"type":"string"}],"description":"Aggregator that produced the executed quote ('lifi' or 'relay'), as returned in the quote response. Status checks default to 'lifi', and Relay transactions are not found under that default — always pass this for Relay bridges.","title":"Aggregator"},"description":"Aggregator that produced the executed quote ('lifi' or 'relay'), as returned in the quote response. Status checks default to 'lifi', and Relay transactions are not found under that default — always pass this for Relay bridges."}],"responses":{"200":{"description":"Bridge transaction status including sending and receiving details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradingBridgeStatusResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"$ref":"#/components/responses/BadRequestError","description":"Bad Request"},"401":{"$ref":"#/components/responses/UnauthorizedError","description":"Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenError","description":"Forbidden"},"404":{"$ref":"#/components/responses/NotFoundError","description":"Not Found"},"422":{"$ref":"#/components/responses/ValidationError","description":"Unprocessable Content"},"429":{"$ref":"#/components/responses/TooManyRequestsError","description":"Too Many Requests"},"500":{"$ref":"#/components/responses/InternalServerError","description":"Internal Server Error"},"502":{"$ref":"#/components/responses/BadGatewayError","description":"Bad Gateway"},"503":{"$ref":"#/components/responses/ServiceUnavailableError","description":"Service Unavailable"},"504":{"$ref":"#/components/responses/GatewayTimeoutError","description":"Gateway Timeout"}}}}}} ``` # Perpetual Trading Open, manage and close Hyperliquid perpetual positions with your own keys — the prepare, sign and execute flow end to end. This page is part of [API > Trading](/api/trade). It remains at its existing URL for compatibility with existing links. The Hyperliquid trading endpoints let you place, manage and close perpetual positions on Hyperliquid, and move USDC on and off the venue. **Your keys never leave your side.** Nansen builds an unsigned action and returns the typed data for it. You sign locally, and you send the signature back to be submitted. No endpoint ever accepts a private key, and no endpoint can act on a wallet that has not signed. These endpoints trade with real funds. Read [Availability](#availability) before you start. ### The prepare → sign → execute flow Every state change on Hyperliquid — an order, a cancel, a leverage change, a transfer, even the one-time fee approval — goes through the same three steps: 1. **Prepare.** Call the endpoint for what you want to do (`/perp/order`, `/perp/close`, `/perp/cancel`, `/perp/leverage`, `/perp/transfer`, `/perp/approve-builder-fee`). You get back an unsigned `action`, a `nonce`, and an `eip712` object. Nothing has happened on the exchange yet. 2. **Sign.** Sign the `eip712` payload locally with the wallet's key. You get an `{r, s, v}` signature. 3. **Execute.** Post `action`, `nonce` and `signature` to `/perp/execute`. This is the only call that changes anything. ``` ┌────────────┐ unsigned action ┌──────────┐ {r,s,v} ┌───────────────┐ │ prepare │ ───────────────────► │ sign │ ───────────► │ execute │ │ (6 routes) │ + eip712 │ (local) │ │ (1 route) │ └────────────┘ └──────────┘ └───────────────┘ no state change your keys real money ``` Two rules make or break this flow: * **Pass `action` and `nonce` through byte-for-byte.** They are part of what you signed. Re-serializing the JSON, reordering keys, rounding a number or "cleaning up" a field all invalidate the signature and the action is rejected. * **Don't cache a prepared payload.** `nonce` is a millisecond timestamp, so a prepare response goes stale. Prepare, sign and execute in one go; if the user takes a while to confirm, prepare again. ### Which endpoints can I use? | I want to... | Use this endpoint | Notes | | ------------------------------------------ | ------------------------------------------------------- | ------------------------------------------- | | Check the one-time fee approval | `GET /perp/builder-fee` | Do this before a wallet's first order | | Approve the builder fee | `POST /perp/approve-builder-fee` | Once per wallet, signed by the wallet's key | | Fund the account from another chain | `POST /perp/bridge/quote` | Deposit; you broadcast the transaction | | See what I can trade and at what precision | `GET /perp/meta` | Symbols, size precision, max leverage | | Set leverage or margin mode | `POST /perp/leverage` | Per asset, applies to new positions | | Open a position | `POST /perp/order` | Market or limit, optional TP/SL bracket | | Submit anything I've signed | `POST /perp/execute` | The only endpoint that changes state | | See balances and margin usage | `GET /perp/account` | Includes the spot USDC balance | | See open positions | `GET /perp/positions` | Source of truth for closing | | See resting and trigger orders | `GET /perp/orders` | Gives you the `oid` to cancel | | Cancel a resting order | `POST /perp/cancel` | One order per call | | Close a position | `POST /perp/close` | Reduce-only market order | | Move USDC between spot and perps | `POST /perp/transfer` | Only perps USDC is usable as margin | | Withdraw to another chain | `POST /perp/bridge/quote` → `POST /perp/bridge/execute` | Follow with bridge status | | Track a deposit or withdrawal | `GET /perp/bridge/status` | Poll until `success` | All paths are under `/api/v1/`. ### Before the first order: approve the builder fee Orders placed through these endpoints carry Nansen's builder code. Hyperliquid **rejects** an order carrying a builder code until the wallet has approved a maximum fee rate at least as high as the fee on that order. This is a one-time, per-wallet approval, and skipping it is the most common reason a first order fails. ```bash # 1. Check curl -s "https://api.nansen.ai/api/v1/perp/builder-fee?wallet_address=0xYourWallet" \ -H "apikey: YOUR_API_KEY" # {"approved": false, "max_fee_rate": 0, "required_fee": 80, "builder_address": "0x..."} ``` `required_fee` and `max_fee_rate` are in **tenths of a basis point**, so `80` means 8 basis points. When `approved` is false, prepare the approval, sign it, and submit it like any other action: ```bash # 2. Prepare the approval curl -s -X POST "https://api.nansen.ai/api/v1/perp/approve-builder-fee" \ -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" \ -d '{"wallet_address": "0xYourWallet"}' # 3. Sign the returned eip712 payload locally, then curl -s -X POST "https://api.nansen.ai/api/v1/perp/execute" \ -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" \ -d '{"action": {...}, "nonce": 1754476800000, "signature": {"r": "0x..", "s": "0x..", "v": 28}}' ``` The approval must be signed by the wallet's **own key**. An approval signed by an API (agent) wallet is not accepted. Trading actions, unlike this one, may be signed either by the wallet's key or by an API wallet it has approved. ### Funding the account Hyperliquid keeps two USDC balances per wallet, and **only the perpetuals balance can be used as margin**. This trips up more integrations than anything else: a wallet holds USDC, `/perp/account` shows a balance, and orders still fail for insufficient margin because the funds are sitting in spot. * `GET /perp/account` reports both — the perpetuals figures plus `spotUsdc`. * `POST /perp/transfer` moves USDC between them (`to_perp: true` for spot → perps). * On a bridge deposit, pass `perps` as the destination token to land the funds straight into the tradeable balance. To bring USDC in from another chain, quote it and broadcast the resulting transactions yourself: ```bash curl -s -X POST "https://api.nansen.ai/api/v1/perp/bridge/quote" \ -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" \ -d '{ "wallet_address": "0xYourWallet", "origin_chain": "base", "destination_chain": "hyperliquid", "origin_token": "USDC", "destination_token": "perps", "amount": "10000000" }' ``` Deposits are supported from Ethereum, Base, Arbitrum, Polygon and BNB Chain; withdrawals go to Ethereum, Base and Arbitrum. **Amounts are in the origin token's base units, and the two sides of a Hyperliquid route are not on the same scale** — USDC has 8 decimals on Hyperliquid and 6 on the EVM chains: | You want to bridge | From an EVM chain | From Hyperliquid | | ------------------ | ----------------- | ---------------- | | 1 USDC | `1000000` | `100000000` | | 10 USDC | `10000000` | `1000000000` | A wrong scale is quoted **without any error** — it just quotes the wrong size. Always check `amount_in` and `amount_out` in the response before signing anything; `amount_formatted` gives you the decoded figure, and the token `name` (`USDC (Perps)` vs `USDC (Spot)`) is the only field that tells you which balance the quote touches. The quote's `execution_type` tells you what to do next: | `execution_type` | Direction | What you do | | ----------------------- | ---------- | ----------------------------------------------------------------------------- | | `evm_transaction` | Deposit | Sign the `steps` transactions and broadcast them yourself on the origin chain | | `hyperliquid_signature` | Withdrawal | Sign the step's typed data and submit it to `POST /perp/bridge/execute` | Then poll `GET /perp/bridge/status` with the quote's `request_id` (or a deposit's origin transaction hash) until it reports `success`. A just-broadcast transfer reads `not_found` for a short while before it is indexed — retry for a bounded window, then treat it as terminal. `refund` means the funds returned to the origin chain instead of completing. ### Placing an order ```bash curl -s -X POST "https://api.nansen.ai/api/v1/perp/order" \ -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" \ -d '{ "wallet_address": "0xYourWallet", "coin": "BTC", "is_buy": true, "size": 0.01, "price": 65000, "order_type": "market", "slippage": 0.03 }' ``` **`size` is in units of the asset, not USD.** `0.01` on BTC is 0.01 BTC. **Market vs limit.** Hyperliquid has no separate market order type: `order_type: "market"` takes the current mark price you pass as `price`, adjusts it by `slippage` (a fraction — `0.03` is 3%), and submits an immediate-or-cancel limit order at that price. For `order_type: "limit"`, `price` is the limit price and `tif` decides how it rests (`Gtc`, `Ioc`, `Alo`). **Sizes and prices are rounded** to the precision the asset accepts, which you can read as `sz_decimals` from `/perp/meta`. The prepare response echoes the `size` and `price` actually encoded in the signed action, and both can differ from what you sent. Requesting `size: 0.0071111` on BTC (5 size decimals) comes back as `0.00711`, and a market order at `price: 65000` with 3% slippage comes back as `66950` — the immediate-or-cancel limit that will actually be submitted. Show the echoed values to the user, not the raw request. **Brackets.** Setting `take_profit` and/or `stop_loss` adds reduce-only trigger orders to the same signed action, so the entry and its protection are submitted together. The sides must be consistent: a take-profit above the entry and a stop-loss below it for a long, and the reverse for a short. The wrong side is rejected with a `422` rather than triggering the moment the position opens. ### Managing and closing Read state from the API rather than tracking it yourself — fills, funding and partial closes all move a position, and trigger legs may fire between your calls. * `GET /perp/positions` gives each position's signed size (negative is short), entry price, leverage, unrealized PnL and liquidation price. * `GET /perp/orders` lists resting limit orders plus untriggered TP/SL legs, each with the `oid` you pass to `/perp/cancel`. Closing takes the position's size and the **opposite** side: ```bash # Closing a long: is_buy is false (sell to close) curl -s -X POST "https://api.nansen.ai/api/v1/perp/close" \ -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" \ -d '{"wallet_address": "0xYourWallet", "coin": "BTC", "size": 0.01, "price": 65000, "is_buy": false}' ``` `price` here is only used to derive the slippage-adjusted limit; the close is always reduce-only and immediate-or-cancel, so it can never flip your position into the other direction. Leverage is set per asset with `/perp/leverage` and applies to positions opened afterwards — it does not re-margin a position you already hold. Check the asset's `max_leverage` in `/perp/meta` first. ### Signing the typed data The `eip712` object contains everything a standard EIP-712 signer needs: `domain`, `types`, `primaryType` and `message`. There are **two payload families**, and they do not share a domain or a `primaryType`: | Action | `domain.name` | `primaryType` | Signed by | | ---------------------------------------- | ---------------------------- | -------------------------- | ------------------------------------------------------ | | Trading — order, close, cancel, leverage | `Exchange` | `Agent` | The wallet's key **or** an approved API (agent) wallet | | Wallet-signed — transfer, fee approval | `HyperliquidSignTransaction` | `HyperliquidTransaction:*` | The wallet's own key only | So sign whatever the `eip712` field contains rather than hard-coding a shape from a previous response — that is the whole reason it is returned per call. A signer that assumes the trading domain will produce a signature the exchange rejects on a transfer, and vice versa. If a response carries a `vault_address`, forward it to `/perp/execute` exactly as received. The prepare response's `size` and `price` are `null` for actions that carry no order (cancel, leverage, transfer) — that is expected, not a missing field. ### Errors | Status | What it means | | ------ | ----------------------------------------------------------------------------------------- | | `422` | Your request was rejected, or the exchange refused the action. The reason is in `detail`. | | `451` | Perpetual trading is not available in your region. See [Availability](#availability). | | `502` | Hyperliquid could not be reached. Retry. | | `503` | Your region could not be verified, or a compliance check could not complete. Retry. | **A `2xx` from `/perp/execute` means the exchange really accepted the action.** Hyperliquid reports a refused action inside an otherwise successful response, so these endpoints inspect the result and surface the reason as a `422` instead of handing back a success envelope. The same applies to `/perp/bridge/execute` for withdrawals. You do not need to parse the response body to find out whether your order was rejected. Common `422` reasons worth handling explicitly: the builder fee is not approved, the size or price is too imprecise for the asset (re-prepare rather than rounding yourself), insufficient margin because the USDC is in spot, a stop-loss on the wrong side of the entry, or a cancel for an order that already filled. ### Cost and limits Trading actions — prepare, execute, transfer, the fee approval, and everything under `/perp/bridge/` — **do not consume plan credits**. The cost of trading is the exchange's own fees, the builder fee, and on-chain gas where you broadcast a transaction yourself. The read endpoints (`/perp/account`, `/perp/positions`, `/perp/orders`, `/perp/meta`, `/perp/builder-fee`) cost 1 credit per call. Every trading endpoint carries its own rate limit, sized for real trading rather than for polling. They are the same on every plan, because trading throughput is not a plan feature. Order placement, closes and executes are the tightest; cancels get more headroom so cancel/replace loops work. Poll `/perp/positions` and `/perp/orders` on a sensible interval rather than in a tight loop. ### Availability Perpetual trading is **not available in every jurisdiction**, and requests from restricted regions are rejected with `451`. If your region cannot be determined, requests are rejected with `503` rather than allowed through. Wallet addresses are screened against sanctions lists before an action is prepared and again when a signed action is submitted, where the signer is recovered from the signature itself. A blocked address is rejected regardless of which wallet was named in the request. These controls apply to the bridge endpoints too — funding and defunding a perpetuals account follow the same policy as trading on it. # Perpetual Trading reference These endpoint references support the [Perpetual Trading guide](/api/trade/perp-trading). They remain under their existing URLs for compatibility with existing links. | I want to... | Use this endpoint | | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Check account balances and margin usage | [Get perp account state](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-account.md) | | Check the one-time builder-fee approval | [Get builder-fee approval status](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-builder-fee.md) | | Prepare the builder-fee approval action | [Prepare a builder-fee approval](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-approve-builder-fee.md) | | See tradable assets and precision | [Get perp asset metadata](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-meta.md) | | Prepare an order | [Prepare a perp order](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-order.md) | | Submit a signed action | [Submit a signed perp action](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-execute.md) | | Get open positions | [Get open perp positions](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-positions.md) | | Get open orders | [Get open perp orders](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-orders.md) | | Prepare a cancel | [Prepare a perp cancel](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-cancel.md) | | Prepare a position close | [Prepare a position close](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-close.md) | | Prepare a leverage update | [Prepare a leverage update](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-leverage.md) | | Move USDC between spot and perps | [Prepare a Spot<->Perps transfer](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-transfer.md) | | Quote a bridge deposit or withdrawal | [Get a bridge quote](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-bridge-quote.md) | | Execute a signed bridge withdrawal | [Execute a bridge step](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-bridge-execute.md) | | Track a bridge deposit or withdrawal | [Check bridge status](https://github.com/nansen-ai/nansen-api/tree/main/gitbook/api/hyperliquid/perp-bridge-status.md) | # Hyperliquid Nansen's Hyperliquid API endpoints help you track positions, analyze trades, screen tokens and follow smart money activity across the fastest-growing perps platform. To open, manage or close your own perpetual positions, start from [API > Trading > Perpetual Trading](/api/trade#perpetual-trading). ## What can you do? With Hyperliquid endpoints, you can: * **Track wallet positions:** Monitor real-time perpetual positions, PnL, and account health * **Analyze trading activity:** View detailed trade history and execution data of any address * **Screen perp trading activity:** Find high-volume tokens and smart money flows on Hyperliquid * **Find top performers:** Discover the most profitable traders on specific tokens. ## Which endpoints can I use? | I want to... | Use this endpoint | Best for | | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | -------------------------------------------- | | See all open positions for a wallet including leverage, PnL, and liquidation prices | [Address Perp Positions](https://docs.nansen.ai/api/hyperliquid-apis/address-perp-positions) | Snapshot of current positions | | View a wallet's trading history with entry/exit prices, fees, and PnL | [Address Perp Trades](https://docs.nansen.ai/api/hyperliquid-apis/address-perp-trades) | Trade by trade breakdown of address activity | | See top profitable wallets on Hyperliquid over a given period | [Hyperliquid Leaderboard](https://docs.nansen.ai/api/hyperliquid-apis/hyperliquid-leaderboard) | Find profitable wallets and copy trading | | Find high-volume perp tokens or see where smart money is trading | [Perp Screener](https://docs.nansen.ai/api/hyperliquid-apis/perp-screener) | Market discovery & trends | | Find the most profitable traders on a specific perp token | [Perp PnL Leaderboard](https://docs.nansen.ai/api/hyperliquid-apis/perp-pnl-leaderboard) | Performance rankings | | Track what smart money wallets are trading on Hyperliquid | [Smart Money Perp Trades](/api/hyperliquid/smart-money-perp-trades) | Real-time smart money | | See all open positions for a specific perp token including leverage, PnL, and liquidation prices | [Token Perp Positions](/api/hyperliquid/token-perp-positions) | Snapshot of current positions for a token | | View trading history for a specific perp token over a time period | [Token Perp Trades](/api/hyperliquid/token-perp-trades) | All trading activity for a specific token | ## Key Differences: Hyperliquid vs. Other Chains #### Token Identification **Important**: Hyperliquid perp endpoints use **token symbols** instead of token addresses in Token God Mode Inputs | Other Chains | Hyperliquid | | ---------------------------- | ---------------------------------------- | | `token_address: "0x1234..."` | `token_symbol: "BTC"` | | Use contract addresses | Use ticker symbols (BTC, ETH, SOL, etc.) | **Example**: ```json // Other chains {"token_address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"} // Hyperliquid {"token_symbol": "BTC"} // For leaderboard endpoint ``` #### Positive and Negative Positions Some endpoints (Eg. Token Perp Positions) have negative Position value. This usually represents a short and a positive value represents a long. ## Quick Start Checklist 1. **Get your API key** from Nansen 2. **Choose your use case**: * Wallet monitoring → Use `/perp-positions` + `/perp-trades` * Market discovery → Use `/perp-screener` * Copy trading → Use `/perp-leaderboard` + `/tgm/perp-pnl-leaderboard` * Trading your own wallet → Follow [API > Trading > Perpetual Trading](/api/trade#perpetual-trading) 3. **Remember**: Use token symbols (BTC, ETH) not addresses 4. **Add filters**: Refine results with volume, PnL, or time filters # Address Perp Positions ### Common Scenarios
UsecaseRequired ParametersOptional FiltersExpected Output
Check current perp positions for a single addressaddress ="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 addressaddress ="0xa312114b5795dff9b8db50474dd57701aa78ad1e"filters ={"unrealized_pnl_usd": {"max": 0}}List of positions with negative unrealized PnL
### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Returns a **current, point-in-time snapshot** of the address's open positions — there is no date-range parameter or historical look-back, and values reflect within the standard live latency. ## Get Perpetual Positions Data > Get perpetual positions data for a user by calling the Hyperliquid API directly. This endpoint provides real-time position information including entry price, mark price, PnL, leverage, and other position details.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*What are the current perpetual positions for a specific user address?\*\*\ > 2\. \*\*What is the unrealized PnL and performance of each position?\*\*\ > 3\. \*\*What are the leverage levels and margin requirements for each position?\*\*\ > 4\. \*\*What are the liquidation prices and risk levels for each position?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"PerpPositionsRequest":{"properties":{"address":{"type":"string","maxLength":42,"minLength":42,"title":"Address","description":"User's Hyperliquid address in 42-character hexadecimal format"},"filters":{"anyOf":[{"$ref":"#/components/schemas/PerpPositionsFilters"}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/PerpPositionsSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"position_value_usd\", \"direction\": \"DESC\"}] - Sort by position value descending\n- [{\"field\": \"unrealized_pnl_usd\", \"direction\": \"ASC\"}] - Sort by unrealized PnL ascending\n\nIf not provided, positions are sorted by position value descending."}},"additionalProperties":false,"type":"object","required":["address"],"title":"PerpPositionsRequest","description":"Request model for Perp Positions endpoint."},"PerpPositionsFilters":{"properties":{"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","description":"Filter by token symbol"},"position_value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Filter by position value in USD"},"position_type":{"anyOf":[{"type":"string"}],"title":"Position Type","description":"Filter by position type"},"unrealized_pnl_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Filter by unrealized PnL in USD"}},"additionalProperties":false,"type":"object","title":"PerpPositionsFilters","description":"Filters for perp positions endpoint."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"PerpPositionsSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/PerpPositionsSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"PerpPositionsSortOrder"},"PerpPositionsSortField":{"type":"string","enum":["leverage_value","position_value_usd","entry_price_usd","liquidation_price_usd","unrealized_pnl_usd","size","token_symbol","position_type"],"title":"PerpPositionsSortField","description":"Enum for perp positions sort fields."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"PerpPositionsResponse":{"properties":{"data":{"$ref":"#/components/schemas/PerpPositionsData","description":"Hyperliquid clearinghouse state data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"PerpPositionsResponse","description":"Response model for perp positions endpoint."},"PerpPositionsData":{"properties":{"assetPositions":{"anyOf":[{"items":{"$ref":"#/components/schemas/AssetPosition"},"type":"array"}],"title":"Assetpositions","description":"List of asset positions"},"crossMaintenanceMarginUsed":{"anyOf":[{"type":"string"}],"title":"Crossmaintenancemarginused","description":"Cross maintenance margin used USD"},"cross_margin_summary_account_value_usd":{"anyOf":[{"type":"string"}],"title":"Cross Margin Summary Account Value Usd","description":"Cross margin summary account value USD"},"cross_margin_summary_total_margin_used_usd":{"anyOf":[{"type":"string"}],"title":"Cross Margin Summary Total Margin Used Usd","description":"Cross margin summary total margin used USD"},"cross_margin_summary_total_net_liquidation_position_on_usd":{"anyOf":[{"type":"string"}],"title":"Cross Margin Summary Total Net Liquidation Position On Usd","description":"Cross margin summary total net liquidation position on USD"},"cross_margin_summary_total_raw_usd":{"anyOf":[{"type":"string"}],"title":"Cross Margin Summary Total Raw Usd","description":"Cross margin summary total raw USD"},"margin_summary_account_value_usd":{"anyOf":[{"type":"string"}],"title":"Margin Summary Account Value Usd","description":"Margin summary account value USD"},"margin_summary_total_margin_used_usd":{"anyOf":[{"type":"string"}],"title":"Margin Summary Total Margin Used Usd","description":"Margin summary total margin used USD"},"margin_summary_total_net_liquidation_position_usd":{"anyOf":[{"type":"string"}],"title":"Margin Summary Total Net Liquidation Position Usd","description":"Margin summary total net liquidation position USD"},"margin_summary_total_raw_usd":{"anyOf":[{"type":"string"}],"title":"Margin Summary Total Raw Usd","description":"Margin summary total raw USD"},"time":{"anyOf":[{"type":"integer"}],"title":"Time","description":"Timestamp"},"withdrawable":{"anyOf":[{"type":"string"}],"title":"Withdrawable","description":"Withdrawable USD"}},"additionalProperties":false,"type":"object","title":"PerpPositionsData","description":"Data model for Hyperliquid clearinghouse state response."},"AssetPosition":{"properties":{"position":{"anyOf":[{"$ref":"#/components/schemas/Position"}],"description":"Position data"},"position_type":{"anyOf":[{"type":"string"}],"title":"Position Type","description":"Position type"}},"additionalProperties":false,"type":"object","title":"AssetPosition","description":"Asset position wrapper."},"Position":{"properties":{"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","description":"Asset symbol (e.g., BTC, ETH)"},"size":{"anyOf":[{"type":"string"}],"title":"Size","description":"Size"},"position_value_usd":{"anyOf":[{"type":"string"}],"title":"Position Value Usd","description":"Position value USD"},"entry_price_usd":{"anyOf":[{"type":"string"}],"title":"Entry Price Usd","description":"Entry price USD"},"liquidation_price_usd":{"anyOf":[{"type":"string"}],"title":"Liquidation Price Usd","description":"Liquidation price USD"},"leverage_value":{"anyOf":[{"type":"integer"}],"title":"Leverage Value","description":"Leverage value"},"leverage_type":{"anyOf":[{"type":"string"}],"title":"Leverage Type","description":"Leverage type: 'cross' or 'isolated'"},"leverage_raw_usd":{"anyOf":[{"type":"string"}],"title":"Leverage Raw Usd","description":"Raw USD leverage"},"margin_used_usd":{"anyOf":[{"type":"string"}],"title":"Margin Used Usd","description":"Margin used USD"},"max_leverage_value":{"anyOf":[{"type":"integer"}],"title":"Max Leverage Value","description":"Maximum allowed leverage value"},"return_on_equity":{"anyOf":[{"type":"string"}],"title":"Return On Equity","description":"Return on equity"},"unrealized_pnl_usd":{"anyOf":[{"type":"string"}],"title":"Unrealized Pnl Usd","description":"Unrealized PnL USD"},"cumulative_funding_all_time_usd":{"anyOf":[{"type":"string"}],"title":"Cumulative Funding All Time Usd","description":"Cumulative funding all time USD"},"cumulative_funding_since_change_usd":{"anyOf":[{"type":"string"}],"title":"Cumulative Funding Since Change Usd","description":"Cumulative funding since change USD"},"cumulative_funding_since_open_usd":{"anyOf":[{"type":"string"}],"title":"Cumulative Funding Since Open Usd","description":"Cumulative funding since open USD"}},"additionalProperties":false,"type":"object","title":"Position","description":"Individual perpetual position."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/perp-positions":{"post":{"tags":["Profiler"],"summary":"Get Perpetual Positions Data","description":"Get perpetual positions data for a user by calling the Hyperliquid API directly. This endpoint provides real-time position information including entry price, mark price, PnL, leverage, and other position details.\n\n**What it helps to answer:**\n\n1. **What are the current perpetual positions for a specific user address?**\n2. **What is the unrealized PnL and performance of each position?**\n3. **What are the leverage levels and margin requirements for each position?**\n4. **What are the liquidation prices and risk levels for each position?**","operationId":"get_perp_positions_api_v1_profiler_perp_positions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpPositionsRequest"}}},"required":true},"responses":{"200":{"description":"Perpetual positions data for the user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpPositionsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Address Perp Trades ### Common Scenarios
UsecaseRequired ParametersOptional FiltersExpected Output
Fetch all perp trades for an address within a specific date rangeaddress ="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 detailsaddress ="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 tokenaddress ="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
### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Covers the Hyperliquid perpetuals dataset (reliable from **May 2025**), not per-chain history — see the Hyperliquid note on the coverage page. ## Get Perpetual Trade Data > Get perpetual trade data for a user. This endpoint provides trade information including trade price, size, side, fees, and other trade details.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*What are the perpetual trades for a specific user address within a date range?\*\*\ > 2\. \*\*What are the trade prices, sizes, and directions for each trade?\*\*\ > 3\. \*\*What are the trading fees and closed PnL for each trade?\*\*\ > 4\. \*\*What are the order IDs and transaction hashes for trade tracking?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"PerpTradeRequest":{"properties":{"address":{"type":"string","maxLength":42,"minLength":42,"title":"Address","description":"User's Hyperliquid address in 42-character hexadecimal format"},"date":{"$ref":"#/components/schemas/DateRange","description":"Date range for the trades (ISO 8601 date-time)"},"filters":{"anyOf":[{"$ref":"#/components/schemas/PerpTradeFilters"}],"description":"Additional filters for the trades"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/PerpTradeSortOrder"},"type":"array"}],"title":"Order By","description":"Sort order for the trades"}},"additionalProperties":false,"type":"object","required":["address","date"],"title":"PerpTradeRequest","description":"Request model for Perp Trades endpoint."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PerpTradeFilters":{"properties":{"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","description":"Token symbol filter"},"side":{"anyOf":[{"$ref":"#/components/schemas/PerpTradeType"}],"description":"Position side filter (Long or Short)"},"action":{"anyOf":[{"$ref":"#/components/schemas/PerpTradeActionFilter"}],"description":"Action filter (Open/Add, Close/Reduce, Liquidation)"},"crossed":{"anyOf":[{"type":"boolean"}],"title":"Crossed","description":"Whether the trade was crossed"},"size":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Trade size range filter"},"start_position":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Start position range filter"},"closed_pnl":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Closed PnL range filter"},"fee_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Fee in USD range filter"},"fee_token_symbol":{"anyOf":[{"type":"string"}],"title":"Fee Token Symbol","description":"Fee token filter"},"oid":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Order ID range filter"},"price":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Price range filter"},"value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Value in USD range filter"}},"additionalProperties":false,"type":"object","title":"PerpTradeFilters","description":"Filters for perp trades endpoint.\n\nThese filters control which perpetual trades are included in the results\nbased on various trade criteria."},"PerpTradeType":{"type":"string","enum":["Long","Short"],"title":"PerpTradeType","description":"Enum for perp trade position types."},"PerpTradeActionFilter":{"type":"string","enum":["Open/Add","Close/Reduce","Liquidation"],"title":"PerpTradeActionFilter","description":"Enum for perp trade action filters (grouped)."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"PerpTradeSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/PerpTradeSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"PerpTradeSortOrder"},"PerpTradeSortField":{"type":"string","enum":["timestamp","size","fee_usd","closed_pnl","price","value_usd"],"title":"PerpTradeSortField","description":"Enum for perp trade sort fields."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"PerpTradeResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/PerpTrade"},"type":"array","title":"Data","description":"List of perpetual trades"}},"additionalProperties":false,"type":"object","required":["pagination","data"],"title":"PerpTradeResponse","description":"Response model for perp trades endpoint."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"PerpTrade":{"properties":{"timestamp":{"type":"string","title":"Timestamp","description":"Timestamp of the trade"},"side":{"anyOf":[{"$ref":"#/components/schemas/PerpTradeType"}],"description":"Position side (Long or Short)"},"action":{"type":"string","title":"Action","description":"Action taken (Open, Add, Close, Reduce, etc.)"},"block_number":{"type":"integer","title":"Block Number","description":"Block number of the trade"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Symbol of the token"},"price":{"anyOf":[{"type":"number"}],"title":"Price","description":"Average price of the trade (averaged across fills)"},"size":{"type":"number","title":"Size","description":"Total size of the trade (sum of all fills)"},"value_usd":{"type":"number","title":"Value Usd","description":"Total value in USD of the trade"},"start_position":{"type":"number","title":"Start Position","description":"Start position of the trade in token units"},"closed_pnl":{"type":"number","title":"Closed Pnl","description":"Total closed PnL of the trade (sum of all fills)"},"crossed":{"type":"boolean","title":"Crossed","description":"Crossed of the trade"},"fee_usd":{"type":"number","title":"Fee Usd","description":"Total fee in USD of the trade (sum of all fills)"},"fee_token_symbol":{"type":"string","title":"Fee Token Symbol","description":"Fee in token of the trade"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Transaction hash of the trade"},"user":{"type":"string","title":"User","description":"User of the trade"},"oid":{"type":"integer","title":"Oid","description":"Order ID of the trade"}},"additionalProperties":false,"type":"object","required":["timestamp","side","action","block_number","token_symbol","price","size","value_usd","start_position","closed_pnl","crossed","fee_usd","fee_token_symbol","transaction_hash","user","oid"],"title":"PerpTrade","description":"Perpetual trade with computed type and action fields for client response."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/profiler/perp-trades":{"post":{"tags":["Profiler"],"summary":"Get Perpetual Trade Data","description":"Get perpetual trade data for a user. This endpoint provides trade information including trade price, size, side, fees, and other trade details.\n\n**What it helps to answer:**\n\n1. **What are the perpetual trades for a specific user address within a date range?**\n2. **What are the trade prices, sizes, and directions for each trade?**\n3. **What are the trading fees and closed PnL for each trade?**\n4. **What are the order IDs and transaction hashes for trade tracking?**","operationId":"get_perp_trades_api_v1_profiler_perp_trades_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpTradeRequest"}}},"required":true},"responses":{"200":{"description":"Perpetual trade data for the user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpTradeResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Hyperliquid Leaderboard {% hint style="warning" %} **Update:** The `premium_labels` parameter on this endpoint now defaults to `false`, as previously announced in the API changelog. Requests that omit the parameter return free-tier labels at the standard credit cost. Passing `premium_labels=true` returns premium labels (Smart Money, Fund, etc.), is billed at **150 credits per call**, and requires a paid plan. See the API changelog for details. {% endhint %} ### Common Scenarios
UsecaseRequired ParametersOptional FiltersExpected Output
Find top perpetual traders in a specific date rangedate ={ "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 (a fractional ratio: 0.15 means 15%), and account values in the date range
Filter leaderboard for high-value profitable accountsdate ={ "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
### ROI Unit `roi` is a fractional ratio, not a percentage: `0.15` means 15% and `-0.20` means -20%. It is total PnL over traded notional in USD plus the notional of positions still open, so it measures PnL per dollar traded rather than return on capital: a position that was opened and closed contributes both fills to the denominator. Two defects in this calculation were corrected on 24-08-2026 — see the [changelog entry](/api/changelog/24-08-2026-perp-leaderboard-roi-corrections). A trader with no traded notional in the window returns `roi: null`. ### Open Positions (`top_positions`) Each row carries the trader's five largest open positions by absolute position value, largest first. Every entry holds `coin`, `side` (`long` or `short`), `size_base`, `position_value_usd`, `entry_price`, and `unrealized_pnl_usd`. `size_base` is **absolute** — `side` carries the direction, so a short has a positive size. The list covers only positions in coins the trader **traded during the requested date range**. A position opened earlier and held through the window, in a coin not traded during it, is not listed — the same scope as `unrealized_pnl_usd` and the open-exposure term of `roi`. An empty list therefore means "no open position in a coin traded in the window", not "holds nothing". This field and the four other additions shipped on 25-08-2026 — see the [changelog entry](/api/changelog/25-08-2026-perp-leaderboard-new-fields). ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Covers the Hyperliquid perpetuals dataset (reliable from **May 2025**), not per-chain history — see the Hyperliquid note on the coverage page. ## Get Perpetual Trading Leaderboard Data > Get perpetual trading leaderboard data showing the most profitable traders within a given date range. This endpoint provides trader performance metrics including total PnL, ROI, and account values.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*Who are the most profitable perpetual traders in a given timeframe?\*\*\ > 2\. \*\*What is the ROI of the top performing traders?\*\*\ > 3\. \*\*What are the account values of successful perpetual traders?\*\*\ > 4\. \*\*How do trader addresses and labels correlate with performance?\*\*\ > 5\. \*\*What is a top trader holding right now?\*\*\ > \ > \*\*Key Features:\*\*\ > \- Trader address and label information\ > \- Total, realized and unrealized PnL in USD\ > \- ROI as a fractional ratio (0.15 means 15%)\ > \- Traded notional and fill count over the timeframe\ > \- The five largest open positions per trader\ > \- Account value tracking\ > \- Flexible filtering and sorting options\ > \ > \*\*Label Tier Control (\`premium\_labels\`):\*\*\ > When omitted or set to \`false\` (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing \`premium\_labels=true\` returns premium labels (Smart Money, Fund, and other advanced labels), is billed at \*\*150 credits per call\*\*, and requires a paid plan. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"PerpLeaderboardRequest":{"properties":{"date":{"$ref":"#/components/schemas/DateOnlyRange","description":"Date range object with optional from and to fields in YYYY-MM-DD format"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/PerpLeaderboardFilters"}],"description":"Additional filters to apply to the query."},"premium_labels":{"anyOf":[{"type":"boolean"}],"title":"Premium Labels","description":"Controls label tier in the response. When null/omitted or false (the default), returns free-tier labels at the standard credit cost for this endpoint. When true, returns premium labels (Smart Money, Fund, and other advanced labels), is billed at 150 credits per call, and requires a paid plan."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/PerpLeaderboardSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering"}},"additionalProperties":false,"type":"object","required":["date"],"title":"PerpLeaderboardRequest","description":"Request model for Perp Leaderboard endpoint.\nThis endpoint provides a perpetual trading leaderboard showing the most profitable\ntraders within a given date range."},"DateOnlyRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in YYYY-MM-DD format"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in YYYY-MM-DD format"}},"type":"object","title":"DateOnlyRange","description":"Date range model that only accepts YYYY-MM-DD format (no time components)."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"PerpLeaderboardFilters":{"properties":{"trader_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address","description":"Trader address filter"},"trader_address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address Label","description":"Filter by wallet display name. Use LIKE patterns (%) for partial matching. Note: This filters by the wallet's display name, not by label category. To filter by smart money labels, use include_smart_money_labels instead."},"total_pnl":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total PnL range filter in USD"},"roi":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"ROI range filter as a fractional ratio (0.15 means 15%). Signed, so a loss is negative and a min of 0 keeps profitable traders only."},"account_value":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Account value range filter in USD. Note: Only the top 500K traders have account value data available."},"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Filter to include only traders with these smart money labels. For Hyperliquid, use 'Smart HL Perps Trader'. See SmartMoneyFilterType enum for valid values."},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels"}},"additionalProperties":false,"type":"object","title":"PerpLeaderboardFilters","description":"Filters for Perp Leaderboard endpoint.\n\nThese filters control which traders are included in the leaderboard."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Filter by smart money label type."},"PerpLeaderboardSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/PerpLeaderboardSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"PerpLeaderboardSortOrder"},"PerpLeaderboardSortField":{"type":"string","enum":["total_pnl","realized_pnl_usd","unrealized_pnl_usd","roi","volume_usd","total_trades","account_value"],"title":"PerpLeaderboardSortField","description":"Sort field for the perpetuals leaderboard."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"PerpLeaderboardResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/PerpLeaderboard"},"type":"array","title":"Data","description":"List of Perp Leaderboard records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"PerpLeaderboardResponse","description":"Response model for Perp Leaderboard endpoint.\nContains a list of leaderboard records with pagination and metadata."},"PerpLeaderboard":{"properties":{"trader_address":{"type":"string","title":"Trader Address","description":"The Ethereum wallet address of the trader."},"trader_address_label":{"anyOf":[{"type":"string"}],"title":"Trader Address Label","description":"The name associated with the address, derived using Nansen's multichain label function for Ethereum."},"total_pnl":{"anyOf":[{"type":"number"}],"title":"Total Pnl","description":"Profit and loss for the selected timeframe in USD, realized plus unrealized."},"realized_pnl_usd":{"anyOf":[{"type":"number"}],"title":"Realized Pnl Usd","description":"Realized profit and loss for the selected timeframe in USD."},"unrealized_pnl_usd":{"anyOf":[{"type":"number"}],"title":"Unrealized Pnl Usd","description":"Unrealized profit and loss in USD on positions still open, valued at the current mark price."},"roi":{"anyOf":[{"type":"number"}],"title":"Roi","description":"Return on investment for the selected timeframe as a fractional ratio (0.15 means 15%, -0.20 means -20%). Computed as total_pnl divided by traded notional in USD plus the notional of positions still open, so it measures PnL per dollar traded rather than return on capital: a position that was opened and closed contributes both fills to the denominator."},"volume_usd":{"anyOf":[{"type":"number"}],"title":"Volume Usd","description":"Traded notional in USD over the selected timeframe. Both the opening and the closing fill of a position count."},"total_trades":{"anyOf":[{"type":"integer"}],"title":"Total Trades","description":"Number of fills over the selected timeframe."},"top_positions":{"items":{"$ref":"#/components/schemas/PerpLeaderboardPosition"},"type":"array","title":"Top Positions","description":"The trader's five largest open positions by absolute position value, largest first. Covers only positions in coins the trader traded during the selected timeframe, so a position held through the window in a coin that was not traded is not listed. Empty for a trader with no such open position."},"account_value":{"anyOf":[{"type":"number"}],"title":"Account Value","description":"Current total account value in USD. Note: Account value data is only available for the top 500K traders due to upstream data limitations. Traders outside the top 500K may show 0 or null values."}},"type":"object","required":["trader_address"],"title":"PerpLeaderboard","description":"Individual Perp Leaderboard record.\nRepresents a single trader's perpetual trading performance."},"PerpLeaderboardPosition":{"properties":{"coin":{"type":"string","title":"Coin","description":"Perp market symbol the position is in."},"side":{"type":"string","title":"Side","description":"Position direction: 'long' or 'short'."},"size_base":{"type":"number","title":"Size Base","description":"Position size in base/coin units (absolute); `side` carries direction."},"position_value_usd":{"type":"number","title":"Position Value Usd","description":"Notional value of the position in USD."},"entry_price":{"type":"number","title":"Entry Price","description":"Average entry price of the position."},"unrealized_pnl_usd":{"type":"number","title":"Unrealized Pnl Usd","description":"Unrealized PnL on the position, in USD."}},"type":"object","required":["coin","side","size_base","position_value_usd","entry_price","unrealized_pnl_usd"],"title":"PerpLeaderboardPosition","description":"A single open perpetual position held by a leaderboard trader."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/perp-leaderboard":{"post":{"tags":["Perp Leaderboard"],"summary":"Get Perpetual Trading Leaderboard Data","description":"Get perpetual trading leaderboard data showing the most profitable traders within a given date range. This endpoint provides trader performance metrics including total PnL, ROI, and account values.\n\n**What it helps to answer:**\n\n1. **Who are the most profitable perpetual traders in a given timeframe?**\n2. **What is the ROI of the top performing traders?**\n3. **What are the account values of successful perpetual traders?**\n4. **How do trader addresses and labels correlate with performance?**\n5. **What is a top trader holding right now?**\n\n**Key Features:**\n- Trader address and label information\n- Total, realized and unrealized PnL in USD\n- ROI as a fractional ratio (0.15 means 15%)\n- Traded notional and fill count over the timeframe\n- The five largest open positions per trader\n- Account value tracking\n- Flexible filtering and sorting options\n\n**Label Tier Control (`premium_labels`):**\nWhen omitted or set to `false` (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing `premium_labels=true` returns premium labels (Smart Money, Fund, and other advanced labels), is billed at **150 credits per call**, and requires a paid plan.","operationId":"get_perp_leaderboard_api_v1_perp_leaderboard_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpLeaderboardRequest"}}},"required":true},"responses":{"200":{"description":"Perpetual trading leaderboard data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpLeaderboardResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Perp Screener ### Common scenarios
Use caseDate windowFilters and sortingExpected output
Find perps with net buying pressure and high open interestdate = { "from": "2026-10-01T00:00:00Z", "to": "2026-10-05T23:59:59Z" }filters = { "buy_sell_pressure": { "min": 100000 }, "open_interest": { "min": 500000 } }Perps with at least $100,000 in net buying pressure over the window and at least $500,000 in current open interest
Discover perps favored by smart moneydate = { "from": "2026-10-01T00:00:00Z", "to": "2026-10-05T23:59:59Z" }filters = { "trader_type": "sm", "smart_money_volume": { "min": 100000 } }
order_by = [{ "field": "smart_money_volume", "direction": "DESC" }]		Perps with at least $100,000 in smart money volume over the window, highest volume first, with current smart money long/short counts and USD position sizes
Find the top 24h gainersdate = { "from": "<now minus 24h>", "to": "<now>" }order_by = [{ "field": "price_change", "direction": "DESC" }]Perps ranked by mark price change over the last 24 hours, largest gain first
For the 24h example, replace the placeholders with UTC timestamps in ISO 8601 format. Set `to` to the current time and `from` to 24 hours earlier. `trader_type` belongs inside `filters`. Use `"trader_type": "sm"` for smart money; `only_smart_money` is deprecated. ### Price change `price_change` measures how the market price moved over the requested `date` window. It is a signed ratio calculated as `window_end_price_usd / previous_price_usd - 1`. A value of `0.05` means +5%; `-0.2` means -20%. Both prices are Hyperliquid mark prices at the window boundaries, with five-minute precision. One exception: HIP-3 markets (symbols like `xyz:NAME`) have no mark history before 2026-03-12, so a boundary before that date uses the last trade in the interval. For each boundary, the endpoint uses the closing mark of the last complete five-minute UTC interval that ends at or before it. A window starting at 09:00 or 09:02 uses the 08:55 to 09:00 interval; one starting at 09:05 uses 09:00 to 09:05. `date.to` is capped at the current time, so a window ending now uses the latest complete interval, and a historical window uses its own end price. `mark_price` is still the latest mark and is not part of the calculation. The prices do not depend on which traders were active. A coin and window have the same `previous_price_usd`, `window_end_price_usd` and `price_change` in every `trader_type`. The trader type selects which coins and activity appear. If an interval has no mark price, or its price is zero or negative, that boundary price is `null` and so is `price_change`. The endpoint does not substitute a nearby interval or a trade from elsewhere in the window, so a coin listed after the window started has no `price_change` for that window. Before this change, `previous_price_usd` was the first trade in the window and `price_change` compared it with the latest mark price. Both fields now use the window-boundary marks described above. The response includes `previous_price_usd`, `window_end_price_usd` and `price_change` for every `filters.trader_type`, and each supports sorting by `price_change`. The default mode is `"all"`. For `whale`, `public_figure`, `high_winrate_hl_perps_trader` and `predicted_winner`, the price fields are `null` on ordinary requests. Set `"include_price_change": true` to return them. Sorting by `price_change` or `previous_price_usd`, or filtering by `previous_price_usd`, includes them automatically. This optional lookup can add latency. `all` and `sm` return the price fields on every request. `predicted_winner` is available only to accounts with access to it. To rank gainers first, add this sort order to your request: ```json { "order_by": [{ "field": "price_change", "direction": "DESC" }] } ``` Use `"ASC"` to rank the largest declines first. * `price_change` is `null` for outcome contracts, whose symbols start with `#` and whose prices represent probabilities between 0 and 1. It is also `null` when either boundary price is missing, zero, or negative. * When sorting by `price_change`, rows with `null` values appear last in either direction. The endpoint adds `token_symbol` ascending as a final tie-breaker unless you include your own `token_symbol` sort. This gives tied rows a consistent order across pages, though live data can change between requests. ### Data freshness and historical coverage Hyperliquid perpetuals are a separate dataset from the chains listed in [Data Coverage by Chain](/api/data-coverage), with reliable history from May 2025 onward. See that page for general data freshness. The `date` window controls trade metrics such as volume, buy/sell pressure, and trader counts, and the boundary prices behind `price_change`. Mark price, funding, open interest, and current position metrics reflect the latest available data, even when you request a historical window. ## Get Perpetual Contract Screening Data > Discover and screen perpetual contracts on Hyperliquid with advanced filtering capabilities. This endpoint helps identify trending perpetual contracts, trading activity, funding rates, and smart money movements by combining metrics like volume, open interest, funding rates, and position data.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*Which perpetual contracts are experiencing significant trading volume and activity?\*\*\ > 2\. \*\*How do funding rates correlate with trading patterns and smart money positions?\*\*\ > 3\. \*\*What perpetual contracts show strong fundamentals in terms of open interest and trading patterns?\*\*\ > 4\. \*\*Which perpetual contracts are attracting smart money participation with long/short positions?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"PerpScreenerRequest":{"properties":{"date":{"$ref":"#/components/schemas/DateRange","description":"Date range for the perp screener"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/PerpScreenerFilters"}],"description":"Additional filters to apply"},"include_price_change":{"type":"boolean","title":"Include Price Change","description":"Return previous_price_usd, window_end_price_usd and price_change for notable-label trader cohorts even when not sorting or filtering by price. These fields are otherwise null unless price_change or previous_price_usd is used for sorting, or previous_price_usd is used for filtering. All and Smart Money results always include these fields.","default":false},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/PerpScreenerSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"volume\", \"direction\": \"DESC\"}] - Sort by volume descending\n- [{\"field\": \"net_position_change\", \"direction\": \"DESC\"}] - Sort by net_position_change descending\n- [{\"field\": \"buy_sell_pressure\", \"direction\": \"DESC\"}] - Sort by buy/sell pressure descending\n- [{\"field\": \"price_change\", \"direction\": \"DESC\"}] - Top gainers first\n\nAvailable sort fields depend on trader_type: buy_sell_pressure only applies to\ntrader_type all, net_position_change to the other trader types. price_change\napplies to every trader type. Rows with a null price_change (outcome contracts,\nmissing prices) sort last in both directions, and token_symbol ASC\nis added as a final tie-breaker so pages don't overlap.\n\nDefault behavior:\n- trader_type all (or unset): sorts by buy_sell_pressure DESC\n- all other trader types: sorts by net_position_change DESC"}},"additionalProperties":false,"type":"object","required":["date"],"title":"PerpScreenerRequest","description":"Request model for Perp Screener endpoint."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"PerpScreenerFilters":{"properties":{"trader_type":{"anyOf":[{"$ref":"#/components/schemas/PerpTraderType"}],"description":"Filter by trader type. Overrides only_smart_money when provided. Values: all, sm, whale, public_figure, high_winrate_hl_perps_trader."},"only_smart_money":{"anyOf":[{"type":"boolean"}],"title":"Only Smart Money","description":"Deprecated: Use 'trader_type=sm' instead.","default":false,"deprecated":true},"sectors_filter":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Sectors Filter","description":"Filter by sector in category:subcategory format (e.g. Crypto:DeFi, Crypto:AI, TradFi:Stocks). Values in any other format are rejected. Note: this differs from the token screener's sectors filter, which uses bare sector names. Applied server-side."},"sm_label_filter":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Sm Label Filter","description":"Filter by Nansen smart money label. Applies when trader_type is all or sm; ignored for other trader types. Applied server-side."},"trader_label_filter":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Trader Label Filter","description":"Filter by Hyperliquid perps trader label (e.g. HL Perps Whale, HL Perps Swing Trader). Applies when trader_type is all or sm; ignored for other trader types. Applied server-side."},"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","description":"Asset symbol filter (e.g., BTC, ETH)"},"volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total traded notional in USD range filter"},"buy_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total USD value of market buy trades range filter"},"sell_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total USD value of market sell trades range filter"},"buy_sell_pressure":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Net USD flow range filter"},"trader_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of unique traders range filter"},"mark_price":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Latest mark price range filter"},"funding":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Latest funding rate range filter"},"previous_price_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Window-start mark price range filter: the close of the last complete 5-minute bucket ending at or before date.from (UTC). Rows with a null start price match only a filter with no max and a min of 0 or less."},"open_interest":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Latest open interest range filter"},"smart_money_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total traded notional in USD by Smart Money range filter"},"smart_money_buy_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total USD value of Smart Money market buy trades range filter"},"smart_money_sell_volume":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total USD value of Smart Money market sell trades range filter"},"net_position_change":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Net USD flow (buy_market_vol - sell_market_vol) range filter"},"current_smart_money_position_longs_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Aggregate USD value of Smart Money long positions range filter"},"current_smart_money_position_shorts_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Aggregate USD value of Smart Money short positions range filter"},"smart_money_longs_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of Smart Money accounts with net long position range filter"},"smart_money_shorts_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of Smart Money accounts with net short position range filter"}},"additionalProperties":false,"type":"object","title":"PerpScreenerFilters","description":"Filters for perp screener endpoints.\n\nThese filters control which perpetual contracts are included in the screening\nresults based on various criteria."},"PerpTraderType":{"type":"string","enum":["all","sm","whale","public_figure","high_winrate_hl_perps_trader"],"title":"PerpTraderType","description":"Trader type for perp screener."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"PerpScreenerSortOrder":{"properties":{"field":{"anyOf":[{"$ref":"#/components/schemas/PerpScreenerSortFieldDefault"},{"$ref":"#/components/schemas/PerpScreenerSortFieldSmartMoney"},{"$ref":"#/components/schemas/PerpScreenerSortFieldNotableLabel"}],"title":"Field","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"PerpScreenerSortOrder"},"PerpScreenerSortFieldDefault":{"type":"string","enum":["token_symbol","volume","buy_volume","sell_volume","buy_sell_pressure","trader_count","mark_price","funding","previous_price_usd","price_change","open_interest"],"title":"PerpScreenerSortFieldDefault","description":"Sort fields available for default perp screener data (only_smart_money=False)."},"PerpScreenerSortFieldSmartMoney":{"type":"string","enum":["token_symbol","smart_money_volume","smart_money_buy_volume","smart_money_sell_volume","net_position_change","trader_count","mark_price","funding","previous_price_usd","price_change","open_interest","current_smart_money_position_longs_usd","current_smart_money_position_shorts_usd","smart_money_longs_count","smart_money_shorts_count"],"title":"PerpScreenerSortFieldSmartMoney","description":"Sort fields available for smart money perp screener data (only_smart_money=True)."},"PerpScreenerSortFieldNotableLabel":{"type":"string","enum":["token_symbol","volume","buy_volume","sell_volume","net_position_change","trader_count","mark_price","funding","previous_price_usd","price_change","open_interest","current_position_longs_usd","current_position_shorts_usd","longs_count","shorts_count"],"title":"PerpScreenerSortFieldNotableLabel","description":"Sort fields available for notable-label perp screener data (trader_type whale/public_figure/high_winrate_hl_perps_trader)."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"PerpScreenerResponse":{"properties":{"data":{"items":{"anyOf":[{"$ref":"#/components/schemas/PerpScreenerDataDefault"},{"$ref":"#/components/schemas/PerpScreenerDataSmartMoney"},{"$ref":"#/components/schemas/PerpScreenerDataNotableLabel"}]},"type":"array","title":"Data","description":"List of perp screening results"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"PerpScreenerResponse","description":"Response model for perp screener endpoint."},"PerpScreenerDataDefault":{"properties":{"volume":{"anyOf":[{"type":"number"}],"title":"Volume","description":"Total traded notional in USD over the recent window."},"buy_volume":{"anyOf":[{"type":"number"}],"title":"Buy Volume","description":"Total USD value of market buy trades over the recent window."},"sell_volume":{"anyOf":[{"type":"number"}],"title":"Sell Volume","description":"Total USD value of market sell trades over the recent window."},"buy_sell_pressure":{"anyOf":[{"type":"number"}],"title":"Buy Sell Pressure","description":"Changes in position by Market Orders. Buys and sells through market orders (top of orderbook) indicate a rush into adjusting the position."},"trader_count":{"anyOf":[{"type":"integer"}],"title":"Trader Count","description":"Number of unique traders active over the recent window."},"token_symbol":{"type":"string","title":"Token Symbol","description":"Asset symbol (e.g., BTC, ETH) on Hyperliquid."},"mark_price":{"anyOf":[{"type":"number"}],"title":"Mark Price","description":"Latest mark price for the coin."},"funding":{"anyOf":[{"type":"number"}],"title":"Funding","description":"Latest funding rate/value for the coin."},"open_interest":{"anyOf":[{"type":"number"}],"title":"Open Interest","description":"Latest open interest for the coin."},"previous_price_usd":{"anyOf":[{"type":"number"}],"title":"Previous Price Usd","description":"Window-start mark price: the close of the last complete 5-minute bucket ending at or before date.from (UTC). A 09:00 or 09:02 start uses the 08:55 to 09:00 bucket. Null when that bucket is missing or its price is not positive; no later or earlier price substitutes. HIP-3 markets (symbols like xyz:NAME) have no mark history before 2026-03-12, so their closes before then are the last trade in the bucket."},"window_end_price_usd":{"anyOf":[{"type":"number"}],"title":"Window End Price Usd","description":"Window-end mark price: the close of the last complete 5-minute bucket ending at or before date.to, capped at now (UTC). For a window ending now this is the latest complete bucket, not the live mark_price. Null when that bucket is missing or its price is not positive. HIP-3 markets (symbols like xyz:NAME) have no mark history before 2026-03-12, so their closes before then are the last trade in the bucket."},"price_change":{"anyOf":[{"type":"number"}],"title":"Price Change","description":"Signed ratio change over the date window, window_end_price_usd / previous_price_usd - 1 (0.05 = +5%, -0.2 = -20%). Both prices are 5-minute Hyperliquid closes at the window boundaries and do not depend on which traders were active, so a coin and window have the same value in every trader_type. A historical window uses its own end price, not the latest mark. Null for outcome contracts (symbols starting with '#') and when either boundary price is missing, zero, or negative."}},"type":"object","required":["token_symbol"],"title":"PerpScreenerDataDefault","description":"Data model for perp screener results when only_smart_money is False."},"PerpScreenerDataSmartMoney":{"properties":{"smart_money_volume":{"anyOf":[{"type":"number"}],"title":"Smart Money Volume","description":"Total traded notional in USD by Smart Money over the window."},"smart_money_buy_volume":{"anyOf":[{"type":"number"}],"title":"Smart Money Buy Volume","description":"Total USD value of Smart Money market buy trades over the window."},"smart_money_sell_volume":{"anyOf":[{"type":"number"}],"title":"Smart Money Sell Volume","description":"Total USD value of Smart Money market sell trades over the window."},"net_position_change":{"anyOf":[{"type":"number"}],"title":"Net Position Change","description":"Net USD flow (buy_market_vol - sell_market_vol) over the window."},"trader_count":{"anyOf":[{"type":"integer"}],"title":"Trader Count","description":"Number of unique Smart Money traders active over the window."},"token_symbol":{"type":"string","title":"Token Symbol","description":"Asset symbol (e.g., BTC, ETH) on Hyperliquid."},"mark_price":{"anyOf":[{"type":"number"}],"title":"Mark Price","description":"Latest mark price for the coin."},"funding":{"anyOf":[{"type":"number"}],"title":"Funding","description":"Latest funding rate/value for the coin."},"previous_price_usd":{"anyOf":[{"type":"number"}],"title":"Previous Price Usd","description":"Window-start mark price: the close of the last complete 5-minute bucket ending at or before date.from (UTC). A 09:00 or 09:02 start uses the 08:55 to 09:00 bucket. Null when that bucket is missing or its price is not positive; no later or earlier price substitutes. HIP-3 markets (symbols like xyz:NAME) have no mark history before 2026-03-12, so their closes before then are the last trade in the bucket."},"window_end_price_usd":{"anyOf":[{"type":"number"}],"title":"Window End Price Usd","description":"Window-end mark price: the close of the last complete 5-minute bucket ending at or before date.to, capped at now (UTC). For a window ending now this is the latest complete bucket, not the live mark_price. Null when that bucket is missing or its price is not positive. HIP-3 markets (symbols like xyz:NAME) have no mark history before 2026-03-12, so their closes before then are the last trade in the bucket."},"price_change":{"anyOf":[{"type":"number"}],"title":"Price Change","description":"Signed ratio change over the date window, window_end_price_usd / previous_price_usd - 1 (0.05 = +5%, -0.2 = -20%). Both prices are 5-minute Hyperliquid closes at the window boundaries and do not depend on which traders were active, so a coin and window have the same value in every trader_type. A historical window uses its own end price, not the latest mark. Null for outcome contracts (symbols starting with '#') and when either boundary price is missing, zero, or negative."},"open_interest":{"anyOf":[{"type":"number"}],"title":"Open Interest","description":"Latest open interest in USD (open_interest × mark_price)."},"current_smart_money_position_longs_usd":{"anyOf":[{"type":"number"}],"title":"Current Smart Money Position Longs Usd","description":"Aggregate USD value of Smart Money long positions for the coin."},"current_smart_money_position_shorts_usd":{"anyOf":[{"type":"number"}],"title":"Current Smart Money Position Shorts Usd","description":"Aggregate USD value of Smart Money short positions for the coin (negative)."},"smart_money_longs_count":{"anyOf":[{"type":"integer"}],"title":"Smart Money Longs Count","description":"Number of Smart Money accounts with a net long position."},"smart_money_shorts_count":{"anyOf":[{"type":"integer"}],"title":"Smart Money Shorts Count","description":"Number of Smart Money accounts with a net short position."}},"type":"object","required":["token_symbol"],"title":"PerpScreenerDataSmartMoney","description":"Data model for perp screener results when only_smart_money is True."},"PerpScreenerDataNotableLabel":{"properties":{"volume":{"anyOf":[{"type":"number"}],"title":"Volume","description":"Total traded notional in USD by the selected trader cohort over the window."},"buy_volume":{"anyOf":[{"type":"number"}],"title":"Buy Volume","description":"Total USD value of buys by the selected trader cohort over the window."},"sell_volume":{"anyOf":[{"type":"number"}],"title":"Sell Volume","description":"Total USD value of sells by the selected trader cohort over the window."},"net_position_change":{"anyOf":[{"type":"number"}],"title":"Net Position Change","description":"Net USD flow (buys minus sells) by the selected trader cohort over the window."},"trader_count":{"anyOf":[{"type":"integer"}],"title":"Trader Count","description":"Number of unique cohort traders active over the window."},"token_symbol":{"type":"string","title":"Token Symbol","description":"Asset symbol (e.g., BTC, ETH) on Hyperliquid."},"mark_price":{"anyOf":[{"type":"number"}],"title":"Mark Price","description":"Latest mark price for the coin."},"funding":{"anyOf":[{"type":"number"}],"title":"Funding","description":"Latest funding rate/value for the coin."},"previous_price_usd":{"anyOf":[{"type":"number"}],"title":"Previous Price Usd","description":"Window-start mark price: the close of the last complete 5-minute bucket ending at or before date.from (UTC). A 09:00 or 09:02 start uses the 08:55 to 09:00 bucket. Null when that bucket is missing or its price is not positive; no later or earlier price substitutes. HIP-3 markets (symbols like xyz:NAME) have no mark history before 2026-03-12, so their closes before then are the last trade in the bucket. Null unless price fields are requested with include_price_change, sorting or filtering."},"window_end_price_usd":{"anyOf":[{"type":"number"}],"title":"Window End Price Usd","description":"Window-end mark price: the close of the last complete 5-minute bucket ending at or before date.to, capped at now (UTC). For a window ending now this is the latest complete bucket, not the live mark_price. Null when that bucket is missing or its price is not positive. HIP-3 markets (symbols like xyz:NAME) have no mark history before 2026-03-12, so their closes before then are the last trade in the bucket. Null unless price fields are requested with include_price_change, sorting or filtering."},"price_change":{"anyOf":[{"type":"number"}],"title":"Price Change","description":"Signed ratio change over the date window, window_end_price_usd / previous_price_usd - 1 (0.05 = +5%, -0.2 = -20%). Both prices are 5-minute Hyperliquid closes at the window boundaries and do not depend on which traders were active, so a coin and window have the same value in every trader_type. A historical window uses its own end price, not the latest mark. Null for outcome contracts (symbols starting with '#') and when either boundary price is missing, zero, or negative. Null unless price fields are requested with include_price_change, sorting or filtering."},"open_interest":{"anyOf":[{"type":"number"}],"title":"Open Interest","description":"Latest open interest for the coin."},"current_position_longs_usd":{"anyOf":[{"type":"number"}],"title":"Current Position Longs Usd","description":"Aggregate USD value of cohort long positions for the coin."},"current_position_shorts_usd":{"anyOf":[{"type":"number"}],"title":"Current Position Shorts Usd","description":"Aggregate USD value of cohort short positions for the coin (negative)."},"longs_count":{"anyOf":[{"type":"integer"}],"title":"Longs Count","description":"Number of cohort accounts with a net long position."},"shorts_count":{"anyOf":[{"type":"integer"}],"title":"Shorts Count","description":"Number of cohort accounts with a net short position."}},"type":"object","required":["token_symbol"],"title":"PerpScreenerDataNotableLabel","description":"Data model for perp screener when trader_type is whale, public_figure or high_winrate_hl_perps_trader."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/perp-screener":{"post":{"tags":["Token Screener"],"summary":"Get Perpetual Contract Screening Data","description":"Discover and screen perpetual contracts on Hyperliquid with advanced filtering capabilities. This endpoint helps identify trending perpetual contracts, trading activity, funding rates, and smart money movements by combining metrics like volume, open interest, funding rates, and position data.\n\n**What it helps to answer:**\n\n1. **Which perpetual contracts are experiencing significant trading volume and activity?**\n2. **How do funding rates correlate with trading patterns and smart money positions?**\n3. **What perpetual contracts show strong fundamentals in terms of open interest and trading patterns?**\n4. **Which perpetual contracts are attracting smart money participation with long/short positions?**","operationId":"get_perp_screener_api_v1_perp_screener_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpScreenerRequest"}}},"required":true},"responses":{"200":{"description":"Perpetual contract screening data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpScreenerResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Perp PnL Leaderboard ### Common Scenarios
UsecaseRequired ParametersOptional FiltersExpected Output
Filter for high-profit and high-balance addressestoken_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 contracttoken_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
### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Covers the Hyperliquid perpetuals dataset (reliable from **May 2025**), not per-chain history — see the Hyperliquid note on the coverage page. ## Get "Token God Mode" (TGM) perp PnL leaderboard data > Rank traders by their profit/loss performance for a specific perpetual contract on Hyperliquid. Shows both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages and trading patterns. This endpoint can be used to analyze the realized and unrealized profit for each trader who traded the input perpetual contract.\ > \ > \*\*Key Features:\*\*\ > \- Hyperliquid perpetual contracts only (no chain field needed)\ > \- Realized and unrealized PnL tracking\ > \- ROI calculations and trading patterns\ > \- Position size and balance tracking\ > \ > \*\*Request Format:\*\*\ > \- \`token\_symbol\`: Perpetual contract symbol (e.g., "BTC", "ETH", "SOL")\ > \- \`date\`: Date range for analysis\ > \- \`filters\`: Optional filters for trader addresses, PnL ranges, etc.\ > \- \`pagination\`: Page and per\_page parameters\ > \ > \*\*Label Tier Control (\`premium\_labels\`):\*\*\ > When omitted or set to \`false\` (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing \`premium\_labels=true\` returns premium labels (Smart Money, Fund, and other advanced labels), is billed at \*\*150 credits per call\*\*, and requires a paid plan. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMPerpPnlLeaderboardRequest":{"properties":{"token_symbol":{"type":"string","title":"Token Symbol","description":"Perpetual contract symbol (e.g., BTC, ETH, SOL)"},"date":{"$ref":"#/components/schemas/DateRange","description":"ISO 8601 date-time range object with optional from and to fields"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMPerpPnlLeaderboardFilters"}],"description":"Additional filters to apply to the query."},"premium_labels":{"anyOf":[{"type":"boolean"}],"title":"Premium Labels","description":"Controls label tier in the response. When null/omitted or false (the default), returns free-tier labels at the standard credit cost for this endpoint. When true, returns premium labels (Smart Money, Fund, and other advanced labels), is billed at 150 credits per call, and requires a paid plan."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMPerpPnlLeaderboardSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering"}},"type":"object","required":["token_symbol","date"],"title":"TGMPerpPnlLeaderboardRequest","description":"Request model for TGM Perp PnL leaderboard endpoint.\nSimplified version that only supports Hyperliquid perpetual contracts."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMPerpPnlLeaderboardFilters":{"properties":{"trader_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address","description":"Trader address filter"},"trader_address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address Label","description":"Trader name filter"},"token_price":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token price range filter"},"pnl_usd_realised":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Realized PnL range filter in USD"},"pnl_usd_unrealised":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Unrealized PnL range filter in USD"},"holding_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Holding amount range filter"},"position_value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Position value range filter in USD (+ve = Long position, -ve = Short position, 0 = Flat)"},"max_balance_held":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Maximum balance held range filter"},"max_balance_held_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Maximum balance held range filter in USD"},"still_holding_balance_ratio":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Still holding balance ratio range filter"},"nof_trades":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Number of trades range filter. Counts trades since the start of the requested date range."},"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Include smart money labels"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels"}},"additionalProperties":false,"type":"object","title":"TGMPerpPnlLeaderboardFilters","description":"Filters for TGM Perp PnL leaderboard endpoint.\n\nThese filters control which traders are included in the leaderboard."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Filter by smart money label type."},"TGMPerpPnlLeaderboardSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMPerpPnlLeaderboardSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMPerpPnlLeaderboardSortOrder"},"TGMPerpPnlLeaderboardSortField":{"type":"string","enum":["pnl_usd_realised","pnl_usd_unrealised","pnl_usd_total","roi_percent_total","roi_percent_realised","roi_percent_unrealised","holding_amount","position_value_usd","max_balance_held","max_balance_held_usd","still_holding_balance_ratio","netflow_amount_usd","netflow_amount","nof_trades"],"title":"TGMPerpPnlLeaderboardSortField","description":"Enum for sortable fields in TGM Perp PnL leaderboard."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMPerpPnlLeaderboardResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMPerpPnlLeaderboard"},"type":"array","title":"Data","description":"List of TGM Perp PnL leaderboard records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TGMPerpPnlLeaderboardResponse","description":"Response model for TGM Perp PnL leaderboard endpoint.\nContains a list of PnL leaderboard records with pagination and metadata."},"TGMPerpPnlLeaderboard":{"properties":{"trader_address":{"type":"string","title":"Trader Address","description":"Hexadecimal representation of the trader's address."},"trader_address_label":{"anyOf":[{"type":"string"}],"title":"Trader Address Label","description":"Nansen name of the trader"},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Token price in USD at date_to. Uses latest spot price if date_to is today or later, otherwise the daily median price for that date."},"pnl_usd_realised":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Realised","description":"Realised profit and loss in USD."},"pnl_usd_unrealised":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Unrealised","description":"Unrealised profit and loss in USD."},"holding_amount":{"anyOf":[{"type":"number"}],"title":"Holding Amount","description":"Current token balance"},"position_value_usd":{"anyOf":[{"type":"number"}],"title":"Position Value Usd","description":"Position value in USD (+ve = Long position, -ve = Short position, 0 = Flat)"},"max_balance_held":{"anyOf":[{"type":"number"}],"title":"Max Balance Held","description":"Maximum amount of tokens held at some point in time."},"max_balance_held_usd":{"anyOf":[{"type":"number"}],"title":"Max Balance Held Usd","description":"Maximum amount of tokens in current USD value, held at some point in time."},"still_holding_balance_ratio":{"anyOf":[{"type":"number"}],"title":"Still Holding Balance Ratio","description":"The ratio of current holdings to max balance held."},"netflow_amount_usd":{"anyOf":[{"type":"number"}],"title":"Netflow Amount Usd","description":"Netflow amount in USD."},"netflow_amount":{"anyOf":[{"type":"number"}],"title":"Netflow Amount","description":"Netflow amount."},"roi_percent_total":{"anyOf":[{"type":"number"}],"title":"Roi Percent Total","description":"Total ROI."},"roi_percent_realised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Realised","description":"Realised ROI."},"roi_percent_unrealised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Unrealised","description":"Unrealised ROI."},"pnl_usd_total":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Total","description":"Total PNL in USD."},"nof_trades":{"anyOf":[{"type":"integer"}],"title":"Nof Trades","description":"Number of trades since the start of the requested date range, on the same window as the realised PnL."}},"type":"object","required":["trader_address"],"title":"TGMPerpPnlLeaderboard","description":"Individual TGM Perp PnL leaderboard record.\nRepresents a single trader's PnL performance for a specific perpetual contract."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/perp-pnl-leaderboard":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) perp PnL leaderboard data","description":"Rank traders by their profit/loss performance for a specific perpetual contract on Hyperliquid. Shows both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages and trading patterns. This endpoint can be used to analyze the realized and unrealized profit for each trader who traded the input perpetual contract.\n\n**Key Features:**\n- Hyperliquid perpetual contracts only (no chain field needed)\n- Realized and unrealized PnL tracking\n- ROI calculations and trading patterns\n- Position size and balance tracking\n\n**Request Format:**\n- `token_symbol`: Perpetual contract symbol (e.g., \"BTC\", \"ETH\", \"SOL\")\n- `date`: Date range for analysis\n- `filters`: Optional filters for trader addresses, PnL ranges, etc.\n- `pagination`: Page and per_page parameters\n\n**Label Tier Control (`premium_labels`):**\nWhen omitted or set to `false` (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing `premium_labels=true` returns premium labels (Smart Money, Fund, and other advanced labels), is billed at **150 credits per call**, and requires a paid plan.","operationId":"get_tgm_perp_pnl_leaderboard_api_v1_tgm_perp_pnl_leaderboard_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPerpPnlLeaderboardRequest"}}},"required":true},"responses":{"200":{"description":"TGM Perp PnL leaderboard data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPerpPnlLeaderboardResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Smart Money Perp Trades ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Only the **trailing 7 days** of Hyperliquid perpetuals activity is queryable — far shorter than the available history — and there is no date-range parameter. ## Get Smart Money Perpetual Trades Data > Access real-time perpetual trading activity from smart traders and funds on Hyperliquid. This endpoint provides granular transaction-level data showing exactly what sophisticated traders are trading on perpetual contracts.\ > \ > Key Features:\ > \- Hyperliquid perpetual contracts only (no chain field needed)\ > \- Real-time trading data from smart money wallets\ > \- Detailed trade information including coin, amount, price, action, and type\ > \- Smart money filtering capabilities\ > \- Type filtering (Market/Limit)\ > \- Only new positions filter to show only position opening trades (defaults to false - shows all trades) ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"SmartMoneyPerpTradesRequest":{"properties":{"filters":{"anyOf":[{"$ref":"#/components/schemas/SmartMoneyPerpTradesFilters"}],"description":"Additional filters to apply. Only filters for columns that are being selected will be applied."},"lookback_hours":{"type":"integer","maximum":168,"minimum":1,"title":"Lookback Hours","description":"Length of the recent trade window in hours. Defaults to 168 hours to preserve the endpoint's existing seven-day behavior.","default":168},"only_new_positions":{"anyOf":[{"type":"boolean"}],"title":"Only New Positions","description":"When True, includes 'Open' position actions (Open Long, Open Short). Can be combined with other action filters using OR logic (union). When False (default), returns all trades.","default":false},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyPerpTradesSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"value_usd\", \"direction\": \"DESC\"}] - Sort by trade value descending\n- [{\"field\": \"block_timestamp\", \"direction\": \"ASC\"}] - Sort by timestamp ascending\n- [{\"field\": \"token_amount\", \"direction\": \"DESC\"}, {\"field\": \"block_timestamp\", \"direction\": \"ASC\"}] - Sort by token amount descending, then timestamp ascending"}},"additionalProperties":false,"type":"object","title":"SmartMoneyPerpTradesRequest","description":""},"SmartMoneyPerpTradesFilters":{"properties":{"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Narrow the fixed Smart HL Perps Trader cohort to traders that also carry any selected label. Empty or omitted keeps the full cohort."},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Remove members of the fixed Smart HL Perps Trader cohort that carry any selected label. Empty or omitted removes no traders."},"trader_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address","description":"Trader address filter"},"trader_address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address Label","description":"Trader name or label filter"},"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","description":"Token symbol filter"},"type":{"anyOf":[{"$ref":"#/components/schemas/TradeType"}],"description":"Trade type filter - Market or Limit"},"token_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token amount range filter"},"price_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Price range filter in USD"},"value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Trade value range filter in USD"},"side":{"anyOf":[{"$ref":"#/components/schemas/PositionSide"},{"items":{"$ref":"#/components/schemas/PositionSide"},"type":"array"},{"type":"null"}],"title":"Side","description":"Position side filter - Long or Short"},"action":{"anyOf":[{"$ref":"#/components/schemas/PerpActionType"},{"items":{"$ref":"#/components/schemas/PerpActionType"},"type":"array"},{"type":"null"}],"title":"Action","description":"Action filter - combined buy/sell with position action (e.g., 'Buy - Add Long', 'Sell - Open Short')"}},"additionalProperties":false,"type":"object","title":"SmartMoneyPerpTradesFilters","description":"Filters for smart money perpetual trades endpoint.\n\nThese filters control which perpetual trades and traders\nare included in the trades analysis."},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Filter by smart money label type."},"TradeType":{"type":"string","enum":["Market","Limit"],"title":"TradeType","description":"Enum for trade types."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"PositionSide":{"type":"string","enum":["Long","Short"],"title":"PositionSide","description":"Shared enum for position side direction."},"PerpActionType":{"type":"string","enum":["Buy - Add Long","Buy - Reduce Short","Buy - Open Long","Buy - Close Short","Sell - Add Short","Sell - Reduce Long","Sell - Open Short","Sell - Close Long"],"title":"PerpActionType","description":"Shared enum for perpetual trade action types (combined buy/sell with position actions)."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"SmartMoneyPerpTradesSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/SmartMoneyPerpTradesSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"SmartMoneyPerpTradesSortOrder"},"SmartMoneyPerpTradesSortField":{"type":"string","enum":["block_timestamp","token_amount","price_usd","value_usd"],"title":"SmartMoneyPerpTradesSortField","description":"Enum for sortable fields in smart money perp trades."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"SmartMoneyPerpTradesResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SmartMoneyPerpTrade"},"type":"array","title":"Data","description":"List of smart money perpetual trade records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"SmartMoneyPerpTradesResponse","description":"Response model for smart money perpetual trades endpoint.\n\nContains the filtered smart money perpetual trades data with metadata."},"SmartMoneyPerpTrade":{"properties":{"trader_address_label":{"type":"string","title":"Trader Address Label","description":"Name of the trader, based on Nansen labels"},"trader_address":{"type":"string","title":"Trader Address","description":"Hexadecimal representation of the trader's address, i.e. the signer of the transaction"},"token_symbol":{"type":"string","title":"Token Symbol","description":"The token symbol"},"side":{"anyOf":[{"$ref":"#/components/schemas/PositionSide"}],"description":"The side of the position (Long or Short)"},"action":{"type":"string","title":"Action","description":"The action taken by the trader (Add, Reduce, Open, Close)"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"Trade size in contract units"},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Trade price in USD"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Notional trade value in USD"},"type":{"$ref":"#/components/schemas/TradeType","description":"The trade type (Market or Limit)"},"block_timestamp":{"type":"string","title":"Block Timestamp","description":"The timestamp of the block"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Hexadecimal representation of the transaction hash"}},"type":"object","required":["trader_address_label","trader_address","token_symbol","action","type","block_timestamp","transaction_hash"],"title":"SmartMoneyPerpTrade","description":"Individual smart money perpetual trade record.\n\nRepresents a single perpetual trade made by smart money wallets on Hyperliquid."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/smart-money/perp-trades":{"post":{"tags":["Smart Money"],"summary":"Get Smart Money Perpetual Trades Data","description":"Access real-time perpetual trading activity from smart traders and funds on Hyperliquid. This endpoint provides granular transaction-level data showing exactly what sophisticated traders are trading on perpetual contracts.\n\nKey Features:\n- Hyperliquid perpetual contracts only (no chain field needed)\n- Real-time trading data from smart money wallets\n- Detailed trade information including coin, amount, price, action, and type\n- Smart money filtering capabilities\n- Type filtering (Market/Limit)\n- Only new positions filter to show only position opening trades (defaults to false - shows all trades)","operationId":"get_smart_money_perp_trades_api_v1_smart_money_perp_trades_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyPerpTradesRequest"}}},"required":true},"responses":{"200":{"description":"Smart money perpetual trades data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyPerpTradesResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Token Perp Positions ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Returns a **current, point-in-time snapshot** of open positions for the token — there is no date-range parameter or historical look-back, and values reflect within the standard live latency. ## Get "Token God Mode" (TGM) perp positions data > Retrieve current perpetual positions for a specific token on Hyperliquid. Shows active positions with detailed metrics including entry price, mark price, leverage, PnL, and liquidation price.\ > \ > \*\*Key Features:\*\*\ > \- Hyperliquid perpetual contracts only (no chain field needed)\ > \- Real-time position tracking with live PnL calculations\ > \- Leverage and margin information\ > \- Smart money filtering capabilities\ > \- Support for both Long and Short positions\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*What are the current perp positions for a specific token?\*\*\ > 2\. \*\*Which addresses have the largest positions by value?\*\*\ > 3\. \*\*What are the unrealized gains/losses on current positions?\*\*\ > 4\. \*\*What leverage levels are traders using?\*\*\ > 5\. \*\*Which smart money wallets are holding positions?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMPerpPositionsRequest":{"properties":{"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"label_type":{"$ref":"#/components/schemas/TGMPerpPositionsLabel","description":"Label type filter","default":"all_traders"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMPerpPositionsFilters"}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMPerpPositionsSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"position_value_usd\", \"direction\": \"DESC\"}] - Sort by position value USD descending\n- [{\"field\": \"upnl_usd\", \"direction\": \"ASC\"}] - Sort by unrealized PnL ascending\n- [{\"field\": \"leverage\", \"direction\": \"DESC\"}] - Sort by leverage descending\n- [{\"field\": \"size_base\", \"direction\": \"DESC\"}] - Sort by absolute position size descending, longs and shorts together\n\n`position_size` is signed (a short is negative), so a sort on it ranks every long above every short. `size_base` sorts both sides by the size of the position."}},"additionalProperties":false,"type":"object","required":["token_symbol"],"title":"TGMPerpPositionsRequest","description":"Request model for TGM perp positions endpoint.\n\nThis endpoint provides perp positions data for a specific token."},"TGMPerpPositionsLabel":{"type":"string","enum":["smart_money","all_traders","whale","public_figure"],"title":"TGMPerpPositionsLabel","description":"TGM perp positions label types."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMPerpPositionsFilters":{"properties":{"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Include smart money labels for traders"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/LabelType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels for traders"},"address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Address","description":"Trader address filter"},"address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Address Label","description":"Trader label filter"},"side":{"anyOf":[{"$ref":"#/components/schemas/PositionSide"},{"items":{"$ref":"#/components/schemas/PositionSide"},"type":"array"},{"type":"null"}],"title":"Side","description":"Position side filter (Long or Short)"},"position_value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Position value range filter in USD"},"position_size":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Position size range filter (token amount)"},"entry_price":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Entry price range filter"},"upnl_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Unrealized PnL range filter in USD"},"funding_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Funding range filter in USD"}},"additionalProperties":false,"type":"object","title":"TGMPerpPositionsFilters","description":"Filters for TGM perp positions endpoint.\n\nThese filters control which perp positions are included in the analysis."},"LabelType":{"type":"string","enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"title":"LabelType","description":"Filter by entity label type."},"PositionSide":{"type":"string","enum":["Long","Short"],"title":"PositionSide","description":"Shared enum for position side direction."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"TGMPerpPositionsSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMPerpPositionsSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMPerpPositionsSortOrder"},"TGMPerpPositionsSortField":{"type":"string","enum":["address","address_label","side","position_value_usd","position_size","size_base","leverage","entry_price","mark_price","liquidation_price","funding_usd","upnl_usd"],"title":"TGMPerpPositionsSortField","description":"Enum for sortable fields in TGM perp positions."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMPerpPositionsResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMPerpPosition"},"type":"array","title":"Data","description":"List of TGM perp position records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TGMPerpPositionsResponse","description":"Response model for TGM perp positions endpoint.\n\nContains a list of perp position records with pagination and metadata."},"TGMPerpPosition":{"properties":{"address":{"anyOf":[{"type":"string"}],"title":"Address","description":"The wallet address of the trader."},"address_label":{"anyOf":[{"type":"string"}],"title":"Address Label","description":"Wallet or labeled entity holding the position."},"side":{"anyOf":[{"$ref":"#/components/schemas/PositionSide"}],"description":"Position direction (Long/Short)"},"position_value_usd":{"anyOf":[{"type":"number"}],"title":"Position Value Usd","description":"USD notional size of the position."},"position_size":{"anyOf":[{"type":"number"}],"title":"Position Size","description":"The position size (token amount)."},"leverage":{"type":"string","title":"Leverage","description":"The leverage applied to the position."},"leverage_type":{"anyOf":[{"type":"string"}],"title":"Leverage Type","description":"The type of leverage used, e.g., cross or isolated."},"entry_price":{"anyOf":[{"type":"number"}],"title":"Entry Price","description":"Average price where the position was opened."},"mark_price":{"anyOf":[{"type":"number"}],"title":"Mark Price","description":"The current mark price of the asset."},"liquidation_price":{"anyOf":[{"type":"number"}],"title":"Liquidation Price","description":"The price at which the position would be liquidated."},"funding_usd":{"anyOf":[{"type":"number"}],"title":"Funding Usd","description":"Net funding paid (-) or received (+) since entry."},"upnl_usd":{"anyOf":[{"type":"number"}],"title":"Upnl Usd","description":"Unrealized profit/loss including funding."}},"type":"object","required":["leverage"],"title":"TGMPerpPosition","description":"Individual TGM perp position record.\n\nRepresents a single perp position."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/perp-positions":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) perp positions data","description":"Retrieve current perpetual positions for a specific token on Hyperliquid. Shows active positions with detailed metrics including entry price, mark price, leverage, PnL, and liquidation price.\n\n**Key Features:**\n- Hyperliquid perpetual contracts only (no chain field needed)\n- Real-time position tracking with live PnL calculations\n- Leverage and margin information\n- Smart money filtering capabilities\n- Support for both Long and Short positions\n\n**What it helps to answer:**\n\n1. **What are the current perp positions for a specific token?**\n2. **Which addresses have the largest positions by value?**\n3. **What are the unrealized gains/losses on current positions?**\n4. **What leverage levels are traders using?**\n5. **Which smart money wallets are holding positions?**","operationId":"get_tgm_perp_positions_api_v1_tgm_perp_positions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPerpPositionsRequest"}}},"required":true},"responses":{"200":{"description":"TGM perp positions data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPerpPositionsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Token Perp Trades ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Covers the Hyperliquid perpetuals dataset (reliable from **May 2025**), not per-chain history — see the Hyperliquid note on the coverage page. ## Get "Token God Mode" (TGM) perp trades data > Retrieve perpetual trade data for a specific token on Hyperliquid. Shows individual trades with detailed information including trader address, trade side (Long/Short), action type (Add/Reduce/Open/Close), order type (Market/Limit), and trade metrics.\ > \ > \*\*Key Features:\*\*\ > \- Hyperliquid perpetual contracts only\ > \- Smart money filtering capabilities\ > \- Detailed trade breakdown with parsed action fields\ > \- Support for both Long and Short position trading\ > \- Market and Limit order types\ > \ > \*\*Request Parameters:\*\*\ > \- \`token\_symbol\`: Token symbol to fetch trades for (e.g., "BTC", "ETH")\ > \- \`date\`: Date range for the trades\ > \- \`filters\`: Additional filters for side, action, order\_type, etc.\ > \- \`pagination\`: Page and per\_page parameters ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMPerpTradesRequest":{"properties":{"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"date":{"$ref":"#/components/schemas/DateRange","description":"ISO 8601 date-time range object with optional from and to fields"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMPerpTradesFilters"}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMPerpTradesSortOrder"},"type":"array"}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"block_timestamp\", \"direction\": \"DESC\"}] - Sort by timestamp descending\n- [{\"field\": \"value_usd\", \"direction\": \"DESC\"}] - Sort by trade value descending\n\nDefault: block_timestamp DESC, transaction_hash ASC, trader_address ASC (ensures stable pagination and prevents duplicate rows)"}},"additionalProperties":false,"type":"object","required":["token_symbol","date"],"title":"TGMPerpTradesRequest","description":"Request model for TGM perp trades endpoint.\n\nThis endpoint provides perp trades data for a specific token."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMPerpTradesFilters":{"properties":{"trader_address":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address","description":"Trader address filter"},"trader_address_label":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Trader Address Label","description":"Trader label filter"},"side":{"anyOf":[{"$ref":"#/components/schemas/PositionSide"},{"items":{"$ref":"#/components/schemas/PositionSide"},"type":"array"},{"type":"null"}],"title":"Side","description":"Position side filter (Long or Short)"},"action":{"anyOf":[{"$ref":"#/components/schemas/PerpActionType"},{"items":{"$ref":"#/components/schemas/PerpActionType"},"type":"array"},{"type":"null"}],"title":"Action","description":"Action filter with combined buy/sell direction (e.g., 'Buy - Add Long', 'Sell - Reduce Long')"},"order_type":{"anyOf":[{"$ref":"#/components/schemas/OrderType"},{"items":{"$ref":"#/components/schemas/OrderType"},"type":"array"},{"type":"null"}],"title":"Order Type","description":"Order type filter (MARKET or LIMIT)"},"token_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Token amount range filter"},"price_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Price range filter in USD"},"value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Trade value range filter in USD"},"include_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Include Smart Money Labels","description":"Include smart money labels"},"exclude_smart_money_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/SmartMoneyFilterType"},"type":"array"}],"title":"Exclude Smart Money Labels","description":"Exclude smart money labels"}},"additionalProperties":false,"type":"object","title":"TGMPerpTradesFilters","description":"Filters for TGM perp trades endpoint.\n\nThese filters control which perp trades are included in the results."},"PositionSide":{"type":"string","enum":["Long","Short"],"title":"PositionSide","description":"Shared enum for position side direction."},"PerpActionType":{"type":"string","enum":["Buy - Add Long","Buy - Reduce Short","Buy - Open Long","Buy - Close Short","Sell - Add Short","Sell - Reduce Long","Sell - Open Short","Sell - Close Long"],"title":"PerpActionType","description":"Shared enum for perpetual trade action types (combined buy/sell with position actions)."},"OrderType":{"type":"string","enum":["MARKET","LIMIT"],"title":"OrderType","description":"Order type."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"SmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart HL Perps Trader"],"title":"SmartMoneyFilterType","description":"Filter by smart money label type."},"TGMPerpTradesSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMPerpTradesSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMPerpTradesSortOrder"},"TGMPerpTradesSortField":{"type":"string","enum":["block_timestamp","token_amount","value_usd","transaction_hash","trader_address"],"title":"TGMPerpTradesSortField","description":"Enum for sortable fields in TGM perp trades."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMPerpTradesResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMPerpTrade"},"type":"array","title":"Data","description":"List of TGM perp trade records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TGMPerpTradesResponse","description":"Response model for TGM perp trades endpoint.\n\nContains a list of perp trade records with pagination and metadata."},"TGMPerpTrade":{"properties":{"trader_address_label":{"anyOf":[{"type":"string"}],"title":"Trader Address Label","description":"The label associated with the trader"},"trader_address":{"type":"string","title":"Trader Address","description":"The trader's address"},"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","description":"The symbol of the token"},"side":{"anyOf":[{"$ref":"#/components/schemas/PositionSide"}],"description":"The side of the position (Long or Short)"},"action":{"type":"string","title":"Action","description":"The action taken by the trader (Add, Reduce, Open, Close)"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"The amount of the specified token traded"},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Average fill price in USD across all fills in the trade, from exchange data."},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"The value in USD"},"type":{"$ref":"#/components/schemas/OrderType","description":"The order type (MARKET or LIMIT)"},"block_timestamp":{"type":"string","title":"Block Timestamp","description":"The block timestamp for the transaction"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"A representative transaction hash for this trade. Note: A single row may aggregate multiple fills that occurred at the same timestamp. If the trader had fills across multiple transactions at the exact same millisecond, only one transaction_hash is shown. The token_amount and value_usd reflect the total across all fills."}},"type":"object","required":["trader_address","action","type","block_timestamp","transaction_hash"],"title":"TGMPerpTrade","description":"Individual TGM perp trade record.\n\nRepresents a single perp trade with parsed action fields."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/tgm/perp-trades":{"post":{"tags":["Token God Mode"],"summary":"Get \"Token God Mode\" (TGM) perp trades data","description":"Retrieve perpetual trade data for a specific token on Hyperliquid. Shows individual trades with detailed information including trader address, trade side (Long/Short), action type (Add/Reduce/Open/Close), order type (Market/Limit), and trade metrics.\n\n**Key Features:**\n- Hyperliquid perpetual contracts only\n- Smart money filtering capabilities\n- Detailed trade breakdown with parsed action fields\n- Support for both Long and Short position trading\n- Market and Limit order types\n\n**Request Parameters:**\n- `token_symbol`: Token symbol to fetch trades for (e.g., \"BTC\", \"ETH\")\n- `date`: Date range for the trades\n- `filters`: Additional filters for side, action, order_type, etc.\n- `pagination`: Page and per_page parameters","operationId":"get_tgm_perp_trades_api_v1_tgm_perp_trades_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPerpTradesRequest"}}},"required":true},"responses":{"200":{"description":"TGM perp trades data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMPerpTradesResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Backtesting Data Backtest your strategies against the same onchain intelligence that powers Nansen at any point in time. The Nansen API introduces a family of **historical endpoints:** point-in-time versions of our most-used endpoints. Pass a past date, and the API reconstructs holders, flows, PnL, screener results, and wallet state using the onchain data, prices, and label cohorts available for that historical cutoff. Use these endpoints to backtest without manually collecting snapshots. Read each endpoint's label-history caveats before treating its output as a signal observable at the time. ### 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 a historical cutoff, while accounting for documented restatements or corrections. ### 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.
CategoryEndpointsUse case
Token God Modetgm/historical-top-holders, tgm/historical-dex-trades, tgm/historical-who-bought-sold, tgm/historical-token-flow-summary, tgm/historical-pnl-leaderboard, tgm/historical-token-ohlcv, tgm/historical-token-quant-scoresReconstruct a token's market structure, holder base, and trading activity on any past date.
Token Screenertoken-screener/historicalRe-run screeners as of a past date to test signal quality and ranking stability.
Smart Moneysmart-money/historical-token-balances, tgm/historical-token-recent-flows-summary-perpsSee historical Smart Money token holdings and Hyperliquid perp exposure.
Profiler (Wallets)profiler/address/historical-token-balances, profiler/address/historical-transactions, profiler/historical-transaction-lookupInspect any wallet's balances and transactions as they stood at a point in time.
### Pricing Historical endpoints cost **5× the credits of their real-time counterpart**, reflecting the additional indexing required to serve point-in-time data.
EndpointCredits per call
tgm/historical-dex-trades5
tgm/historical-who-bought-sold5
tgm/historical-token-flow-summary5
token-screener/historical5
profiler/address/historical-token-balances5
profiler/address/historical-transactions5
profiler/historical-transaction-lookup5
tgm/historical-top-holders25
tgm/historical-pnl-leaderboard25
tgm/historical-token-quant-scores25
smart-money/historical-token-balances25
tgm/historical-token-recent-flows-summary-perps5
### Stability and restatements Historical endpoints are designed to avoid look-ahead bias: labels, balances, prices, and activity windows are evaluated for the requested historical cutoff where point-in-time data is available. This does not mean an identical request is guaranteed to remain byte-identical forever. Results may change after late-arriving indexed data, pricing fixes, label-history corrections, symbol or sector reclassification, blacklist updates, or endpoint-specific backfills. For `tgm/historical-token-flow-summary`, segment labels are resolved at `date_to`. For multi-date ranges, `date_to` is the cohort date used for segment membership across the requested flow window. For a single-day request, the endpoint still computes the result from the current historical datasets for that cutoff; it is not a frozen API response snapshot. For `token-screener/historical`, the default all-traders mode uses historical activity and historical daily token pricing. Smart Money and notable-label modes use cohort data prepared for each historical day. Token metadata, sectors, blacklist flags, and corrected historical data may still be restated. For `smart-money/historical-token-balances`, balances are read for the requested `as_of_date`; token metadata, sectors, blacklist flags, and corrected historical pricing or balance data may still be restated. For [Historical Smart Money Perps Positions](/api/backtesting-data/historical-smart-money-perps-positions), date snapshots and some timestamp snapshots use labels assigned retrospectively. Cohort membership may include look-ahead bias, and some label filters can reflect current fund membership. This differs from later data corrections or restatements. ### 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. # Historical Token Screener {% hint style="info" %} **Note:** This is a beta endpoint (`/api/v1beta1/`). Request shapes, response fields, and pricing may change as we iterate. {% endhint %} ## Get Historical Token Screener (Beta) > \*\*Beta — subject to breaking changes.\*\*\ > \ > Historical token screener data anchored to \`to\_date\` over a \`timeframe\_days\` window.\ > \ > Output columns match the production token screener API response shape exactly.\ > \ > When \`trader\_type='sm'\` (or the deprecated \`only\_smart\_money=True\`),\ > volume/netflow/nof\_traders fields reflect smart-money flows only;\ > \`sm\_label\_filter\` / \`exclude\_sm\_labels\_filter\` narrow that cohort by\ > sub-label. When \`trader\_type\` is \`whale\` or \`public\_figure\`, those\ > fields reflect the corresponding notable-label cohort instead;\ > smart-money sub-label filters are not applicable in those modes.\ > \`trader\_type\` overrides \`only\_smart\_money\` when both are set.\ > \ > Use \`exclude\_sectors\` to drop tokens whose sector tags include any of the\ > listed sectors (e.g. \`\["Stablecoin"]\`).\ > \ > Results are computed from historical datasets at request time and may change\ > after late data, pricing fixes, label-history corrections, sector changes, or\ > token metadata updates. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TokenScreenerHistoricalRequest":{"properties":{"to_date":{"type":"string","format":"date","title":"To Date","description":"End date of the screener window"},"timeframe_days":{"type":"integer","maximum":365,"minimum":1,"title":"Timeframe Days","description":"Number of days in the screener window"},"chains":{"items":{"$ref":"#/components/schemas/TokenScreenerChain"},"type":"array","minItems":1,"title":"Chains","description":"Chains to include (required, must be non-empty)"},"sectors_filter":{"items":{"type":"string"},"type":"array","title":"Sectors Filter","description":"Sector filter. Empty list includes all sectors."},"exclude_sectors":{"items":{"type":"string"},"type":"array","title":"Exclude Sectors","description":"Sectors to exclude. Empty list excludes nothing."},"only_smart_money":{"type":"boolean","title":"Only Smart Money","description":"Deprecated: Use 'trader_type' instead. When True, aggregate smart money flows only. Volume/netflow/nof_traders fields reflect SM flows. Ignored when trader_type is provided.","default":false,"deprecated":true},"trader_type":{"anyOf":[{"$ref":"#/components/schemas/TraderType"}],"description":"Filter by trader type. Overrides only_smart_money when provided. Supported values: `all`, `sm`, `whale`, `public_figure`."},"filters":{"anyOf":[{"$ref":"#/components/schemas/TokenScreenerHistoricalFilters"}],"description":"Optional filters applied server-side"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"items":{"$ref":"#/components/schemas/TokenScreenerHistoricalSortOrder"},"type":"array","title":"Order By","description":"Sort order. Defaults to netflow DESC. Only the first element is used."},"apply_blacklist_filter":{"type":"boolean","title":"Apply Blacklist Filter","description":"When True, exclude blacklisted addresses from the results. Defaults to True.","default":true}},"additionalProperties":false,"type":"object","required":["to_date","timeframe_days","chains"],"title":"TokenScreenerHistoricalRequest","description":"Request model for the historical token screener endpoint.\n\nReturns token screener data anchored to to_date over a timeframe_days window.\nOutput columns match the production token screener API response shape exactly.\n\ntrader_type selects the wallet cohort whose flows drive the\nvolume/netflow/nof_traders fields:\n - 'all' (default): all wallets.\n - 'sm': smart-money cohort. sm_label_filter / exclude_sm_labels_filter\n narrow the cohort by smart-money sub-label.\n - 'whale' / 'public_figure': notable-label cohort. Label-filter fields\n are not applicable in these modes and will be rejected."},"TokenScreenerChain":{"type":"string","enum":["arbitrum","arc","avalanche","base","bitcoin","bnb","citrea","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"TokenScreenerChain","description":"Chains supported for Token Screener endpoint."},"TraderType":{"type":"string","enum":["all","sm","whale","public_figure","trending","consistent_perps_winner","high_winrate_hl_perps_trader","predicted_winner"],"title":"TraderType","description":"Trader type filter for token screener."},"TokenScreenerHistoricalFilters":{"properties":{"sm_label_filter":{"items":{"$ref":"#/components/schemas/HistoricalSmartMoneyFilterType"},"type":"array","title":"Sm Label Filter","description":"Include smart-money labels (only applied when trader_type='sm'). Empty list includes all smart-money labels.","default":[]},"exclude_sm_labels_filter":{"items":{"$ref":"#/components/schemas/HistoricalSmartMoneyFilterType"},"type":"array","title":"Exclude Sm Labels Filter","description":"Exclude smart-money labels (only applied when trader_type='sm'). Empty list excludes nothing.","default":[]},"volume_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total volume range filter in USD"},"buy_volume_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Buy volume range filter in USD"},"sell_volume_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Sell volume range filter in USD"},"market_cap_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Market cap range filter in USD"},"nof_traders":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of traders range filter"},"nof_buyers":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of buyers range filter"},"nof_sellers":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of sellers range filter"},"nof_buys":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of buy transactions range filter"},"nof_sells":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of sell transactions range filter"},"fdv_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"FDV range filter in USD"},"fdv_mc_ratio":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"FDV/MC ratio range filter"},"liquidity_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"On-chain liquidity range filter in USD"},"netflow_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Netflow range filter in USD (can be negative)"},"inflow_fdv_ratio":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Inflow/FDV ratio range filter"},"outflow_fdv_ratio":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Outflow/FDV ratio range filter"},"token_age_days":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Token age range filter in days"}},"additionalProperties":false,"type":"object","title":"TokenScreenerHistoricalFilters","description":"Filters for the historical token screener endpoint.\n\nWhen trader_type='sm' (or only_smart_money=True), sm_label_filter\nrestricts results to specific smart-money labels and\nexclude_sm_labels_filter removes them. Both lists are ignored in\nother trader_type modes."},"HistoricalSmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart Dex Trader","30D Smart Dex Trader","90D Smart Dex Trader","180D Smart Dex Trader","Smart HL Perps Trader"],"title":"HistoricalSmartMoneyFilterType","description":"Filter by smart money label type. Includes legacy label classes (e.g. Smart Dex Trader) that appear in historical data."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TokenScreenerHistoricalSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TokenScreenerHistoricalSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TokenScreenerHistoricalSortOrder"},"TokenScreenerHistoricalSortField":{"type":"string","enum":["volume","buy_volume","sell_volume","netflow","price_change","market_cap_usd","fdv","liquidity","price_usd","nof_traders","nof_buyers","nof_sellers","nof_buys","nof_sells","token_age_days"],"title":"TokenScreenerHistoricalSortField","description":"Sortable fields for the historical token screener endpoint."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TokenScreenerHistoricalResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/TokenScreenerHistoricalItem"},"type":"array","title":"Data","description":"List of token screener records"}},"type":"object","required":["pagination","data"],"title":"TokenScreenerHistoricalResponse","description":"Response model for the historical token screener endpoint."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"TokenScreenerHistoricalItem":{"properties":{"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"chain":{"type":"string","title":"Chain","description":"Blockchain chain"},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Token price in USD at to_date"},"price_change":{"anyOf":[{"type":"number"}],"title":"Price Change","description":"Price change over the timeframe as a ratio"},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Market cap in USD (falls back to FDV if zero)"},"fdv":{"anyOf":[{"type":"number"}],"title":"Fdv","description":"Fully diluted valuation in USD"},"fdv_mc_ratio":{"anyOf":[{"type":"number"}],"title":"Fdv Mc Ratio","description":"FDV / market cap ratio"},"volume":{"anyOf":[{"type":"number"}],"title":"Volume","description":"Total DEX volume (buy + sell) in USD over the timeframe"},"buy_volume":{"anyOf":[{"type":"number"}],"title":"Buy Volume","description":"Buy volume in USD over the timeframe"},"sell_volume":{"anyOf":[{"type":"number"}],"title":"Sell Volume","description":"Sell volume in USD over the timeframe"},"netflow":{"anyOf":[{"type":"number"}],"title":"Netflow","description":"Net flow (buy - sell) in USD over the timeframe"},"inflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Inflow Fdv Ratio","description":"Buy volume / FDV ratio"},"outflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Outflow Fdv Ratio","description":"Sell volume / FDV ratio"},"token_age_days":{"anyOf":[{"type":"integer"}],"title":"Token Age Days","description":"Days since token deployment as of to_date"},"liquidity":{"anyOf":[{"type":"number"}],"title":"Liquidity","description":"Total on-chain liquidity in USD at to_date"},"sectors":{"items":{"type":"string"},"type":"array","title":"Sectors","description":"Token sector classifications"}},"type":"object","required":["token_address","token_symbol","chain"],"title":"TokenScreenerHistoricalItem","description":"Single token screener record for a historical date window."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1beta1/token-screener/historical":{"post":{"tags":["Token Screener"],"summary":"Get Historical Token Screener (Beta)","description":"**Beta — subject to breaking changes.**\n\nHistorical token screener data anchored to `to_date` over a `timeframe_days` window.\n\nOutput columns match the production token screener API response shape exactly.\n\nWhen `trader_type='sm'` (or the deprecated `only_smart_money=True`),\nvolume/netflow/nof_traders fields reflect smart-money flows only;\n`sm_label_filter` / `exclude_sm_labels_filter` narrow that cohort by\nsub-label. When `trader_type` is `whale` or `public_figure`, those\nfields reflect the corresponding notable-label cohort instead;\nsmart-money sub-label filters are not applicable in those modes.\n`trader_type` overrides `only_smart_money` when both are set.\n\nUse `exclude_sectors` to drop tokens whose sector tags include any of the\nlisted sectors (e.g. `[\"Stablecoin\"]`).\n\nResults are computed from historical datasets at request time and may change\nafter late data, pricing fixes, label-history corrections, sector changes, or\ntoken metadata updates.","operationId":"get_token_screener_historical_beta_api_v1beta1_token_screener_historical_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenScreenerHistoricalRequest"}}},"required":true},"responses":{"200":{"description":"Historical token screener data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenScreenerHistoricalResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Historical Top Holders {% hint style="info" %} **Note:** This is a beta endpoint (`/api/v1beta1/`). Request shapes, response fields, and pricing may change as we iterate. {% endhint %} ## Get historical "Token God Mode" (TGM) top holders (Beta) > \*\*Beta — subject to breaking changes.\*\*\ > \ > Top token holders at a historical \`as\_of\_date\` with temporally-correct labels.\ > Labels are resolved from label history tables to avoid forward-looking bias.\ > \ > \*\*Key differences from \`/tgm/holders\`:\*\*\ > \- Accepts an explicit \`as\_of\_date\` (Date) instead of returning current state\ > \- Labels resolved at \`as\_of\_date\`, not from current-state dictionaries\ > \- \`value\_usd\` priced at the historical median price for \`as\_of\_date\`\ > \- The \`filters.include\_sm\_labels\` field only sub-restricts the \`smart\_money\` bucket;\ > to switch buckets use the top-level \`label\_type\` field\ > \- No dust-filter default — set filters at the caller side if needed\ > \ > \*\*Performance:\*\* Can be slow for high-volume tokens (USDC, native ETH, etc.). ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMHistoricalTopHoldersRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TGMHistoricalChain","description":"Blockchain chain. Currently base, bnb, ethereum, solana."},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"as_of_date":{"type":"string","title":"As Of Date","description":"Historical date (YYYY-MM-DD) to compute holder balances at."},"label_type":{"$ref":"#/components/schemas/TGMHistoricalTopHoldersLabel","description":"Holder filter bucket. 'all_holders' returns everyone; the others restrict to a specific label class.","default":"all_holders"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMHistoricalTopHoldersFilters"}],"description":"Optional filters applied server-side"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMHistoricalTopHoldersSortOrder"},"type":"array"}],"title":"Order By","description":"Sort order. Defaults to token_amount DESC. Only the first element is used."},"apply_blacklist_filter":{"type":"boolean","title":"Apply Blacklist Filter","description":"When True, exclude blacklisted addresses from the results. Defaults to True.","default":true}},"additionalProperties":false,"type":"object","required":["chain","token_address","as_of_date"],"title":"TGMHistoricalTopHoldersRequest","description":"Request model for the historical top holders endpoint.\n\nReturns the top holders of a token at a historical `as_of_date` with\ntemporally-correct labels resolved from label history tables to avoid\nforward-looking bias.\n\nCan be slow for high-volume tokens (e.g. USDC, ETH)."},"TGMHistoricalChain":{"type":"string","enum":["base","bnb","ethereum","solana"],"title":"TGMHistoricalChain","description":"Chains supported for the TGM historical endpoints (pnl-leaderboard, who-bought-sold, top-holders, token-flow-summary)."},"TGMHistoricalTopHoldersLabel":{"type":"string","enum":["all_holders","whale","public_figure","exchange","smart_money"],"title":"TGMHistoricalTopHoldersLabel","description":"Holder label-type filter for the historical top holders endpoint."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMHistoricalTopHoldersFilters":{"properties":{"include_sm_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/HistoricalLabelType"},"type":"array"}],"title":"Include Sm Labels","description":"When label_type is 'smart_money', restrict to these specific smart-money labels (e.g. ['Fund']). Empty = all smart-money labels."}},"additionalProperties":false,"type":"object","title":"TGMHistoricalTopHoldersFilters","description":"Filters for the historical top holders endpoint.\n\nUse `label_type` (top-level field) to choose the holder bucket; this filter only\nsub-restricts the smart_money bucket."},"HistoricalLabelType":{"type":"string","enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Smart Dex Trader","30D Smart Dex Trader","90D Smart Dex Trader","180D Smart Dex Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"title":"HistoricalLabelType","description":"Filter by entity label type. Includes legacy label classes (e.g. Smart Dex Trader) that appear in historical data."},"TGMHistoricalTopHoldersSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMHistoricalTopHoldersSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMHistoricalTopHoldersSortOrder"},"TGMHistoricalTopHoldersSortField":{"type":"string","enum":["token_amount","value_usd","total_outflow","total_inflow","balance_change_24h","balance_change_7d","balance_change_30d","ownership_percentage"],"title":"TGMHistoricalTopHoldersSortField","description":"Sortable fields for the historical top holders endpoint."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMHistoricalTopHoldersResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMHistoricalTopHolder"},"type":"array","title":"Data","description":"List of historical top-holder records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TGMHistoricalTopHoldersResponse","description":"Response model for the historical top holders endpoint."},"TGMHistoricalTopHolder":{"properties":{"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","description":"Token symbol resolved at the queried date"},"address":{"anyOf":[{"type":"string"}],"title":"Address","description":"Holder wallet address"},"address_label":{"anyOf":[{"type":"string"}],"title":"Address Label","description":"Temporally-correct label resolved at as_of_date"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"Holder's cumulative token balance at as_of_date"},"total_outflow":{"anyOf":[{"type":"number"}],"title":"Total Outflow","description":"Cumulative tokens sent by the holder up to as_of_date"},"total_inflow":{"anyOf":[{"type":"number"}],"title":"Total Inflow","description":"Cumulative tokens received by the holder up to as_of_date"},"balance_change_24h":{"anyOf":[{"type":"number"}],"title":"Balance Change 24H","description":"Net token balance change on as_of_date"},"balance_change_7d":{"anyOf":[{"type":"number"}],"title":"Balance Change 7D","description":"Net token balance change over the 7 days ending at as_of_date"},"balance_change_30d":{"anyOf":[{"type":"number"}],"title":"Balance Change 30D","description":"Net token balance change over the 30 days ending at as_of_date"},"ownership_percentage":{"anyOf":[{"type":"number"}],"title":"Ownership Percentage","description":"Fraction of total supply held by this address (0-1)"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"USD value of the holder's balance at the historical price for as_of_date"}},"type":"object","title":"TGMHistoricalTopHolder","description":"Single historical top-holder record.\n\nBalances and labels are resolved at `as_of_date` using label history tables\nto avoid forward-looking bias. Mirrors the `/tgm/holders` response where\nthey overlap, and adds `token_symbol`."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1beta1/tgm/historical-top-holders":{"post":{"tags":["Token God Mode"],"summary":"Get historical \"Token God Mode\" (TGM) top holders (Beta)","description":"**Beta — subject to breaking changes.**\n\nTop token holders at a historical `as_of_date` with temporally-correct labels.\nLabels are resolved from label history tables to avoid forward-looking bias.\n\n**Key differences from `/tgm/holders`:**\n- Accepts an explicit `as_of_date` (Date) instead of returning current state\n- Labels resolved at `as_of_date`, not from current-state dictionaries\n- `value_usd` priced at the historical median price for `as_of_date`\n- The `filters.include_sm_labels` field only sub-restricts the `smart_money` bucket;\n to switch buckets use the top-level `label_type` field\n- No dust-filter default — set filters at the caller side if needed\n\n**Performance:** Can be slow for high-volume tokens (USDC, native ETH, etc.).","operationId":"get_tgm_historical_top_holders_beta_api_v1beta1_tgm_historical_top_holders_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMHistoricalTopHoldersRequest"}}},"required":true},"responses":{"200":{"description":"Historical TGM top holders data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMHistoricalTopHoldersResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Historical Token DEX Trades {% hint style="info" %} **Note:** This is a beta endpoint (`/api/v1beta1/`). Request shapes, response fields, and pricing may change as we iterate. {% endhint %} ## Get historical "Token God Mode" (TGM) DEX trades (Beta) > \*\*Beta — subject to breaking changes.\*\*\ > \ > Access historical DEX trading transactions for a specific token with temporally-correct\ > trader labels. Labels are resolved at the trade date using label history tables to\ > avoid forward-looking bias.\ > \ > \*\*Key differences from \`/tgm/dex-trades\`:\*\*\ > \- Accepts an explicit \`date\_range\` (no rolling default)\ > \- Labels resolved at the trade date, not the current state\ > \- No \`token\_address\` / \`traded\_token\_address\` in the response\ > \- No \`only\_smart\_money\` flag — use \`filters.include\_labels\` instead ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMHistoricalDexTradesRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TGMHistoricalDexTradesChain","description":"Blockchain chain"},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"date_range":{"$ref":"#/components/schemas/DateRange","description":"Historical date range with explicit from and to dates"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMHistoricalDexTradesFilters"}],"description":"Optional filters applied server-side"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMHistoricalDexTradesSortOrder"},"type":"array"}],"title":"Order By","description":"Sort order. Defaults to block_timestamp DESC. Only the first element is used."},"apply_blacklist_filter":{"type":"boolean","title":"Apply Blacklist Filter","description":"When True, exclude blacklisted addresses from the results. Defaults to True.","default":true}},"additionalProperties":false,"type":"object","required":["chain","token_address","date_range"],"title":"TGMHistoricalDexTradesRequest","description":"Request model for the historical DEX trades endpoint.\n\nReturns individual DEX trades for a token with temporally-correct trader labels\nto prevent forward-looking bias. Uses label history tables instead of\ncurrent-state label dictionaries."},"TGMHistoricalDexTradesChain":{"type":"string","enum":["base","bnb","ethereum","solana"],"title":"TGMHistoricalDexTradesChain","description":"Chains supported for the TGM historical DEX trades endpoint."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMHistoricalDexTradesFilters":{"properties":{"action":{"anyOf":[{"$ref":"#/components/schemas/TGMWhoBoughtSoldType"}],"description":"Filter by trade direction. Omit for all trades."},"include_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/HistoricalLabelType"},"type":"array"}],"title":"Include Labels","description":"Include only traders with these smart money labels"},"value_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Trade value range filter in USD"},"trader_address":{"anyOf":[{"type":"string"}],"title":"Trader Address","description":"Filter to a specific trader address"}},"additionalProperties":false,"type":"object","title":"TGMHistoricalDexTradesFilters","description":"Filters for the historical DEX trades endpoint."},"TGMWhoBoughtSoldType":{"type":"string","enum":["BUY","SELL"],"title":"TGMWhoBoughtSoldType","description":"TGM who bought/sold type."},"HistoricalLabelType":{"type":"string","enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Smart Dex Trader","30D Smart Dex Trader","90D Smart Dex Trader","180D Smart Dex Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"title":"HistoricalLabelType","description":"Filter by entity label type. Includes legacy label classes (e.g. Smart Dex Trader) that appear in historical data."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"TGMHistoricalDexTradesSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMHistoricalDexTradesSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMHistoricalDexTradesSortOrder"},"TGMHistoricalDexTradesSortField":{"type":"string","enum":["block_timestamp","estimated_value_usd","token_amount","estimated_swap_price_usd"],"title":"TGMHistoricalDexTradesSortField","description":"Sortable fields for historical DEX trades endpoint."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMHistoricalDexTradesResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMHistoricalDexTrade"},"type":"array","title":"Data","description":"List of historical DEX trade records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TGMHistoricalDexTradesResponse","description":"Response model for the historical DEX trades endpoint."},"TGMHistoricalDexTrade":{"properties":{"block_timestamp":{"type":"string","title":"Block Timestamp","description":"Block timestamp of the trade"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Transaction hash"},"trader_address":{"type":"string","title":"Trader Address","description":"Trader address"},"trader_address_label":{"anyOf":[{"type":"string"}],"title":"Trader Address Label","description":"Temporally-correct label of the trader as of the trade date"},"action":{"$ref":"#/components/schemas/TGMWhoBoughtSoldType","description":"Trade direction: BUY or SELL"},"token_name":{"type":"string","title":"Token Name","description":"Symbol of the queried token"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"Amount of the queried token traded"},"traded_token_name":{"type":"string","title":"Traded Token Name","description":"Symbol of the counter token"},"traded_token_amount":{"anyOf":[{"type":"number"}],"title":"Traded Token Amount","description":"Amount of the counter token traded"},"estimated_swap_price_usd":{"anyOf":[{"type":"number"}],"title":"Estimated Swap Price Usd","description":"Estimated per-token price in USD at trade time"},"estimated_value_usd":{"anyOf":[{"type":"number"}],"title":"Estimated Value Usd","description":"Estimated trade value in USD"}},"type":"object","required":["block_timestamp","transaction_hash","trader_address","action","token_name","token_amount","traded_token_name","traded_token_amount","estimated_swap_price_usd","estimated_value_usd"],"title":"TGMHistoricalDexTrade","description":"Single historical DEX trade record.\n\nLabels are resolved at the trade date using temporal label tables to avoid\nforward-looking bias. Differs from TGMDexTrade: no token_address or\ntraded_token_address columns (not surfaced by this endpoint)."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1beta1/tgm/historical-dex-trades":{"post":{"tags":["Token God Mode"],"summary":"Get historical \"Token God Mode\" (TGM) DEX trades (Beta)","description":"**Beta — subject to breaking changes.**\n\nAccess historical DEX trading transactions for a specific token with temporally-correct\ntrader labels. Labels are resolved at the trade date using label history tables to\navoid forward-looking bias.\n\n**Key differences from `/tgm/dex-trades`:**\n- Accepts an explicit `date_range` (no rolling default)\n- Labels resolved at the trade date, not the current state\n- No `token_address` / `traded_token_address` in the response\n- No `only_smart_money` flag — use `filters.include_labels` instead","operationId":"get_tgm_historical_dex_trades_beta_api_v1beta1_tgm_historical_dex_trades_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMHistoricalDexTradesRequest"}}},"required":true},"responses":{"200":{"description":"Historical TGM DEX trades data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMHistoricalDexTradesResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Historical Token PnL Leaderboard {% hint style="info" %} **Note:** This is a beta endpoint (`/api/v1beta1/`). Request shapes, response fields, and pricing may change as we iterate. {% endhint %} ## Get historical "Token God Mode" (TGM) PnL leaderboard (Beta) > \*\*Beta — subject to breaking changes.\*\*\ > \ > Per-trader PnL statistics for a specific token over a historical date range with\ > temporally-correct labels resolved at \`date\_to\`. Uses label history tables to\ > avoid forward-looking bias.\ > \ > \*\*Key differences from \`/tgm/pnl-leaderboard\`:\*\*\ > \- Accepts an explicit \`date\_range\` with Date-only granularity\ > \- Labels resolved at \`date\_to\`, not the current state\ > \- Supports page-based pagination via \`per\_page\` and \`page\`\ > \- Filter parameters are applied server-side before pagination ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMHistoricalPnlLeaderboardRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TGMHistoricalChain","description":"Blockchain chain. Currently base, bnb, ethereum, solana."},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"date_range":{"$ref":"#/components/schemas/DateRange","description":"Historical date range. Dates are truncated to YYYY-MM-DD server-side."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters."},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMHistoricalPnlLeaderboardFilters"}],"description":"Optional filters applied server-side"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMHistoricalPnlLeaderboardSortOrder"},"type":"array"}],"title":"Order By","description":"Sort order. Defaults to pnl_usd_total DESC. Only the first element is used."},"apply_blacklist_filter":{"type":"boolean","title":"Apply Blacklist Filter","description":"When True, exclude blacklisted addresses from the results. Defaults to True.","default":true}},"additionalProperties":false,"type":"object","required":["chain","token_address","date_range"],"title":"TGMHistoricalPnlLeaderboardRequest","description":"Request model for the historical PnL leaderboard endpoint.\n\nReturns per-trader PnL statistics for a token over a date range with\ntemporally-correct labels resolved at date_to. Uses label history tables\nto avoid forward-looking bias.\n\nSupports page-based pagination via per_page and page."},"TGMHistoricalChain":{"type":"string","enum":["base","bnb","ethereum","solana"],"title":"TGMHistoricalChain","description":"Chains supported for the TGM historical endpoints (pnl-leaderboard, who-bought-sold, top-holders, token-flow-summary)."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMHistoricalPnlLeaderboardFilters":{"properties":{"trader_address":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Trader Address","description":"Filter to specific trader addresses (empty = all traders)"},"pnl_usd_total":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total PnL range filter in USD"},"roi_percent_total":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total ROI percentage range filter"},"pnl_usd_realised":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Realised PnL range filter in USD"},"roi_percent_realised":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Realised ROI percentage range filter"},"pnl_usd_unrealised":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Unrealised PnL range filter in USD"},"roi_percent_unrealised":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Unrealised ROI percentage range filter"},"netflow_amount_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Netflow range filter in USD"},"holding_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Holding value range filter in USD"},"nof_trades":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Number of trades range filter"},"still_holding_balance_ratio":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Ratio of current holdings to max balance held"},"holding_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Current token holding amount range filter"},"nof_buys":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Number of buy trades range filter"},"nof_sells":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Number of sell trades range filter"},"bought_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total bought token amount range filter"},"sold_amount":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total sold token amount range filter"},"bought_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total bought volume range filter in USD"},"sold_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Total sold volume range filter in USD"},"max_balance_held":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Peak token balance ever held range filter"},"max_balance_held_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Peak token balance in USD ever held range filter"}},"additionalProperties":false,"type":"object","title":"TGMHistoricalPnlLeaderboardFilters","description":"Filters for the historical PnL leaderboard endpoint."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"TGMHistoricalPnlLeaderboardSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMHistoricalPnlLeaderboardSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMHistoricalPnlLeaderboardSortOrder"},"TGMHistoricalPnlLeaderboardSortField":{"type":"string","enum":["pnl_usd_total","roi_percent_total","pnl_usd_realised","roi_percent_realised","pnl_usd_unrealised","roi_percent_unrealised","holding_usd","holding_amount","nof_trades","still_holding_balance_ratio","netflow_amount_usd","max_balance_held","max_balance_held_usd","nof_buys","nof_sells","bought_amount","sold_amount","bought_usd","sold_usd"],"title":"TGMHistoricalPnlLeaderboardSortField","description":"Sortable fields for the historical PnL leaderboard endpoint."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMHistoricalPnlLeaderboardResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMPnlLeaderboard"},"type":"array","title":"Data","description":"List of historical PnL leaderboard records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TGMHistoricalPnlLeaderboardResponse","description":"Response model for the historical PnL leaderboard endpoint."},"TGMPnlLeaderboard":{"properties":{"trader_address":{"type":"string","title":"Trader Address","description":"Hexadecimal representation of the trader's address."},"trader_address_label":{"anyOf":[{"type":"string"}],"title":"Trader Address Label","description":"Nansen name of the trader"},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Token price in USD at date_to. Uses latest spot price if date_to is today or later, otherwise the daily median price for that date."},"pnl_usd_realised":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Realised","description":"Realised profit and loss in USD."},"pnl_usd_unrealised":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Unrealised","description":"Unrealised profit and loss in USD."},"holding_amount":{"anyOf":[{"type":"number"}],"title":"Holding Amount","description":"Current token balance"},"holding_usd":{"anyOf":[{"type":"number"}],"title":"Holding Usd","description":"USD value of token balance"},"max_balance_held":{"anyOf":[{"type":"number"}],"title":"Max Balance Held","description":"Maximum amount of tokens held at some point in time."},"max_balance_held_usd":{"anyOf":[{"type":"number"}],"title":"Max Balance Held Usd","description":"Maximum amount of tokens in current USD value, held at some point in time."},"still_holding_balance_ratio":{"anyOf":[{"type":"number"}],"title":"Still Holding Balance Ratio","description":"The ratio of current holdings to max balance held."},"netflow_amount_usd":{"anyOf":[{"type":"number"}],"title":"Netflow Amount Usd","description":"Netflow amount in USD."},"netflow_amount":{"anyOf":[{"type":"number"}],"title":"Netflow Amount","description":"Netflow amount."},"roi_percent_total":{"anyOf":[{"type":"number"}],"title":"Roi Percent Total","description":"Total ROI."},"roi_percent_realised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Realised","description":"Realised ROI."},"roi_percent_unrealised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Unrealised","description":"Unrealised ROI."},"pnl_usd_total":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Total","description":"Total PNL in USD."},"nof_trades":{"anyOf":[{"type":"integer"}],"title":"Nof Trades","description":"Number of trades."}},"type":"object","required":["trader_address"],"title":"TGMPnlLeaderboard","description":"Individual TGM PnL leaderboard record.\nRepresents a single trader's PnL performance for a specific token."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1beta1/tgm/historical-pnl-leaderboard":{"post":{"tags":["Token God Mode"],"summary":"Get historical \"Token God Mode\" (TGM) PnL leaderboard (Beta)","description":"**Beta — subject to breaking changes.**\n\nPer-trader PnL statistics for a specific token over a historical date range with\ntemporally-correct labels resolved at `date_to`. Uses label history tables to\navoid forward-looking bias.\n\n**Key differences from `/tgm/pnl-leaderboard`:**\n- Accepts an explicit `date_range` with Date-only granularity\n- Labels resolved at `date_to`, not the current state\n- Supports page-based pagination via `per_page` and `page`\n- Filter parameters are applied server-side before pagination","operationId":"get_tgm_historical_pnl_leaderboard_beta_api_v1beta1_tgm_historical_pnl_leaderboard_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMHistoricalPnlLeaderboardRequest"}}},"required":true},"responses":{"200":{"description":"Historical TGM PnL leaderboard data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMHistoricalPnlLeaderboardResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Historical Token OHLCV {% hint style="info" %} **Note:** This is a beta endpoint (`/api/v1beta1/`). Request shapes, response fields, and pricing may change as we iterate. {% endhint %} ## Get historical "Token God Mode" (TGM) token OHLCV (Beta) > \*\*Beta — subject to breaking changes.\*\*\ > \ > Historical counterpart of \`/tgm/token-ohlcv\`. Returns OHLCV candles over\ > a window anchored to exactly one of \`as\_of\_date\` or \`as\_of\_ts\`.\ > \ > \*\*Differences from \`/tgm/token-ohlcv\`:\*\*\ > \- Flat date contract: \`date\_from\` + \`as\_of\_date\` (no \`date\` / \`date\_range\`\ > wrapper). \`as\_of\_date\` is the data-window upper bound.\ > \- Hyperliquid requests may instead provide a timezone-aware \`as\_of\_ts\`; only\ > candles completed by that exact instant are returned. A candle whose interval\ > ends exactly at \`as\_of\_ts\` is included.\ > \- High-tf (\`1d\`, \`1w\`) supports \`apply\_blacklist\_filter\` to exclude\ > blacklisted token prices from \`volume\_usd\`.\ > \- Low-tf (\`5m\`, \`15m\`, \`30m\`, \`1h\`, \`4h\`) does \*\*not\*\* support\ > \`apply\_blacklist\_filter\`; passing it returns 400.\ > \- \`4h\` always excludes its trailing partial bucket, for spot and Hyperliquid\ > alike, with either \`as\_of\_date\` or \`as\_of\_ts\`. Other low-tf timeframes may\ > still include a partial trailing bucket with \`as\_of\_date\`.\ > \- For \`4h\`, a date-only \`as\_of\_date\` (e.g. \`2026-04-15\`) means through the\ > end of that day, so the day's final completed bucket (\`20:00\`-\`24:00\`) is\ > included. A datetime-valued \`as\_of\_date\` is an exact instant instead: e.g.\ > \`2026-04-15T23:59:59Z\` excludes that same bucket, because it has not\ > closed yet at \`23:59:59\`.\ > \ > \*\*Accepted timeframes:\*\* \`5m\`, \`15m\`, \`30m\`, \`1h\`, \`4h\`, \`1d\`, \`1w\`.\ > \`1m\` and \`1M\` are not supported.\ > \ > \*\*Hyperliquid:\*\* \`chain="hyperliquid"\` is supported; pass the coin symbol\ > (e.g. \`"BTC"\`, \`"HYPE"\`, \`"@1"\`, \`"XYZ/USDC"\`) in \`token\_address\`. The\ > \`apply\_blacklist\_filter\` flag is not accepted for Hyperliquid; market-cap\ > fields are returned as \`null\` (HL perps have no market-cap concept). Candles\ > from 2025-05-29 are built from fills and match the exchange's own candles;\ > \`volume\` is base units and \`volume\_usd\` is \`volume × close\`, as on\ > \`/tgm/token-ohlcv\`. Both are \`null\` before 2025-05-29 (mark-price candles,\ > no volume) and on the trailing partial bucket when \`as\_of\_date\` lands\ > mid-bucket on a day or week timeframe. Weekly candles start Thursday\ > 00:00 UTC, as on the exchange. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMHistoricalTokenOHLCVRequest":{"properties":{"chain":{"$ref":"#/components/schemas/HistoricalTokenOHLCVChain","description":"Blockchain chain (ethereum, solana, base, bnb, hyperliquid)."},"token_address":{"type":"string","title":"Token Address","description":"Token contract address. For chain='hyperliquid', pass the coin symbol instead (e.g. \"BTC\", \"HYPE\", \"@1\", \"XYZ/USDC\")."},"date_from":{"type":"string","title":"Date From","description":"Start of the data window, ISO 8601 (date or datetime)."},"as_of_date":{"anyOf":[{"type":"string"}],"title":"As Of Date","description":"Snapshot anchor; semantically equivalent to date_to. The data window is [date_from, as_of_date]. Date-only values are treated as end-of-day. Asymmetry: the blacklist anchor uses the date part only, while the data-window upper bound preserves the time component if supplied. So as_of_date='2025-06-07T15:30:00Z' clamps the data to 15:30 but evaluates the blacklist as of the full day 2025-06-07 (daily granularity)."},"as_of_ts":{"anyOf":[{"type":"string","format":"date-time"}],"title":"As Of Ts","description":"Exact UTC-normalized cutoff for Hyperliquid requests. Only candles that are complete at this timestamp are returned. Provide exactly one of `as_of_date` or `as_of_ts`."},"timeframe":{"$ref":"#/components/schemas/ResolutionEnum","description":"OHLCV interval. Accepted: 5m, 15m, 30m, 1h, 4h, 1d, 1w. 1m and 1M are not supported."},"apply_blacklist_filter":{"anyOf":[{"type":"boolean"}],"title":"Apply Blacklist Filter","description":"High-tf-only (`1d`/`1w`). When True, prices for currently-flagged blacklisted tokens resolve to NULL in `volume_usd` (prod-equivalent). When False, historical prices are returned regardless of current blacklist status. Passing this with a low-tf timeframe returns 400 — low-tf has no blacklist plumbing (sources the unfiltered 5m feed)."}},"additionalProperties":false,"type":"object","required":["chain","token_address","date_from","timeframe"],"title":"TGMHistoricalTokenOHLCVRequest","description":"Request model for the historical TGM token OHLCV endpoint."},"HistoricalTokenOHLCVChain":{"type":"string","enum":["base","bnb","ethereum","hyperliquid","solana"],"title":"HistoricalTokenOHLCVChain","description":"Chains supported for the historical Token OHLCV endpoint."},"ResolutionEnum":{"type":"string","enum":["1m","5m","15m","30m","1h","4h","1d","1w","1M"],"title":"ResolutionEnum","description":"Supported OHLCV resolution values."},"TokenOHLCVResponse":{"properties":{"chain":{"type":"string","title":"Chain","description":"Blockchain chain"},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"timeframe":{"type":"string","title":"Timeframe","description":"Time resolution used"},"data":{"items":{"$ref":"#/components/schemas/OHLCVCandle"},"type":"array","title":"Data","description":"OHLCV candle data points, ordered by interval_start"},"truncated":{"type":"boolean","title":"Truncated","description":"True if the result reached the candle cap and some candles were omitted. On most chains the cap is 50,000 candles for this token and the omitted candles are the most recent ones, since results are ordered by interval_start ascending. Hyperliquid tokens are served from Hyperliquid's own feed, which applies a smaller per-response cap of roughly 5,000 candles and omits the oldest candles instead, so the returned data starts later than requested. Narrow the date range for complete coverage.","default":false},"truncation_note":{"anyOf":[{"type":"string"}],"title":"Truncation Note","description":"Human-readable detail when 'truncated' is true, naming the cap that was reached and which end of the requested range was omitted."}},"type":"object","required":["chain","token_address","timeframe","data"],"title":"TokenOHLCVResponse","description":"Response model for Token OHLCV endpoint (single token).\n\nContains the requested OHLCV data with metadata about the request parameters."},"OHLCVCandle":{"properties":{"interval_start":{"type":"string","title":"Interval Start","description":"Start time of the candle interval (ISO datetime string)"},"open":{"anyOf":[{"type":"number"}],"title":"Open","description":"Opening price. For sub-daily timeframes (`1m`, `5m`, `15m`, `30m`, `1h`, `4h`) this is the previous completed candle's close (carry-forward), so it can fall outside the current candle's `low`–`high` range when price gaps at the interval boundary. Null on the very first (inception) candle, when no prior close exists."},"high":{"anyOf":[{"type":"number"}],"title":"High","description":"Highest price in the interval"},"low":{"anyOf":[{"type":"number"}],"title":"Low","description":"Lowest price in the interval"},"close":{"anyOf":[{"type":"number"}],"title":"Close","description":"Closing price"},"volume":{"anyOf":[{"type":"number"}],"title":"Volume","description":"Trading volume in token units. Null for `1m` resolution — token-unit volume is not available at that resolution; use `volume_usd` instead."},"volume_usd":{"anyOf":[{"type":"number"}],"title":"Volume Usd","description":"Trading volume in USD"},"market_cap":{"$ref":"#/components/schemas/MarketCapData","description":"Market capitalization data for the candle"}},"type":"object","required":["interval_start","market_cap"],"title":"OHLCVCandle","description":"Individual OHLCV candle data point."},"MarketCapData":{"properties":{"open":{"anyOf":[{"type":"number"}],"title":"Open","description":"Market cap at candle open"},"high":{"anyOf":[{"type":"number"}],"title":"High","description":"Highest market cap in the candle"},"low":{"anyOf":[{"type":"number"}],"title":"Low","description":"Lowest market cap in the candle"},"close":{"anyOf":[{"type":"number"}],"title":"Close","description":"Market cap at candle close"}},"type":"object","title":"MarketCapData","description":"Market capitalization data for OHLCV candles."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1beta1/tgm/historical-token-ohlcv":{"post":{"tags":["Token God Mode"],"summary":"Get historical \"Token God Mode\" (TGM) token OHLCV (Beta)","description":"**Beta — subject to breaking changes.**\n\nHistorical counterpart of `/tgm/token-ohlcv`. Returns OHLCV candles over\na window anchored to exactly one of `as_of_date` or `as_of_ts`.\n\n**Differences from `/tgm/token-ohlcv`:**\n- Flat date contract: `date_from` + `as_of_date` (no `date` / `date_range`\n wrapper). `as_of_date` is the data-window upper bound.\n- Hyperliquid requests may instead provide a timezone-aware `as_of_ts`; only\n candles completed by that exact instant are returned. A candle whose interval\n ends exactly at `as_of_ts` is included.\n- High-tf (`1d`, `1w`) supports `apply_blacklist_filter` to exclude\n blacklisted token prices from `volume_usd`.\n- Low-tf (`5m`, `15m`, `30m`, `1h`, `4h`) does **not** support\n `apply_blacklist_filter`; passing it returns 400.\n- `4h` always excludes its trailing partial bucket, for spot and Hyperliquid\n alike, with either `as_of_date` or `as_of_ts`. Other low-tf timeframes may\n still include a partial trailing bucket with `as_of_date`.\n- For `4h`, a date-only `as_of_date` (e.g. `2026-04-15`) means through the\n end of that day, so the day's final completed bucket (`20:00`-`24:00`) is\n included. A datetime-valued `as_of_date` is an exact instant instead: e.g.\n `2026-04-15T23:59:59Z` excludes that same bucket, because it has not\n closed yet at `23:59:59`.\n\n**Accepted timeframes:** `5m`, `15m`, `30m`, `1h`, `4h`, `1d`, `1w`.\n`1m` and `1M` are not supported.\n\n**Hyperliquid:** `chain=\"hyperliquid\"` is supported; pass the coin symbol\n(e.g. `\"BTC\"`, `\"HYPE\"`, `\"@1\"`, `\"XYZ/USDC\"`) in `token_address`. The\n`apply_blacklist_filter` flag is not accepted for Hyperliquid; market-cap\nfields are returned as `null` (HL perps have no market-cap concept). Candles\nfrom 2025-05-29 are built from fills and match the exchange's own candles;\n`volume` is base units and `volume_usd` is `volume × close`, as on\n`/tgm/token-ohlcv`. Both are `null` before 2025-05-29 (mark-price candles,\nno volume) and on the trailing partial bucket when `as_of_date` lands\nmid-bucket on a day or week timeframe. Weekly candles start Thursday\n00:00 UTC, as on the exchange.","operationId":"get_tgm_historical_token_ohlcv_beta_api_v1beta1_tgm_historical_token_ohlcv_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMHistoricalTokenOHLCVRequest"}}},"required":true},"responses":{"200":{"description":"Historical TGM Token OHLCV data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenOHLCVResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Historical Token Flow Summary {% hint style="info" %} **Note:** This is a beta endpoint (`/api/v1beta1/`). Request shapes, response fields, and pricing may change as we iterate. {% endhint %} ## Get historical "Token God Mode" (TGM) token flow summary (Beta) > \*\*Beta — subject to breaking changes.\*\*\ > \ > Aggregated token flow intelligence with temporally-correct segment labels.\ > Same response shape as \`/tgm/flow-intelligence\` plus a \`token\_symbol\` column.\ > \ > \*\*Key differences from \`/tgm/flow-intelligence\`:\*\*\ > \- Accepts an explicit \`date\_range\` (no rolling timeframe default)\ > \- Segment labels (Whale, Public Figure, Top PnL, Smart Trader) are resolved\ > at \`date\_to\` from history tables to avoid forward-looking bias\ > \- Segment columns are NULL when temporal label coverage does not yet include\ > \`date\_to\` (whale/public\_figure/top\_pnl/exchange coverage starts 2025-03-11;\ > smart\_trader is available from 2020+)\ > \- Results are computed from historical datasets at request time and may change\ > after late data, pricing fixes, label-history corrections, or token metadata\ > updates ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMHistoricalTokenFlowSummaryRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TGMHistoricalChain","description":"Blockchain chain. Currently base, bnb, ethereum, solana."},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"date_range":{"$ref":"#/components/schemas/DateRange","description":"Historical date range with explicit from and to dates. date_to is the as-of date for label resolution; the (date_from, date_to) span determines bucket resolution and the lookback window for avg_flow_usd."},"apply_blacklist_filter":{"type":"boolean","title":"Apply Blacklist Filter","description":"When True, exclude blacklisted addresses from the results. Defaults to True.","default":true}},"additionalProperties":false,"type":"object","required":["chain","token_address","date_range"],"title":"TGMHistoricalTokenFlowSummaryRequest","description":"Request model for the historical token flow summary endpoint.\n\nReturns the same per-segment flow intelligence shape as\n`/tgm/flow-intelligence` but resolved against temporal label history so\nsegment classification reflects who held a label _at_ `date_to` rather\nthan today. Use this for backtests and as-of-date analysis."},"TGMHistoricalChain":{"type":"string","enum":["base","bnb","ethereum","solana"],"title":"TGMHistoricalChain","description":"Chains supported for the TGM historical endpoints (pnl-leaderboard, who-bought-sold, top-holders, token-flow-summary)."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"TGMHistoricalTokenFlowSummaryResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMHistoricalTokenFlowSummary"},"type":"array","title":"Data","description":"List of historical token flow summary records. The endpoint returns a single aggregated row per (token_address, date_to)."},"warnings":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Warnings","description":"Optional warnings about the query results, e.g. when segment fields are NULL because temporal label data does not yet cover the requested date_to."}},"type":"object","required":["data"],"title":"TGMHistoricalTokenFlowSummaryResponse","description":"Response for the historical token flow summary endpoint."},"TGMHistoricalTokenFlowSummary":{"properties":{"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","description":"Symbol of the queried token, resolved from on-chain metadata."},"public_figure_net_flow_usd":{"anyOf":[{"type":"number"}],"title":"Public Figure Net Flow Usd","description":"Net flow (USD) for addresses labeled as Public Figure at date_to."},"public_figure_avg_flow_usd":{"anyOf":[{"type":"number"}],"title":"Public Figure Avg Flow Usd","description":"Geometric mean of absolute flow for Public Figure addresses."},"public_figure_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Public Figure Wallet Count","description":"Unique wallet count for Public Figure addresses in the period."},"top_pnl_net_flow_usd":{"anyOf":[{"type":"number"}],"title":"Top Pnl Net Flow Usd","description":"Net flow (USD) for addresses labeled as Top PnL at date_to."},"top_pnl_avg_flow_usd":{"anyOf":[{"type":"number"}],"title":"Top Pnl Avg Flow Usd","description":"Geometric mean of absolute flow for Top PnL addresses."},"top_pnl_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Top Pnl Wallet Count","description":"Unique wallet count for Top PnL addresses in the period."},"whale_net_flow_usd":{"anyOf":[{"type":"number"}],"title":"Whale Net Flow Usd","description":"Net flow (USD) for addresses labeled as Whale at date_to."},"whale_avg_flow_usd":{"anyOf":[{"type":"number"}],"title":"Whale Avg Flow Usd","description":"Geometric mean of absolute flow for Whale addresses."},"whale_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Whale Wallet Count","description":"Unique wallet count for Whale addresses in the period."},"exchange_net_flow_usd":{"anyOf":[{"type":"number"}],"title":"Exchange Net Flow Usd","description":"Net exchange flow in USD (direction inverted: deposit-to-exchange is positive). Combines CEX transfers and DEX trades."},"exchange_avg_flow_usd":{"anyOf":[{"type":"number"}],"title":"Exchange Avg Flow Usd","description":"Geometric mean of absolute exchange flow sizes."},"exchange_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Exchange Wallet Count","description":"Always 0 (matching production flow-intelligence — exchange wallet count is not tracked)."},"smart_trader_net_flow_usd":{"anyOf":[{"type":"number"}],"title":"Smart Trader Net Flow Usd","description":"Net flow (USD) for addresses labeled as Smart Trader at date_to. Available from 2020+; before 2025-03-11 covers DEX trades only."},"smart_trader_avg_flow_usd":{"anyOf":[{"type":"number"}],"title":"Smart Trader Avg Flow Usd","description":"Geometric mean of absolute flow for Smart Trader addresses."},"smart_trader_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Smart Trader Wallet Count","description":"Unique wallet count for Smart Trader addresses in the period."},"fresh_wallets_net_flow_usd":{"anyOf":[{"type":"number"}],"title":"Fresh Wallets Net Flow Usd","description":"24h fresh-wallet inflow (USD) from the most recent snapshot taken on or before date_to."},"fresh_wallets_avg_flow_usd":{"anyOf":[{"type":"number"}],"title":"Fresh Wallets Avg Flow Usd","description":"7-day daily-average fresh-wallet inflow (USD) from the snapshot."},"fresh_wallets_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Fresh Wallets Wallet Count","description":"Always 0 (matching production — fresh wallet count is not tracked separately)."}},"type":"object","title":"TGMHistoricalTokenFlowSummary","description":"Single historical token flow summary record.\n\nOutput schema mirrors `/tgm/flow-intelligence` (TGMFlowIntelligence) plus\na `token_symbol` convenience column. All segment columns are Nullable —\nNULL means the segment's temporal label data is not available for the\nqueried `date_to` (e.g. before 2025-03-11 for whale/public_figure/top_pnl/\nexchange), distinct from a zero net flow."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1beta1/tgm/historical-token-flow-summary":{"post":{"tags":["Token God Mode"],"summary":"Get historical \"Token God Mode\" (TGM) token flow summary (Beta)","description":"**Beta — subject to breaking changes.**\n\nAggregated token flow intelligence with temporally-correct segment labels.\nSame response shape as `/tgm/flow-intelligence` plus a `token_symbol` column.\n\n**Key differences from `/tgm/flow-intelligence`:**\n- Accepts an explicit `date_range` (no rolling timeframe default)\n- Segment labels (Whale, Public Figure, Top PnL, Smart Trader) are resolved\n at `date_to` from history tables to avoid forward-looking bias\n- Segment columns are NULL when temporal label coverage does not yet include\n `date_to` (whale/public_figure/top_pnl/exchange coverage starts 2025-03-11;\n smart_trader is available from 2020+)\n- Results are computed from historical datasets at request time and may change\n after late data, pricing fixes, label-history corrections, or token metadata\n updates","operationId":"get_tgm_historical_token_flow_summary_beta_api_v1beta1_tgm_historical_token_flow_summary_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMHistoricalTokenFlowSummaryRequest"}}},"required":true},"responses":{"200":{"description":"Historical TGM token flow summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMHistoricalTokenFlowSummaryResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Historical Token Quant Scores {% hint style="info" %} **Note:** This is a beta endpoint (`/api/v1beta1/`). Request shapes, response fields, and pricing may change as we iterate. {% endhint %} ## Get Historical Token Quant Scores (Beta) > \*\*Beta — subject to breaking changes.\*\*\ > \ > Point-in-time Nansen Score indicators for a token anchored to \`as\_of\_date\`.\ > \ > Percentile rankings are computed across all tokens in the same market cap group\ > at \`as\_of\_date\`, avoiding forward-looking bias. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TgmHistoricalTokenQuantScoresRequest":{"properties":{"as_of_date":{"type":"string","format":"date","title":"As Of Date","description":"Date to query indicators for"},"chain":{"$ref":"#/components/schemas/TGMChain","description":"Blockchain chain"},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"}},"additionalProperties":false,"type":"object","required":["as_of_date","chain","token_address"],"title":"TgmHistoricalTokenQuantScoresRequest","description":"Request model for the historical token quant scores endpoint.\n\nReturns point-in-time Nansen Score indicators for a token anchored to as_of_date."},"TGMChain":{"type":"string","enum":["arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","hyperliquid","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","sei","solana","sonic","starknet","sui","ton","tron"],"title":"TGMChain","description":"Chains supported in TGM (Token God Mode) endpoints."},"TgmHistoricalTokenQuantScoresResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TgmHistoricalTokenQuantScore"},"type":"array","title":"Data","description":"List of token quant score indicators"}},"type":"object","required":["data"],"title":"TgmHistoricalTokenQuantScoresResponse","description":"Response model for the historical token quant scores endpoint."},"TgmHistoricalTokenQuantScore":{"properties":{"indicator_type":{"type":"string","title":"Indicator Type","description":"Indicator type identifier"},"signal":{"anyOf":[{"type":"number"}],"title":"Signal","description":"Raw indicator signal value"},"signal_percentile":{"anyOf":[{"type":"number"}],"title":"Signal Percentile","description":"Signal percentile vs same market cap group (0-100)"},"score":{"anyOf":[{"type":"string"}],"title":"Score","description":"Qualitative score label"},"last_trigger_on":{"anyOf":[{"type":"string","format":"date-time"}],"title":"Last Trigger On","description":"Timestamp of last signal trigger"},"is_stablecoin":{"anyOf":[{"type":"boolean"}],"title":"Is Stablecoin","description":"Whether the token is classified as a stablecoin"},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Token market cap in USD at as_of_date"},"market_cap_group":{"anyOf":[{"type":"string"}],"title":"Market Cap Group","description":"Market cap group used for percentile ranking"},"model_type":{"anyOf":[{"type":"string"}],"title":"Model Type","description":"Whether indicator measures risk or reward"}},"type":"object","required":["indicator_type"],"title":"TgmHistoricalTokenQuantScore","description":"Single token quant score indicator record for a given date."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1beta1/tgm/historical-token-quant-scores":{"post":{"tags":["Token God Mode"],"summary":"Get Historical Token Quant Scores (Beta)","description":"**Beta — subject to breaking changes.**\n\nPoint-in-time Nansen Score indicators for a token anchored to `as_of_date`.\n\nPercentile rankings are computed across all tokens in the same market cap group\nat `as_of_date`, avoiding forward-looking bias.","operationId":"get_tgm_historical_token_quant_scores_beta_api_v1beta1_tgm_historical_token_quant_scores_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TgmHistoricalTokenQuantScoresRequest"}}},"required":true},"responses":{"200":{"description":"Historical token quant scores data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TgmHistoricalTokenQuantScoresResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Historical Address Balance {% hint style="info" %} **Note:** This is a beta endpoint (`/api/v1beta1/`). Request shapes, response fields, and pricing may change as we iterate. {% endhint %} ## Get Historical Balances by Address (Beta) > \*\*Beta — subject to breaking changes.\*\*\ > \ > Token balances for a wallet address as of a historical snapshot date.\ > \ > Supports EVM chains (ethereum, base, bnb) and solana. Balances are computed from on-chain transfer history\ > up to \`as\_of\_date\`. Results are ordered by USD value descending. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"ProfilerHistoricalTokenBalancesRequest":{"properties":{"address":{"type":"string","title":"Address","description":"Wallet address (EVM hex or Solana base58)"},"as_of_date":{"type":"string","format":"date","title":"As Of Date","description":"Historical snapshot date — balances are computed up to this date"},"chain":{"$ref":"#/components/schemas/ProfilerHistoricalTokenBalancesChain","description":"Chain filter"},"apply_blacklist_filter":{"type":"boolean","title":"Apply Blacklist Filter","description":"When True, exclude blacklisted addresses from the results. Defaults to True.","default":true},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"}},"additionalProperties":false,"type":"object","required":["address","as_of_date","chain"],"title":"ProfilerHistoricalTokenBalancesRequest","description":"Request model for the profiler historical token balances endpoint.\n\nReturns token balances for an address as of a historical snapshot date.\nSupports EVM chains (ethereum, base, bnb) and solana."},"ProfilerHistoricalTokenBalancesChain":{"type":"string","enum":["all","base","bnb","ethereum","mantra","solana"],"title":"ProfilerHistoricalTokenBalancesChain","description":"Chains supported for Profiler Historical Token Balances endpoint."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"ProfilerHistoricalTokenBalancesResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/ProfilerHistoricalTokenBalancesItem"},"type":"array","title":"Data","description":"List of token balance records, ordered by value_usd DESC"}},"type":"object","required":["pagination","data"],"title":"ProfilerHistoricalTokenBalancesResponse","description":"Response model for the profiler historical token balances endpoint."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ProfilerHistoricalTokenBalancesItem":{"properties":{"chain":{"type":"string","title":"Chain","description":"Blockchain chain"},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"token_symbol":{"anyOf":[{"type":"string"}],"title":"Token Symbol","description":"Token symbol"},"name":{"anyOf":[{"type":"string"}],"title":"Name","description":"Token name"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"Token balance (adjusted for decimals)"},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","description":"Token price in USD at as_of_date"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Token balance value in USD (token_amount * price_usd)"}},"type":"object","required":["chain","token_address"],"title":"ProfilerHistoricalTokenBalancesItem","description":"Single token balance record for an address at a historical date."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1beta1/profiler/address/historical-token-balances":{"post":{"tags":["Profiler"],"summary":"Get Historical Balances by Address (Beta)","description":"**Beta — subject to breaking changes.**\n\nToken balances for a wallet address as of a historical snapshot date.\n\nSupports EVM chains (ethereum, base, bnb) and solana. Balances are computed from on-chain transfer history\nup to `as_of_date`. Results are ordered by USD value descending.","operationId":"get_profiler_historical_token_balances_beta_api_v1beta1_profiler_address_historical_token_balances_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerHistoricalTokenBalancesRequest"}}},"required":true},"responses":{"200":{"description":"Historical token balance records","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerHistoricalTokenBalancesResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Historical Smart Money Positions {% hint style="info" %} **Note:** This is a beta endpoint (`/api/v1beta1/`). Request shapes, response fields, and pricing may change as we iterate. {% endhint %} ### Data Freshness & Snapshot Timing This endpoint returns **point-in-time daily snapshots** keyed by `as_of_date`. Each snapshot represents **end-of-day UTC** values for that date. * **Daily snapshots only — the current day is excluded.** Querying `as_of_date = today` (or any date whose snapshot has not yet been produced) returns an empty `data` array with HTTP 200 — never a live or partial current-day result. * **Settlement timing.** A given day's snapshot is produced by a daily batch the following morning (UTC); exact timing varies. Until that batch completes, the prior day returns empty, so in the early-UTC hours the freshest available snapshot may be two days back. Rather than assuming a fixed availability time, query the date you need and fall back to the previous day (or retry later) if it comes back empty. ## Get Historical SM Token Balances (Beta) > \*\*Beta — subject to breaking changes.\*\*\ > \ > Point-in-time smart money token balance aggregates for a given date.\ > \ > Returns SM token holdings per (chain, token\_address) pair filtered by SM labels,\ > token type, and chain. Includes 24h balance change, holder counts, share of total\ > SM holdings, and historical market cap.\ > \ > Results are computed from historical datasets at request time and may change\ > after late data, pricing fixes, label-history corrections, sector changes, or\ > token metadata updates. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"SmartMoneyHistoricalTokenBalancesRequest":{"properties":{"as_of_date":{"type":"string","format":"date","title":"As Of Date","description":"Date to query balances for"},"chains":{"items":{"$ref":"#/components/schemas/SmartMoneyChain"},"type":"array","title":"Chains","description":"Chains to include. Empty list returns all chains.","default":[]},"filters":{"anyOf":[{"$ref":"#/components/schemas/SmartMoneyHistoricalTokenBalancesFilters"}],"description":"Optional filters for SM labels and token types"},"apply_blacklist_filter":{"type":"boolean","title":"Apply Blacklist Filter","description":"When True, exclude blacklisted addresses from the results. Defaults to True.","default":true},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"}},"additionalProperties":false,"type":"object","required":["as_of_date"],"title":"SmartMoneyHistoricalTokenBalancesRequest","description":"Request model for the historical SM token balances endpoint.\n\nReturns smart money token balance aggregates for a given date, filtered by\nchain, SM label, and token type."},"SmartMoneyChain":{"type":"string","enum":["all","arbitrum","arc","avalanche","base","bnb","ethereum","hyperevm","iotaevm","linea","mantle","monad","optimism","plasma","polygon","robinhood","sei","solana","sonic"],"title":"SmartMoneyChain","description":"Chains supported in smart money analysis."},"SmartMoneyHistoricalTokenBalancesFilters":{"properties":{"sm_filter":{"items":{"$ref":"#/components/schemas/HistoricalSmartMoneyFilterType"},"type":"array","title":"Sm Filter","description":"SM label filter. Empty list includes all SM labels.","default":[]},"include_stablecoins":{"type":"boolean","title":"Include Stablecoins","description":"Whether to include stablecoin tokens","default":true},"include_native_tokens":{"type":"boolean","title":"Include Native Tokens","description":"Whether to include native tokens and LSTs/LRTs","default":true},"holders_count":{"anyOf":[{"$ref":"#/components/schemas/IntegerRangeFilter"}],"description":"Number of SM holders range filter"}},"additionalProperties":false,"type":"object","title":"SmartMoneyHistoricalTokenBalancesFilters","description":"Filters for the historical SM token balances endpoint."},"HistoricalSmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart Dex Trader","30D Smart Dex Trader","90D Smart Dex Trader","180D Smart Dex Trader","Smart HL Perps Trader"],"title":"HistoricalSmartMoneyFilterType","description":"Filter by smart money label type. Includes legacy label classes (e.g. Smart Dex Trader) that appear in historical data."},"IntegerRangeFilter":{"properties":{"min":{"anyOf":[{"type":"integer"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"integer"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"IntegerRangeFilter","description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"SmartMoneyHistoricalTokenBalancesResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SmartMoneyHistoricalTokenBalance"},"type":"array","title":"Data","description":"List of SM token balance records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"SmartMoneyHistoricalTokenBalancesResponse","description":"Response model for the historical SM token balances endpoint."},"SmartMoneyHistoricalTokenBalance":{"properties":{"chain":{"type":"string","title":"Chain","description":"Blockchain chain"},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"token_sectors":{"items":{"type":"string"},"type":"array","title":"Token Sectors","description":"Token sector classifications"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Total SM balance in USD"},"balance_24h_percent_change":{"anyOf":[{"type":"number"}],"title":"Balance 24H Percent Change","description":"24-hour percentage change in token balance amount"},"holders_count":{"anyOf":[{"type":"integer"}],"title":"Holders Count","description":"Number of SM holders with balance > $100"},"share_of_holdings_percent":{"anyOf":[{"type":"number"}],"title":"Share Of Holdings Percent","description":"This token's share of total SM holdings"},"token_age_days":{"anyOf":[{"type":"integer"}],"title":"Token Age Days","description":"Days since token deployment as of as_of_date"},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Historical market cap on as_of_date (falls back to FDV)"}},"type":"object","required":["chain","token_address","token_symbol"],"title":"SmartMoneyHistoricalTokenBalance","description":"Single SM token balance record for a given date."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1beta1/smart-money/historical-token-balances":{"post":{"tags":["Smart Money"],"summary":"Get Historical SM Token Balances (Beta)","description":"**Beta — subject to breaking changes.**\n\nPoint-in-time smart money token balance aggregates for a given date.\n\nReturns SM token holdings per (chain, token_address) pair filtered by SM labels,\ntoken type, and chain. Includes 24h balance change, holder counts, share of total\nSM holdings, and historical market cap.\n\nResults are computed from historical datasets at request time and may change\nafter late data, pricing fixes, label-history corrections, sector changes, or\ntoken metadata updates.","operationId":"get_smart_money_historical_token_balances_beta_api_v1beta1_smart_money_historical_token_balances_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyHistoricalTokenBalancesRequest"}}},"required":true},"responses":{"200":{"description":"Historical SM token balances data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartMoneyHistoricalTokenBalancesResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Historical Smart Money Perps Positions {% hint style="info" %} This is a beta endpoint under `/api/v1beta1/`. Request shapes, response fields, and pricing may change. {% endhint %} Get historical USD exposure for one Hyperliquid perp coin, split into Smart Trader, Whale, and Public Figure cohorts. Each call costs 5 credits. Send `coin` and exactly one of `as_of_date` or `as_of_ts`. A date includes the full UTC day and must be before the current UTC date. A timestamp includes positions through that exact cutoff, must include a timezone, and cannot be in the future. ```bash curl -X POST "https://api.nansen.ai/api/v1beta1/tgm/historical-token-recent-flows-summary-perps" \ -H "Content-Type: application/json" \ -H "apikey: $NANSEN_API_KEY" \ -d '{"coin": "BTC", "as_of_date": "2025-09-15"}' ``` For Smart Money backtesting, calculate net position from the Smart Trader fields: ``` net_position_usd = smart_trader_longs_usd - smart_trader_shorts_usd ``` Short exposure is a positive magnitude. `smart_trader_total_usd` is gross exposure, longs plus shorts. Use the same calculation for the Whale and Public Figure cohorts. `sm_label_filter` applies only to the Smart Trader cohort. An empty list selects `Smart HL Perps Trader`. Whale and Public Figure cohorts use fixed labels. Date snapshots and some timestamp snapshots use labels assigned retrospectively. Membership in a cohort was not necessarily knowable at the cutoff, which can introduce look-ahead bias in backtests. Some label filters can reflect current fund membership. Historical exposure is not a guarantee of a signal observable at the time. Requests before available history return an empty `data` array. Exposure fields can be `null` when cohort coverage is unavailable. Preserve those values as missing data. Top PnL fields are unsupported and always return `null`. Results may change after late data, pricing fixes, label-history corrections, or backfills. ## Get Historical Smart Money Perps Positions (Beta) > \*\*Beta. Request shapes, response fields, and pricing may change.\*\*\ > \ > Historical long, short, and total USD exposure for one Hyperliquid perp coin.\ > Returns the Smart Trader, Whale, and Public Figure cohorts.\ > \ > Supply \`coin\` and exactly one cutoff: \`as\_of\_date\` for a completed UTC date,\ > or \`as\_of\_ts\` for an exact RFC3339 timestamp with a timezone, no later than now.\ > \ > Short exposure is a positive magnitude. Net position equals longs minus\ > shorts; total exposure equals longs plus shorts. Missing cohort coverage\ > returns null exposure fields. Top PnL exposure fields are unsupported and return null.\ > \ > \`sm\_label\_filter\` narrows the Smart Trader cohort. An empty list selects\ > \`Smart HL Perps Trader\`. Whale and Public Figure cohorts are fixed.\ > \ > Date snapshots and some timestamp snapshots use labels assigned retrospectively.\ > Cohort membership was not necessarily knowable at the cutoff and can introduce\ > look-ahead bias in backtests. Some label filters can reflect current fund membership.\ > \ > Results may change after late data, pricing fixes, label-history corrections,\ > or historical data backfills. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMHistoricalTokenRecentFlowsSummaryPerpsRequest":{"properties":{"as_of_ts":{"anyOf":[{"type":"string","format":"date-time"}],"title":"As Of Ts"},"as_of_date":{"anyOf":[{"type":"string","format":"date"}],"title":"As Of Date","description":"UTC date cutoff. The full date is included."},"coin":{"type":"string","title":"Coin","description":"Hyperliquid perp coin symbol (e.g. BTC, HYPE, @1)"},"sm_label_filter":{"items":{"$ref":"#/components/schemas/HistoricalSmartMoneyFilterType"},"type":"array","title":"Sm Label Filter","description":"Smart-money sub-label filter applied to the Smart Trader cohort. Empty list resolves server-side to 'Smart HL Perps Trader' only. Has no effect on the Whale and Public Figure cohorts, which are resolved from a fixed label segment.","default":[]}},"additionalProperties":false,"type":"object","required":["coin"],"title":"TGMHistoricalTokenRecentFlowsSummaryPerpsRequest","description":"Request model for the Hyperliquid historical token recent flows summary endpoint."},"HistoricalSmartMoneyFilterType":{"type":"string","enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart Dex Trader","30D Smart Dex Trader","90D Smart Dex Trader","180D Smart Dex Trader","Smart HL Perps Trader"],"title":"HistoricalSmartMoneyFilterType","description":"Filter by smart money label type. Includes legacy label classes (e.g. Smart Dex Trader) that appear in historical data."},"TGMHistoricalTokenRecentFlowsSummaryPerpsResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/TGMHistoricalTokenRecentFlowsSummaryPerpsItem"},"type":"array","title":"Data","description":"Per-coin cohort exposure records at the requested cutoff."}},"type":"object","required":["pagination","data"],"title":"TGMHistoricalTokenRecentFlowsSummaryPerpsResponse","description":"Response model for the Hyperliquid historical token recent flows summary endpoint."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"TGMHistoricalTokenRecentFlowsSummaryPerpsItem":{"properties":{"coin":{"type":"string","title":"Coin","description":"Hyperliquid perp coin symbol"},"smart_trader_longs_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Smart Trader Longs Usd","description":"Gross long USD exposure of the Smart Trader cohort."},"smart_trader_shorts_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Smart Trader Shorts Usd","description":"Gross short USD exposure of the Smart Trader cohort (positive magnitude)."},"smart_trader_total_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Smart Trader Total Usd","description":"Gross total USD exposure of the Smart Trader cohort (longs + shorts as positive magnitudes)."},"whale_longs_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Whale Longs Usd","description":"Gross long USD exposure of the Whale cohort."},"whale_shorts_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Whale Shorts Usd","description":"Gross short USD exposure of the Whale cohort (positive magnitude)."},"whale_total_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Whale Total Usd","description":"Gross total USD exposure of the Whale cohort."},"public_figure_longs_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Public Figure Longs Usd","description":"Gross long USD exposure of the Public Figure cohort."},"public_figure_shorts_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Public Figure Shorts Usd","description":"Gross short USD exposure of the Public Figure cohort (positive magnitude)."},"public_figure_total_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Public Figure Total Usd","description":"Gross total USD exposure of the Public Figure cohort."},"top_pnl_longs_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top Pnl Longs Usd","description":"Unsupported; currently always null."},"top_pnl_shorts_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top Pnl Shorts Usd","description":"Unsupported; currently always null."},"top_pnl_total_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top Pnl Total Usd","description":"Unsupported; currently always null."}},"type":"object","required":["coin"],"title":"TGMHistoricalTokenRecentFlowsSummaryPerpsItem","description":"Single per-coin cohort exposure record at the requested cutoff."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1beta1/tgm/historical-token-recent-flows-summary-perps":{"post":{"tags":["Token God Mode"],"summary":"Get Historical Smart Money Perps Positions (Beta)","description":"**Beta. Request shapes, response fields, and pricing may change.**\n\nHistorical long, short, and total USD exposure for one Hyperliquid perp coin.\nReturns the Smart Trader, Whale, and Public Figure cohorts.\n\nSupply `coin` and exactly one cutoff: `as_of_date` for a completed UTC date,\nor `as_of_ts` for an exact RFC3339 timestamp with a timezone, no later than now.\n\nShort exposure is a positive magnitude. Net position equals longs minus\nshorts; total exposure equals longs plus shorts. Missing cohort coverage\nreturns null exposure fields. Top PnL exposure fields are unsupported and return null.\n\n`sm_label_filter` narrows the Smart Trader cohort. An empty list selects\n`Smart HL Perps Trader`. Whale and Public Figure cohorts are fixed.\n\nDate snapshots and some timestamp snapshots use labels assigned retrospectively.\nCohort membership was not necessarily knowable at the cutoff and can introduce\nlook-ahead bias in backtests. Some label filters can reflect current fund membership.\n\nResults may change after late data, pricing fixes, label-history corrections,\nor historical data backfills.","operationId":"get_tgm_historical_token_recent_flows_summary_perps_beta_api_v1beta1_tgm_historical_token_recent_flows_summary_perps_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMHistoricalTokenRecentFlowsSummaryPerpsRequest"}}},"required":true},"responses":{"200":{"description":"Historical Hyperliquid cohort exposure at the requested cutoff","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMHistoricalTokenRecentFlowsSummaryPerpsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Historical Address Transactions {% hint style="info" %} **Note:** This is a beta endpoint (`/api/v1beta1/`). Request shapes, response fields, and pricing may change as we iterate. {% endhint %} ## Get Historical Transactions for an Address (Beta) > \*\*Beta — subject to breaking changes.\*\*\ > \ > Returns the 20 most recent token transfer transactions for a wallet address as\ > of a historical snapshot date, with temporally-correct counterparty labels.\ > \ > \*\*Key differences from \`/profiler/address/transactions\`:\*\*\ > \- Accepts an explicit \`as\_of\_date\` (no rolling default)\ > \- Counterparty labels resolved from label history at \`as\_of\_date\` (no forward-looking bias)\ > \- Limited to ethereum, base, bnb, and solana\ > \- Capped at 20 results per query ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"ProfilerAddressHistoricalTransactionsRequest":{"properties":{"address":{"type":"string","title":"Address","description":"Wallet address (EVM hex or Solana base58)"},"chain":{"$ref":"#/components/schemas/ProfilerHistoricalTokenBalancesChain","description":"Blockchain chain"},"as_of_date":{"type":"string","format":"date","title":"As Of Date","description":"Historical snapshot date — only transactions on or before this date are returned, with labels resolved as of this date."},"hide_spam_token":{"type":"boolean","title":"Hide Spam Token","description":"Filter out tokens flagged as spam by Nansen","default":true},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters. The endpoint returns at most 20 rows, so pagination beyond that yields empty results."},"apply_blacklist_filter":{"type":"boolean","title":"Apply Blacklist Filter","description":"When True, exclude blacklisted addresses from the results. Defaults to True.","default":true}},"additionalProperties":false,"type":"object","required":["address","chain","as_of_date"],"title":"ProfilerAddressHistoricalTransactionsRequest","description":"Request model for the profiler historical address transactions endpoint.\n\nReturns the 20 most recent token transfer transactions for a wallet address\nas of a given historical date, with temporally-correct counterparty labels."},"ProfilerHistoricalTokenBalancesChain":{"type":"string","enum":["all","base","bnb","ethereum","mantra","solana"],"title":"ProfilerHistoricalTokenBalancesChain","description":"Chains supported for Profiler Historical Token Balances endpoint."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"ProfilerAddressHistoricalTransactionsResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/ProfilerAddressHistoricalTransactionsItem"},"type":"array","title":"Data","description":"List of historical transaction records ordered by block_timestamp DESC."}},"type":"object","required":["pagination","data"],"title":"ProfilerAddressHistoricalTransactionsResponse","description":"Response model for the profiler historical address transactions endpoint."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ProfilerAddressHistoricalTransactionsItem":{"properties":{"source_type":{"type":"string","title":"Source Type","description":"Always 'transfer'. Mirrors the production schema."},"method":{"type":"string","title":"Method","description":"Transaction method name. Falls back to 'received'/'sent' for single-transfer transactions."},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Transaction hash in human-readable format (0x-prefixed hex on EVM, base58 on Solana)"},"tokens_received":{"anyOf":[{"items":{},"type":"array"}],"title":"Tokens Received","description":"Array of token transfers received in this transaction. Each entry is a tuple of (token_symbol, token_amount, token_price_usd, token_value_usd, token_address, chain, from_address, to_address, from_address_label, to_address_label). Labels are resolved as of as_of_date."},"tokens_sent":{"anyOf":[{"items":{},"type":"array"}],"title":"Tokens Sent","description":"Array of token transfers sent in this transaction. Same tuple shape as tokens_received with negative amounts."},"volume_usd":{"anyOf":[{"type":"number"}],"title":"Volume Usd","description":"Transaction volume in USD computed from historical prices."},"block_timestamp":{"type":"string","title":"Block Timestamp","description":"Block timestamp of the transaction (ISO format)."},"chain":{"type":"string","title":"Chain","description":"Blockchain identifier for this row."}},"type":"object","required":["source_type","method","transaction_hash","block_timestamp","chain"],"title":"ProfilerAddressHistoricalTransactionsItem","description":"Single historical transaction record for a wallet address.\n\nEach row is one transaction (grouped by transaction_hash) containing arrays\nof received and sent token transfers with temporally-correct counterparty\nlabels resolved as of `as_of_date`."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1beta1/profiler/address/historical-transactions":{"post":{"tags":["Profiler"],"summary":"Get Historical Transactions for an Address (Beta)","description":"**Beta — subject to breaking changes.**\n\nReturns the 20 most recent token transfer transactions for a wallet address as\nof a historical snapshot date, with temporally-correct counterparty labels.\n\n**Key differences from `/profiler/address/transactions`:**\n- Accepts an explicit `as_of_date` (no rolling default)\n- Counterparty labels resolved from label history at `as_of_date` (no forward-looking bias)\n- Limited to ethereum, base, bnb, and solana\n- Capped at 20 results per query","operationId":"get_profiler_address_historical_transactions_beta_api_v1beta1_profiler_address_historical_transactions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressHistoricalTransactionsRequest"}}},"required":true},"responses":{"200":{"description":"Historical address transaction data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressHistoricalTransactionsResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` ## Get Historical (Time-Travel) Transaction Lookup Data (Beta) > \*\*Beta — subject to breaking changes.\*\*\ > \ > Time-travel-aware variant of \`/transaction-with-token-transfer-lookup\`.\ > \ > Returns transaction details (sender/receiver, native value, token transfers)\ > with \*\*temporally-correct labels\*\* and \*\*dual pricing\*\* (dated price at the\ > transaction's block\_timestamp + as-of-date price). Labels are resolved at\ > \`as\_of\_date\` to avoid forward-looking bias; entity labels are available from\ > 2025-03-11 onward.\ > \ > \*\*Performance\*\*\ > \ > This endpoint executes two queries sequentially:\ > \ > 1\. \*\*Hash -> timestamp resolution\*\* — can take \*\*60-170 seconds\*\* for unknown\ > hashes. Pass \`block\_timestamp\` in the request to skip this step entirely.\ > 2\. \*\*Data lookup\*\* — <1 second once the timestamp is known. ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"ProfilerHistoricalTransactionLookupRequest":{"properties":{"chain":{"$ref":"#/components/schemas/ProfilerHistoricalTransactionLookupChain","description":"Blockchain chain for the historical transaction lookup"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Transaction hash to lookup (0x-prefixed, 66 chars)"},"as_of_date":{"type":"string","format":"date","title":"As Of Date","description":"Reference date for temporal label resolution and as-of-date pricing. Must be on/after the transaction's block_timestamp. Entity labels are available from 2025-03-11 onward."},"block_timestamp":{"anyOf":[{"type":"string"}],"title":"Block Timestamp","description":"Optional block timestamp in 'YYYY-MM-DD HH:MM:SS' format. When provided, skips the slow (60-170s) hash-to-timestamp resolution step. Strongly recommended."},"apply_blacklist_filter":{"type":"boolean","title":"Apply Blacklist Filter","description":"When True, exclude blacklisted addresses from the results. Defaults to True.","default":true}},"additionalProperties":false,"type":"object","required":["chain","transaction_hash","as_of_date"],"title":"ProfilerHistoricalTransactionLookupRequest","description":"Request model for the profiler historical transaction lookup endpoint."},"ProfilerHistoricalTransactionLookupChain":{"type":"string","enum":["base","bnb","ethereum"],"title":"ProfilerHistoricalTransactionLookupChain","description":"Chains supported by the historical transaction lookup endpoint."},"ProfilerHistoricalTransactionLookupListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ProfilerHistoricalTransactionLookupResponse"},"type":"array","title":"Data","description":"List of historical transaction lookup results"}},"type":"object","required":["data"],"title":"ProfilerHistoricalTransactionLookupListResponse","description":"Wrapper response for the profiler historical transaction lookup endpoint."},"ProfilerHistoricalTransactionLookupResponse":{"properties":{"chain":{"type":"string","title":"Chain","description":"The blockchain network of the transaction"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"The unique identifier of the transaction"},"from_address":{"type":"string","title":"From Address","description":"The hexadecimal address of the sender"},"from_address_label":{"anyOf":[{"type":"string"}],"title":"From Address Label","description":"Temporally-correct label of the sender at as_of_date"},"to_address":{"type":"string","title":"To Address","description":"The hexadecimal address of the recipient"},"to_address_label":{"anyOf":[{"type":"string"}],"title":"To Address Label","description":"Temporally-correct label of the recipient at as_of_date"},"native_value":{"anyOf":[{"type":"number"}],"title":"Native Value","description":"The amount of native cryptocurrency transferred"},"dated_native_price":{"anyOf":[{"type":"number"}],"title":"Dated Native Price","description":"Native cryptocurrency price at the transaction's block_timestamp date"},"dated_native_value_usd":{"anyOf":[{"type":"number"}],"title":"Dated Native Value Usd","description":"USD value of native transfer at the transaction's block_timestamp date"},"as_of_date_native_price":{"anyOf":[{"type":"number"}],"title":"As Of Date Native Price","description":"Native cryptocurrency price at as_of_date"},"as_of_date_native_value_usd":{"anyOf":[{"type":"number"}],"title":"As Of Date Native Value Usd","description":"USD value of native transfer at as_of_date"},"receipt_status":{"anyOf":[{"type":"integer"}],"title":"Receipt Status","description":"Transaction receipt status (1 for success, 0 for failure)"},"block_timestamp":{"type":"string","title":"Block Timestamp","description":"The timestamp of the block containing the transaction"},"as_of_date":{"type":"string","title":"As Of Date","description":"The reference date used for label and pricing resolution"},"method":{"anyOf":[{"type":"string"}],"title":"Method","description":"Human-readable method signature resolved from the transaction's sig_hash. Empty string when no match is found."},"token_transfer_array":{"anyOf":[{"items":{"$ref":"#/components/schemas/HistoricalTokenTransfer"},"type":"array"}],"title":"Token Transfer Array","description":"Token transfers in this transaction (temporally-correct labels)"}},"type":"object","required":["chain","transaction_hash","from_address","from_address_label","to_address","to_address_label","native_value","dated_native_price","dated_native_value_usd","as_of_date_native_price","as_of_date_native_value_usd","receipt_status","block_timestamp","as_of_date","method","token_transfer_array"],"title":"ProfilerHistoricalTransactionLookupResponse","description":"Response row for the profiler historical transaction lookup endpoint.\n\nMirrors the /transaction-with-token-transfer-lookup response where\noverlapping. Differences:\n- Uses ``as_of_date_native_*`` instead of ``current_native_*`` (temporal pricing).\n- Adds ``method`` (resolved from sig_hash) and ``as_of_date`` fields.\n- No ``nft_transfer_array``."},"HistoricalTokenTransfer":{"properties":{"from_address":{"type":"string","title":"From Address","description":"Sender address (0x-prefixed lowercase hex)"},"from_address_label":{"type":"string","title":"From Address Label","description":"Temporally-correct label of the sender at as_of_date"},"to_address":{"type":"string","title":"To Address","description":"Receiver address (0x-prefixed lowercase hex)"},"to_address_label":{"type":"string","title":"To Address Label","description":"Temporally-correct label of the receiver at as_of_date"},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","description":"Token amount transferred (decimal-adjusted)"},"dated_price_usd":{"anyOf":[{"type":"number"}],"title":"Dated Price Usd","description":"Token price in USD at the transaction's block_timestamp date"},"dated_value_usd":{"anyOf":[{"type":"number"}],"title":"Dated Value Usd","description":"USD value of the transfer at the transaction's block_timestamp date"},"as_of_date_price_usd":{"anyOf":[{"type":"number"}],"title":"As Of Date Price Usd","description":"Token price in USD at as_of_date"},"as_of_date_value_usd":{"anyOf":[{"type":"number"}],"title":"As Of Date Value Usd","description":"USD value of the transfer at as_of_date"},"transfer_id":{"type":"string","title":"Transfer Id","description":"Transfer ID (token-transfer-* or trace-*)"}},"type":"object","required":["from_address","from_address_label","to_address","to_address_label","token_address","token_symbol","token_amount","dated_price_usd","dated_value_usd","as_of_date_price_usd","as_of_date_value_usd","transfer_id"],"title":"HistoricalTokenTransfer","description":"Single token transfer with temporally-correct labels and dual pricing."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1beta1/profiler/historical-transaction-lookup":{"post":{"tags":["Profiler"],"summary":"Get Historical (Time-Travel) Transaction Lookup Data (Beta)","description":"**Beta — subject to breaking changes.**\n\nTime-travel-aware variant of `/transaction-with-token-transfer-lookup`.\n\nReturns transaction details (sender/receiver, native value, token transfers)\nwith **temporally-correct labels** and **dual pricing** (dated price at the\ntransaction's block_timestamp + as-of-date price). Labels are resolved at\n`as_of_date` to avoid forward-looking bias; entity labels are available from\n2025-03-11 onward.\n\n**Performance**\n\nThis endpoint executes two queries sequentially:\n\n1. **Hash -> timestamp resolution** — can take **60-170 seconds** for unknown\n hashes. Pass `block_timestamp` in the request to skip this step entirely.\n2. **Data lookup** — <1 second once the timestamp is known.","operationId":"get_profiler_historical_transaction_lookup_beta_api_v1beta1_profiler_historical_transaction_lookup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerHistoricalTransactionLookupRequest"}}},"required":true},"responses":{"200":{"description":"Historical transaction lookup data with temporally-correct labels and dual pricing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerHistoricalTransactionLookupListResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Historical Token Who Bought/Sold {% hint style="info" %} **Note:** This is a beta endpoint (`/api/v1beta1/`). Request shapes, response fields, and pricing may change as we iterate. {% endhint %} ## Get historical "Token God Mode" (TGM) who bought/sold (Beta) > \*\*Beta — subject to breaking changes.\*\*\ > \ > Aggregated buy/sell volumes per trader for a specific token over a historical date range.\ > Labels are resolved at the query end date using temporal label history tables to avoid\ > forward-looking bias.\ > \ > \*\*Key differences from \`/tgm/who-bought-sold\`:\*\*\ > \- Accepts an explicit \`date\_range\` (no rolling default)\ > \- Labels resolved at \`date\_to\`, not the current state\ > \- Response uses \`gross\_token\_volume\` / \`gross\_volume\_usd\` (bought + sold totals) and adds \`is\_smart\_money\`\ > \- \`min\_trade\_volume\_usd\` filter is applied server-side (default 10 USD) ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"TGMHistoricalWhoBoughtSoldRequest":{"properties":{"chain":{"$ref":"#/components/schemas/TGMHistoricalChain","description":"Blockchain chain. Currently base, bnb, ethereum, solana."},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"date_range":{"$ref":"#/components/schemas/DateRange","description":"Historical date range with explicit from and to dates"},"buy_or_sell":{"$ref":"#/components/schemas/TGMWhoBoughtSoldType","description":"Whether to return net buyers or net sellers","default":"BUY"},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"filters":{"anyOf":[{"$ref":"#/components/schemas/TGMHistoricalWhoBoughtSoldFilters"}],"description":"Optional filters applied server-side"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/TGMHistoricalWhoBoughtSoldSortOrder"},"type":"array"}],"title":"Order By","description":"Sort order. Defaults to bought_volume_usd DESC. Only the first element is used."}},"additionalProperties":false,"type":"object","required":["chain","token_address","date_range"],"title":"TGMHistoricalWhoBoughtSoldRequest","description":"Request model for the historical who-bought-sold endpoint.\n\nReturns aggregated buy/sell volumes per trader for a token with temporally-correct\nlabels resolved at date_to. Uses label history tables to avoid forward-looking bias."},"TGMHistoricalChain":{"type":"string","enum":["base","bnb","ethereum","solana"],"title":"TGMHistoricalChain","description":"Chains supported for the TGM historical endpoints (pnl-leaderboard, who-bought-sold, top-holders, token-flow-summary)."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"TGMWhoBoughtSoldType":{"type":"string","enum":["BUY","SELL"],"title":"TGMWhoBoughtSoldType","description":"TGM who bought/sold type."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"TGMHistoricalWhoBoughtSoldFilters":{"properties":{"include_labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/HistoricalLabelType"},"type":"array"}],"title":"Include Labels","description":"Include only traders with these temporal smart money labels"},"trade_volume_usd":{"anyOf":[{"$ref":"#/components/schemas/NumericRangeFilter"}],"description":"Net directional trade volume range filter in USD (default min: 10)"}},"additionalProperties":false,"type":"object","title":"TGMHistoricalWhoBoughtSoldFilters","description":"Filters for the historical who-bought-sold endpoint."},"HistoricalLabelType":{"type":"string","enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Smart Dex Trader","30D Smart Dex Trader","90D Smart Dex Trader","180D Smart Dex Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"title":"HistoricalLabelType","description":"Filter by entity label type. Includes legacy label classes (e.g. Smart Dex Trader) that appear in historical data."},"NumericRangeFilter":{"properties":{"min":{"anyOf":[{"type":"number"}],"title":"Min","description":"Minimum value (inclusive)"},"max":{"anyOf":[{"type":"number"}],"title":"Max","description":"Maximum value (inclusive)"}},"type":"object","title":"NumericRangeFilter","description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"},"TGMHistoricalWhoBoughtSoldSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/TGMHistoricalWhoBoughtSoldSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"TGMHistoricalWhoBoughtSoldSortOrder"},"TGMHistoricalWhoBoughtSoldSortField":{"type":"string","enum":["bought_volume_usd","sold_volume_usd","gross_volume_usd"],"title":"TGMHistoricalWhoBoughtSoldSortField","description":"Sortable fields for the historical who-bought-sold endpoint."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"TGMHistoricalWhoBoughtSoldResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TGMHistoricalWhoBoughtSold"},"type":"array","title":"Data","description":"List of historical who-bought-sold records"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"TGMHistoricalWhoBoughtSoldResponse","description":"Response model for the historical who-bought-sold endpoint."},"TGMHistoricalWhoBoughtSold":{"properties":{"address":{"type":"string","title":"Address","description":"Trader address"},"address_label":{"anyOf":[{"type":"string"}],"title":"Address Label","description":"Temporally-correct label resolved at date_to"},"is_smart_money":{"type":"boolean","title":"Is Smart Money","description":"Whether the address had a smart money label at date_to"},"bought_token_volume":{"anyOf":[{"type":"number"}],"title":"Bought Token Volume","description":"Aggregate bought token volume"},"sold_token_volume":{"anyOf":[{"type":"number"}],"title":"Sold Token Volume","description":"Aggregate sold token volume"},"gross_token_volume":{"anyOf":[{"type":"number"}],"title":"Gross Token Volume","description":"Gross token trade volume (bought + sold)"},"bought_volume_usd":{"anyOf":[{"type":"number"}],"title":"Bought Volume Usd","description":"Aggregate bought volume in USD"},"sold_volume_usd":{"anyOf":[{"type":"number"}],"title":"Sold Volume Usd","description":"Aggregate sold volume in USD"},"gross_volume_usd":{"anyOf":[{"type":"number"}],"title":"Gross Volume Usd","description":"Gross trade volume in USD (bought + sold)"}},"type":"object","required":["address","is_smart_money"],"title":"TGMHistoricalWhoBoughtSold","description":"Single historical who-bought-sold record.\n\nAggregated buy/sell volumes per trader address with temporally-correct labels\nresolved at the query end date. Differs from TGMWhoBoughtSold: uses\ngross_token_volume / gross_volume_usd instead of token_trade_volume / trade_volume_usd,\nand adds is_smart_money."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1beta1/tgm/historical-who-bought-sold":{"post":{"tags":["Token God Mode"],"summary":"Get historical \"Token God Mode\" (TGM) who bought/sold (Beta)","description":"**Beta — subject to breaking changes.**\n\nAggregated buy/sell volumes per trader for a specific token over a historical date range.\nLabels are resolved at the query end date using temporal label history tables to avoid\nforward-looking bias.\n\n**Key differences from `/tgm/who-bought-sold`:**\n- Accepts an explicit `date_range` (no rolling default)\n- Labels resolved at `date_to`, not the current state\n- Response uses `gross_token_volume` / `gross_volume_usd` (bought + sold totals) and adds `is_smart_money`\n- `min_trade_volume_usd` filter is applied server-side (default 10 USD)","operationId":"get_tgm_historical_who_bought_sold_beta_api_v1beta1_tgm_historical_who_bought_sold_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMHistoricalWhoBoughtSoldRequest"}}},"required":true},"responses":{"200":{"description":"Historical TGM who-bought-sold data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TGMHistoricalWhoBoughtSoldResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Prediction Market Nansen's Prediction Market API endpoints provide comprehensive access to onchain prediction market data. Track positions, analyze market activity, find top traders, and discover trending events on Polymarket ### What can you do? With Prediction Market endpoints, you can: * **Discover trending markets and events:** Screen markets by volume, liquidity, and activity to find what's moving * **Analyze wallet performance:** Track any address's prediction market trades, positions, and PnL * **Find top traders:** Identify the most profitable participants on specific markets * **Monitor market dynamics:** Access orderbooks, price history (OHLCV), and trade flows for any market * **Browse by category:** Filter markets by topic: politics, crypto, sports, and more ### Which endpoints can I use? | I want to... | Use this endpoint | Best for | | --------------------------------------------------------- | ----------------- | ---------------------------------------- | | Find high-volume or trending prediction markets | Market Screener | Market discovery and trends | | Browse and filter events by category, status, or volume | Event Screener | Event discovery | | View price history for a specific market | OHLCV | Charting and trend analysis | | See the current orderbook depth for a market | Orderbook | Liquidity analysis and entry/exit sizing | | Find the largest position holders in a market | Top Holders | Identifying conviction holders | | See all trades made by a wallet across prediction markets | Trades by Address | Wallet activity breakdown | | View all trades on a specific market | Trades by Market | Market-level trade flow | | See a wallet's PnL and win rate across all markets | PnL by Address | Trader performance analysis | | See profitability rankings for a specific market | PnL by Market | Find top performers per market | | Get full details on a wallet's open position in a market | Position Detail | Position monitoring | | Browse available market categories | Categories | Navigation and filtering | | PnL, Win rate and age of a wallet | Address Summary | Screening wallets | ### Key Concepts **Market vs Event** Prediction markets are organised into two levels: | Concept | Description | Example | | ---------- | -------------------------------------------------------------- | ------------------------------------------------------- | | **Market** | The fundamental tradable unit: a single binary Yes/No question | "Will ETH reach $5k in 2025?" | | **Event** | A container that groups one or more related markets | "2025 Crypto Predictions" (containing multiple markets) | **Positions and Shares** Unlike perp trading, prediction market positions are expressed as **shares** in a YES/NO outcome: * A positive position = holding YES shares (bullish on the event) * A negative position = holding NO shares (bearish on the event) * Price ranges from $0 to $1, representing the implied probability **Platforms Covered** Nansen currently only supports data across Polymarket. We will be adding more platforms in the future. # Market Categories ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Returns a **current, point-in-time snapshot** of category statistics — there is no date-range parameter or historical look-back, and values reflect within the standard live latency. ## Get Prediction Market Categories > Get aggregated statistics for all prediction market categories. Shows volume,\ > open interest, and top markets per category.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*Which prediction market categories have the most activity?\*\*\ > 2\. \*\*What is the volume breakdown by category?\*\*\ > 3\. \*\*What are the top markets in each category?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"CategoriesRequest":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationRequest"}},"additionalProperties":false,"type":"object","title":"CategoriesRequest","description":"Request for categories endpoint (pagination only)."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"CategoriesResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo"},"data":{"items":{"$ref":"#/components/schemas/CategoryItem"},"type":"array","title":"Data","description":"List of category records"}},"type":"object","required":["data"],"title":"CategoriesResponse","description":"Response for categories endpoint."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"CategoryItem":{"properties":{"category":{"type":"string","title":"Category","description":"Category name"},"active_markets":{"anyOf":[{"type":"integer"}],"title":"Active Markets","description":"Number of active markets"},"total_open_interest":{"anyOf":[{"type":"number"}],"title":"Total Open Interest","description":"Total open interest (USD)"},"total_volume":{"anyOf":[{"type":"number"}],"title":"Total Volume","description":"Total volume (USD)"},"total_volume_24hr":{"anyOf":[{"type":"number"}],"title":"Total Volume 24Hr","description":"Total 24h volume (USD)"},"total_volume_1wk":{"anyOf":[{"type":"number"}],"title":"Total Volume 1Wk","description":"Total 1 week volume (USD)"},"total_traders_24h":{"anyOf":[{"type":"integer"}],"title":"Total Traders 24H","description":"Total unique traders in 24h"},"top_market_id":{"anyOf":[{"type":"string"}],"title":"Top Market Id","description":"Top market by 24h volume"},"top_market_question":{"anyOf":[{"type":"string"}],"title":"Top Market Question","description":"Top market question"},"top_market_volume_24hr":{"anyOf":[{"type":"number"}],"title":"Top Market Volume 24Hr","description":"Top market 24h volume"}},"type":"object","required":["category"],"title":"CategoryItem","description":"Category data from ch_api_pm_categories."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/prediction-market/categories":{"post":{"tags":["Prediction Markets"],"summary":"Get Prediction Market Categories","description":"Get aggregated statistics for all prediction market categories. Shows volume,\nopen interest, and top markets per category.\n\n**What it helps to answer:**\n\n1. **Which prediction market categories have the most activity?**\n2. **What is the volume breakdown by category?**\n3. **What are the top markets in each category?**","operationId":"get_prediction_market_categories_api_v1_prediction_market_categories_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoriesRequest"}}},"required":true},"responses":{"200":{"description":"Category data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoriesResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Market Screener ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Returns a **current, point-in-time snapshot** of prediction markets and their latest metrics — there is no date-range parameter or historical look-back, and values reflect within the standard live latency. ## Get Prediction Market Screener > Browse and filter all Polymarket prediction markets. Supports sorting by volume,\ > liquidity, price change, and more. Filter by search query and active/closed status.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*What are the most active prediction markets right now?\*\*\ > 2\. \*\*Which markets have the highest volume or liquidity?\*\*\ > 3\. \*\*What new markets have been created recently?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"MarketScreenerRequest":{"properties":{"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/ScreenerSortOrder"},"type":"array"}],"title":"Order By","description":"Sort order"},"sort_by":{"$ref":"#/components/schemas/ScreenerSortField","description":"Deprecated: use 'order_by' instead.","default":"volume_24hr","deprecated":true},"query":{"type":"string","maxLength":200,"title":"Query","description":"Search query to filter results","default":""},"status":{"$ref":"#/components/schemas/MarketStatus","description":"Filter by status (active, closed, or empty for all)","default":""},"tags":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Tags","description":"Filter by tags"},"min_liquidity":{"type":"number","minimum":-1,"title":"Min Liquidity","description":"Minimum liquidity filter (-1 = no filter)","default":-1},"max_liquidity":{"type":"number","minimum":-1,"title":"Max Liquidity","description":"Maximum liquidity filter (-1 = no limit)","default":-1},"max_unique_traders_24h":{"type":"integer","minimum":-1,"title":"Max Unique Traders 24H","description":"Maximum unique traders in 24h (-1 = no limit)","default":-1},"min_volume_24hr":{"type":"number","minimum":-1,"title":"Min Volume 24Hr","description":"Minimum 24h volume filter (-1 = no filter)","default":-1},"neg_risk":{"anyOf":[{"type":"boolean"}],"title":"Neg Risk","description":"Filter by neg-risk framework (null = no filter)"},"min_open_interest":{"type":"number","minimum":-1,"title":"Min Open Interest","description":"Minimum open interest filter (-1 = no filter)","default":-1},"max_open_interest":{"type":"number","minimum":-1,"title":"Max Open Interest","description":"Maximum open interest filter (-1 = no limit)","default":-1},"end_date_before":{"type":"string","maxLength":100,"title":"End Date Before","description":"Filter markets ending before this datetime (ISO 8601)","default":""},"end_date_after":{"type":"string","maxLength":100,"title":"End Date After","description":"Filter markets ending after this datetime (ISO 8601)","default":""},"pagination":{"$ref":"#/components/schemas/PaginationRequest"},"min_price":{"type":"number","minimum":-1,"title":"Min Price","description":"Minimum price filter (-1 = no filter)","default":-1},"max_price":{"type":"number","minimum":-1,"title":"Max Price","description":"Maximum price filter (-1 = no limit)","default":-1}},"additionalProperties":false,"type":"object","title":"MarketScreenerRequest","description":"Request for market screener endpoint."},"ScreenerSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/ScreenerSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"ScreenerSortOrder"},"ScreenerSortField":{"type":"string","enum":["volume_24hr","volume","volume_1wk","volume_1mo","liquidity","open_interest","unique_traders_24h","age_hours"],"title":"ScreenerSortField","description":"Valid sort fields for screener endpoints."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"MarketStatus":{"type":"string","enum":["active","closed",""],"title":"MarketStatus","description":"Valid status filters for screener endpoints."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"MarketScreenerResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo"},"data":{"items":{"$ref":"#/components/schemas/MarketScreenerItem"},"type":"array","title":"Data","description":"List of market screener records"}},"type":"object","required":["data"],"title":"MarketScreenerResponse","description":"Response for market screener endpoint."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"MarketScreenerItem":{"properties":{"market_id":{"type":"string","title":"Market Id","description":"Market ID"},"question":{"anyOf":[{"type":"string"}],"title":"Question","description":"Market question"},"slug":{"anyOf":[{"type":"string"}],"title":"Slug","description":"URL slug"},"event_id":{"anyOf":[{"type":"string"}],"title":"Event Id","description":"Parent event ID"},"event_title":{"anyOf":[{"type":"string"}],"title":"Event Title","description":"Parent event title"},"active":{"anyOf":[{"type":"boolean"}],"title":"Active","description":"Whether market is active"},"closed":{"anyOf":[{"type":"boolean"}],"title":"Closed","description":"Whether market is closed"},"end_date":{"anyOf":[{"type":"string","format":"date-time"}],"title":"End Date","description":"Market end date"},"neg_risk":{"anyOf":[{"type":"boolean"}],"title":"Neg Risk","description":"Uses neg-risk framework"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Tags","description":"Market tags"},"volume":{"anyOf":[{"type":"number"}],"title":"Volume","description":"Total volume (USD)"},"volume_24hr":{"anyOf":[{"type":"number"}],"title":"Volume 24Hr","description":"24h volume (USD)"},"volume_1wk":{"anyOf":[{"type":"number"}],"title":"Volume 1Wk","description":"1 week volume (USD)"},"volume_1mo":{"anyOf":[{"type":"number"}],"title":"Volume 1Mo","description":"1 month volume (USD)"},"liquidity":{"anyOf":[{"type":"number"}],"title":"Liquidity","description":"Current liquidity (USD)"},"volume_change_pct":{"anyOf":[{"type":"number"}],"title":"Volume Change Pct","description":"Volume change percentage"},"open_interest":{"anyOf":[{"type":"number"}],"title":"Open Interest","description":"Open interest (USD)"},"best_bid":{"anyOf":[{"type":"number"}],"title":"Best Bid","description":"Best bid price"},"best_ask":{"anyOf":[{"type":"number"}],"title":"Best Ask","description":"Best ask price"},"last_trade_price":{"anyOf":[{"type":"number"}],"title":"Last Trade Price","description":"Last trade price"},"one_day_price_change":{"anyOf":[{"type":"number"}],"title":"One Day Price Change","description":"24h price change"},"unique_traders_24h":{"anyOf":[{"type":"integer"}],"title":"Unique Traders 24H","description":"Unique traders in 24h"},"created_at":{"anyOf":[{"type":"string","format":"date-time"}],"title":"Created At","description":"Market creation time"},"age_hours":{"anyOf":[{"type":"number"}],"title":"Age Hours","description":"Market age in hours"}},"type":"object","required":["market_id"],"title":"MarketScreenerItem","description":"Market screener data from ch_api_pm_market_screener."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/prediction-market/market-screener":{"post":{"tags":["Prediction Markets"],"summary":"Get Prediction Market Screener","description":"Browse and filter all Polymarket prediction markets. Supports sorting by volume,\nliquidity, price change, and more. Filter by search query and active/closed status.\n\n**What it helps to answer:**\n\n1. **What are the most active prediction markets right now?**\n2. **Which markets have the highest volume or liquidity?**\n3. **What new markets have been created recently?**","operationId":"get_prediction_market_screener_api_v1_prediction_market_market_screener_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketScreenerRequest"}}},"required":true},"responses":{"200":{"description":"Market screener data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketScreenerResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Market Event Screener ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Returns a **current, point-in-time snapshot** of market activity metrics (volume, liquidity, and trader counts) — these reflect the latest state within the standard live latency rather than a historical look-back. ## Get Prediction Market Event Screener > Browse and filter Polymarket events (groups of related markets). Includes aggregated\ > volume, liquidity, and trader counts across all markets in each event.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*What are the most popular prediction market events?\*\*\ > 2\. \*\*How much total volume does an event have across all its markets?\*\*\ > 3\. \*\*Which events have the most active trading?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"EventScreenerRequest":{"properties":{"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/ScreenerSortOrder"},"type":"array"}],"title":"Order By","description":"Sort order"},"sort_by":{"$ref":"#/components/schemas/ScreenerSortField","description":"Deprecated: use 'order_by' instead.","default":"volume_24hr","deprecated":true},"query":{"type":"string","maxLength":200,"title":"Query","description":"Search query to filter results","default":""},"status":{"$ref":"#/components/schemas/MarketStatus","description":"Filter by status (active, closed, or empty for all)","default":""},"tags":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Tags","description":"Filter by tags"},"min_liquidity":{"type":"number","minimum":-1,"title":"Min Liquidity","description":"Minimum liquidity filter (-1 = no filter)","default":-1},"max_liquidity":{"type":"number","minimum":-1,"title":"Max Liquidity","description":"Maximum liquidity filter (-1 = no limit)","default":-1},"max_unique_traders_24h":{"type":"integer","minimum":-1,"title":"Max Unique Traders 24H","description":"Maximum unique traders in 24h (-1 = no limit)","default":-1},"min_volume_24hr":{"type":"number","minimum":-1,"title":"Min Volume 24Hr","description":"Minimum 24h volume filter (-1 = no filter)","default":-1},"neg_risk":{"anyOf":[{"type":"boolean"}],"title":"Neg Risk","description":"Filter by neg-risk framework (null = no filter)"},"min_open_interest":{"type":"number","minimum":-1,"title":"Min Open Interest","description":"Minimum open interest filter (-1 = no filter)","default":-1},"max_open_interest":{"type":"number","minimum":-1,"title":"Max Open Interest","description":"Maximum open interest filter (-1 = no limit)","default":-1},"end_date_before":{"type":"string","maxLength":100,"title":"End Date Before","description":"Filter markets ending before this datetime (ISO 8601)","default":""},"end_date_after":{"type":"string","maxLength":100,"title":"End Date After","description":"Filter markets ending after this datetime (ISO 8601)","default":""},"pagination":{"$ref":"#/components/schemas/PaginationRequest"}},"additionalProperties":false,"type":"object","title":"EventScreenerRequest","description":"Request for event screener endpoint."},"ScreenerSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/ScreenerSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"ScreenerSortOrder"},"ScreenerSortField":{"type":"string","enum":["volume_24hr","volume","volume_1wk","volume_1mo","liquidity","open_interest","unique_traders_24h","age_hours"],"title":"ScreenerSortField","description":"Valid sort fields for screener endpoints."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"MarketStatus":{"type":"string","enum":["active","closed",""],"title":"MarketStatus","description":"Valid status filters for screener endpoints."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"EventScreenerResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo"},"data":{"items":{"$ref":"#/components/schemas/EventScreenerItem"},"type":"array","title":"Data","description":"List of event screener records"}},"type":"object","required":["data"],"title":"EventScreenerResponse","description":"Response for event screener endpoint."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"EventScreenerItem":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Event ID"},"event_title":{"anyOf":[{"type":"string"}],"title":"Event Title","description":"Event title"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Tags","description":"Event tags"},"neg_risk":{"anyOf":[{"type":"boolean"}],"title":"Neg Risk","description":"Uses neg-risk framework"},"market_count":{"anyOf":[{"type":"integer"}],"title":"Market Count","description":"Number of markets"},"total_volume":{"anyOf":[{"type":"number"}],"title":"Total Volume","description":"Total volume (USD)"},"total_volume_24hr":{"anyOf":[{"type":"number"}],"title":"Total Volume 24Hr","description":"Total 24h volume (USD)"},"total_volume_1wk":{"anyOf":[{"type":"number"}],"title":"Total Volume 1Wk","description":"Total 1 week volume (USD)"},"total_volume_1mo":{"anyOf":[{"type":"number"}],"title":"Total Volume 1Mo","description":"Total 1 month volume (USD)"},"total_liquidity":{"anyOf":[{"type":"number"}],"title":"Total Liquidity","description":"Total liquidity (USD)"},"total_open_interest":{"anyOf":[{"type":"number"}],"title":"Total Open Interest","description":"Total open interest (USD)"},"total_volume_change_pct":{"anyOf":[{"type":"number"}],"title":"Total Volume Change Pct","description":"Total volume change percentage"},"total_traders_24h":{"anyOf":[{"type":"integer"}],"title":"Total Traders 24H","description":"Total unique traders in 24h"},"max_age_hours":{"anyOf":[{"type":"number"}],"title":"Max Age Hours","description":"Max market age in hours"},"top_market_id":{"anyOf":[{"type":"string"}],"title":"Top Market Id","description":"Top market by 24h volume"},"top_market_question":{"anyOf":[{"type":"string"}],"title":"Top Market Question","description":"Top market question"},"top_market_volume_24hr":{"anyOf":[{"type":"number"}],"title":"Top Market Volume 24Hr","description":"Top market 24h volume"},"markets":{"anyOf":[{"items":{"$ref":"#/components/schemas/EventScreenerMarket"},"type":"array"}],"title":"Markets","description":"Nested market data"}},"type":"object","required":["event_id"],"title":"EventScreenerItem","description":"Event screener data from ch_api_pm_event_screener."},"EventScreenerMarket":{"properties":{"market_id":{"type":"string","title":"Market Id"},"question":{"type":"string","title":"Question"},"volume_24hr":{"anyOf":[{"type":"number"}],"title":"Volume 24Hr"},"open_interest":{"anyOf":[{"type":"number"}],"title":"Open Interest"},"best_bid":{"anyOf":[{"type":"number"}],"title":"Best Bid"},"best_ask":{"anyOf":[{"type":"number"}],"title":"Best Ask"},"last_trade_price":{"anyOf":[{"type":"number"}],"title":"Last Trade Price"},"one_day_price_change":{"anyOf":[{"type":"number"}],"title":"One Day Price Change"},"volume_change_pct":{"anyOf":[{"type":"number"}],"title":"Volume Change Pct"},"unique_traders_24h":{"anyOf":[{"type":"integer"}],"title":"Unique Traders 24H"},"end_date":{"anyOf":[{"type":"string","format":"date-time"}],"title":"End Date"}},"type":"object","required":["market_id","question"],"title":"EventScreenerMarket","description":"Single market within an event screener row."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/prediction-market/event-screener":{"post":{"tags":["Prediction Markets"],"summary":"Get Prediction Market Event Screener","description":"Browse and filter Polymarket events (groups of related markets). Includes aggregated\nvolume, liquidity, and trader counts across all markets in each event.\n\n**What it helps to answer:**\n\n1. **What are the most popular prediction market events?**\n2. **How much total volume does an event have across all its markets?**\n3. **Which events have the most active trading?**","operationId":"get_prediction_market_event_screener_api_v1_prediction_market_event_screener_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventScreenerRequest"}}},"required":true},"responses":{"200":{"description":"Event screener data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventScreenerResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Market Orderbook ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Returns a **current, point-in-time snapshot** of the full bid/ask order book — there is no date-range parameter or historical look-back, and it reflects the latest available state within the standard live latency. ## Get Prediction Market Orderbook > Get the full bid/ask orderbook for a Polymarket prediction market. Data is\ > polled from the Polymarket CLOB API every \~60 seconds with MD5 change detection.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*What is the current bid/ask depth for a prediction market?\*\*\ > 2\. \*\*How much liquidity is available at each price level?\*\*\ > 3\. \*\*What is the current spread?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"OrderbookRequest":{"properties":{"market_id":{"type":"string","maxLength":100,"minLength":1,"title":"Market Id","description":"Polymarket market ID"},"pagination":{"$ref":"#/components/schemas/PaginationRequest"}},"additionalProperties":false,"type":"object","required":["market_id"],"title":"OrderbookRequest","description":"Request for orderbook endpoint."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"OrderbookResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo"},"data":{"items":{"$ref":"#/components/schemas/OrderbookLevel"},"type":"array","title":"Data","description":"List of orderbook level records"}},"type":"object","required":["data"],"title":"OrderbookResponse","description":"Response for orderbook endpoint."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"OrderbookLevel":{"properties":{"market_id":{"type":"string","title":"Market Id","description":"Market ID"},"event_id":{"anyOf":[{"type":"string"}],"title":"Event Id","description":"Event ID"},"outcome":{"anyOf":[{"type":"string"}],"title":"Outcome","description":"Outcome label"},"outcome_index":{"anyOf":[{"type":"integer"}],"title":"Outcome Index","description":"Outcome index"},"asset_id":{"anyOf":[{"type":"string"}],"title":"Asset Id","description":"CLOB token ID"},"side":{"anyOf":[{"type":"string"}],"title":"Side","description":"buy or sell"},"price":{"anyOf":[{"type":"number"}],"title":"Price","description":"Price level"},"size":{"anyOf":[{"type":"number"}],"title":"Size","description":"Size at level"},"cumulative_size":{"anyOf":[{"type":"number"}],"title":"Cumulative Size","description":"Cumulative size"},"snapshot_timestamp":{"anyOf":[{"type":"string","format":"date-time"}],"title":"Snapshot Timestamp","description":"Snapshot timestamp"}},"type":"object","required":["market_id"],"title":"OrderbookLevel","description":"Orderbook level from ch_api_pm_orderbook."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/prediction-market/orderbook":{"post":{"tags":["Prediction Markets"],"summary":"Get Prediction Market Orderbook","description":"Get the full bid/ask orderbook for a Polymarket prediction market. Data is\npolled from the Polymarket CLOB API every ~60 seconds with MD5 change detection.\n\n**What it helps to answer:**\n\n1. **What is the current bid/ask depth for a prediction market?**\n2. **How much liquidity is available at each price level?**\n3. **What is the current spread?**","operationId":"get_prediction_market_orderbook_api_v1_prediction_market_orderbook_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderbookRequest"}}},"required":true},"responses":{"200":{"description":"Orderbook data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderbookResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` # Market OHLCV ### Data Freshness & Historical Coverage For data freshness and historical coverage, see [Data Coverage by Chain](/api/data-coverage); this endpoint follows it except where noted below. * Covers the Polymarket prediction-markets dataset (trade and price history from **November 2022**), not per-chain history — see the Prediction Markets note on the coverage page. * Serves a **price feed in fixed one-hour intervals**, where the most recent candle is the current, still-forming interval that keeps updating until the hour closes. ## Get Prediction Market OHLCV Candles > Get 1-hour OHLCV (Open, High, Low, Close, Volume) candles for a Polymarket\ > prediction market. Candles are computed from on-chain OrderFilled events on Polygon.\ > \ > \*\*What it helps to answer:\*\*\ > \ > 1\. \*\*What is the price history of a prediction market outcome?\*\*\ > 2\. \*\*How has trading volume changed over time?\*\*\ > 3\. \*\*What were the high and low prices in each time period?\*\* ```json {"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]},{"MppPayment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication"},"X402Payment":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 pay-per-request; no API key needed. Send the request without credentials to receive a `402 Payment Required` response whose `Payment-Required` header advertises the accepted payment options, then retry with the signed x402 V2 payment payload in the `Payment-Signature` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"},"MppPayment":{"type":"apiKey","in":"header","name":"Authorization","description":"Machine Payments Protocol (MPP) pay-per-request on Tempo; no API key needed. Send `Authorization: Payment` to receive a `402 Payment Required` response whose `WWW-Authenticate: Payment ...` header carries a fresh challenge, then retry with the signed credential as `Authorization: Payment `. Successful responses include a `Payment-Receipt` header. Only operations that list this scheme accept it. See https://docs.nansen.ai/getting-started/agentic-payments"}},"schemas":{"OhlcvRequest":{"properties":{"market_id":{"type":"string","maxLength":100,"minLength":1,"title":"Market Id","description":"Polymarket market ID"},"pagination":{"$ref":"#/components/schemas/PaginationRequest"},"date":{"anyOf":[{"$ref":"#/components/schemas/DateRange"}],"description":"Date range filter (ISO 8601 date-time)"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/OhlcvSortOrder"},"type":"array"}],"title":"Order By","description":"Sort order"},"sort":{"anyOf":[{"items":{"$ref":"#/components/schemas/OhlcvSortOrder"},"type":"array"}],"title":"Sort","description":"Deprecated: use 'order_by' instead.","deprecated":true}},"additionalProperties":false,"type":"object","required":["market_id"],"title":"OhlcvRequest","description":"Request for OHLCV endpoint."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"OhlcvSortOrder":{"properties":{"field":{"$ref":"#/components/schemas/OhlcvSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"OhlcvSortOrder"},"OhlcvSortField":{"type":"string","enum":["period_start","volume_usd","trade_count"],"title":"OhlcvSortField","description":"Sortable fields for OHLCV endpoint."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"OhlcvResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo"},"data":{"items":{"$ref":"#/components/schemas/OhlcvCandle"},"type":"array","title":"Data","description":"List of OHLCV candle records"}},"type":"object","required":["data"],"title":"OhlcvResponse","description":"Response for OHLCV endpoint."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"OhlcvCandle":{"properties":{"market_id":{"type":"string","title":"Market Id","description":"Market ID"},"token_id":{"anyOf":[{"type":"string"}],"title":"Token Id","description":"CLOB token ID"},"side":{"anyOf":[{"type":"string"}],"title":"Side","description":"Side label (Yes/No)"},"outcome_index":{"anyOf":[{"type":"integer"}],"title":"Outcome Index","description":"Outcome index (1/2)"},"period_start":{"anyOf":[{"type":"string","format":"date-time"}],"title":"Period Start","description":"Candle period start (ISO format)"},"open":{"anyOf":[{"type":"number"}],"title":"Open","description":"Open price"},"high":{"anyOf":[{"type":"number"}],"title":"High","description":"High price"},"low":{"anyOf":[{"type":"number"}],"title":"Low","description":"Low price"},"close":{"anyOf":[{"type":"number"}],"title":"Close","description":"Close price"},"volume_usd":{"anyOf":[{"type":"number"}],"title":"Volume Usd","description":"Volume in USD"},"trade_count":{"anyOf":[{"type":"integer"}],"title":"Trade Count","description":"Number of trades"},"unique_traders":{"anyOf":[{"type":"integer"}],"title":"Unique Traders","description":"Unique traders in period"}},"type":"object","required":["market_id"],"title":"OhlcvCandle","description":"OHLCV candle data from ch_api_pm_ohlcv."},"ErrorEnvelope":{"type":"object","required":["error","message","code","status","request_id","doc_url"],"properties":{"error":{"type":"string","description":"Human-readable error category."},"message":{"type":"string","description":"Human-readable explanation of the error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items","unauthenticated","forbidden","geo_blocked","plan_upgrade_required","insufficient_credits","rate_limit_exceeded","not_found","method_not_allowed","conflict","payload_too_large","query_timeout","query_too_large","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"status":{"type":"integer","description":"HTTP status code returned for the request."},"request_id":{"type":["string","null"],"description":"Identifier for the request, when available."},"doc_url":{"type":"string","format":"uri","description":"Link to the error-code reference documentation, anchored to this error's code."},"param":{"type":"string","description":"Request parameter associated with the error."},"retry_after":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying the request."}}}},"headers":{"XNansenCreditsCost":{"description":"Quoted credit cost of this request. It is present on successful responses and errors reached after pricing, but absent when a request is rejected before pricing. A value of 0 means plan credits do not apply.","schema":{"type":"string"}},"XRequestId":{"description":"Unique identifier for this request, returned on every response. Uses the upstream-assigned request id when available; otherwise echoes a caller-supplied X-Request-Id or generates an id. Include this value in support requests.","schema":{"type":"string"}},"XNansenCreditsUsed":{"description":"Credits actually deducted for this request. Can differ from the quoted cost, for example 0 when the request was rejected.","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Seconds until the rate limit window resets. A delta in seconds, not a Unix timestamp.","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Request limit for the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitRemaining":{"description":"Requests remaining in the most constrained app-enforced window","schema":{"type":"string"}},"XRateLimitReset":{"description":"Seconds until the most constrained app-enforced window resets. A delta in seconds, not a Unix timestamp: it is at least 1 and never exceeds the window span.","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"PaymentRequired":{"description":"Base64-encoded x402 payment options returned on 402 responses for x402 clients","schema":{"type":"string"}},"WWWAuthenticatePayment":{"description":"MPP payment challenge returned on 402 responses, for example `Payment id=\"...\", realm=\"api.nansen.ai\", method=\"tempo\", intent=\"charge\", request=\"...\"`","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}},"XNansenRateLimitScope":{"description":"Window that caused an enforced rate-limit rejection: `second` or `minute` for global plan windows, or `endpoint` for an endpoint-specific window. This is an open set; clients should handle unknown future values with generic rate-limit behavior.","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.","headers":{"Payment-Required":{"$ref":"#/components/headers/PaymentRequired"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticatePayment"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"Problem-details body for x402 or MPP payment challenges."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"}}}]}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"errors":{"type":"array","description":"Per-field request-validation errors, in the order they were detected. This field is absent from other 422 responses. The top-level error, message, and code reflect the primary error, which is not always the first entry. When a request produces an unusually large number of errors the list is truncated and a final entry reports how many were omitted.","items":{"type":"object","required":["field","message","code"],"properties":{"field":{"type":"string","description":"Path of the request field that failed validation, prefixed with its location in the request (body, query, path, header, or cookie) and including array indices. Unlike param, this path keeps the location prefix and array indices."},"message":{"type":"string","description":"Human-readable explanation of the field error."},"code":{"type":"string","enum":["missing_field","unknown_field","invalid_field_value","invalid_address_format","invalid_date_format","invalid_date_range","mutually_exclusive_fields","value_out_of_range","too_many_items"],"description":"Stable machine-readable error code."}}}}}}]}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Nansen-RateLimit-Scope":{"$ref":"#/components/headers/XNansenRateLimitScope"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGatewayError":{"description":"Bad Gateway - Upstream service unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"ServiceUnavailableError":{"description":"Service Unavailable - Service temporarily unavailable","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}},"GatewayTimeoutError":{"description":"Gateway Timeout - Upstream service timed out","headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}]}}}}}},"paths":{"/api/v1/prediction-market/ohlcv":{"post":{"tags":["Prediction Markets"],"summary":"Get Prediction Market OHLCV Candles","description":"Get 1-hour OHLCV (Open, High, Low, Close, Volume) candles for a Polymarket\nprediction market. Candles are computed from on-chain OrderFilled events on Polygon.\n\n**What it helps to answer:**\n\n1. **What is the price history of a prediction market outcome?**\n2. **How has trading volume changed over time?**\n3. **What were the high and low prices in each time period?**","operationId":"get_prediction_market_ohlcv_api_v1_prediction_market_ohlcv_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OhlcvRequest"}}},"required":true},"responses":{"200":{"description":"OHLCV candle data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OhlcvResponse"}}},"headers":{"X-Nansen-Credits-Cost":{"$ref":"#/components/headers/XNansenCreditsCost"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"},"502":{"description":"Bad Gateway","$ref":"#/components/responses/BadGatewayError"},"503":{"description":"Service Unavailable","$ref":"#/components/responses/ServiceUnavailableError"},"504":{"description":"Gateway Timeout","$ref":"#/components/responses/GatewayTimeoutError"}}}}}} ``` --- [Next Page](https://docs.nansen.ai/llms-full.txt/1)