About Nansen API
Review the Service identity, supported languages, protocol versions, and source metadata discovered by the directory.Service details
Service Id
d886e811-83f7-4d15-9c7f-6af359705801
Service origin
https://api.nansen.ai
ListedSeptember 24, 2026, 11:40 PM
Last checkedSeptember 24, 2026, 11:40 PM
Protocol details
SourceOpenAPI
Endpoints
Endpoint details are saved from the OpenAPI document. Authentication requirements and prices are advertised information, not a verified payment or access guarantee. The document may contain additional endpoints.GET/api/v1/account
Retrieve account information
Verify your credential is working and retrieve your account details. Returns your verified account identifier, current subscription plan and total remaining credits. This endpoint does not consume any credits. Use this to: - Confirm your credential is valid and active - Check your remaining credit balance before making calls - Verify your subscription planPrice unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/agent/expert
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", "…Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/agent/fast
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", "err…Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/chains/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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/nansen-score/top-tokens
Get Nansen Score Top Tokens
Get aggregated performance and risk scores for top tokens meeting the scoring thresholds. This endpoint returns the Token Scoring System v1.0 results: - **Performance Score (Alpha)**: Identifies tokens likely to outperform BTC in 7-30 days - Range: -60 to +75 - Buying Threshold: >= 15 - Indicators: price_momentum (+30), chain_fees (+30), trading_range (+15), chain_tvl (-35), protocol_fees (-25) - **Risk Score (Safety)**: Filters "Falling Knives" and dangerous market conditions - Range: -60 to +80 - Safety Threshold: > 0 - Indicators: btc_reflexivity (+40/-20), liquidity_risk (+20/-20), concentration_risk (+10/-10), inflation_risk (+10/-10) Results are pre-filtered to performance_score >= 15 and sorted by: 1. performance_score DESC 2. market_cap_group priority (largecap > midcap > lowcap) 3. risk_score DESC 4. 24h volume DESCPrice unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/perp-leaderboard
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…Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/perp-screener
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?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.GET/api/v1/perp/account
Get perp account state
Fetch a wallet's Hyperliquid perpetuals account state: withdrawable balance, account value, margin usage and open positions, as the exchange reports them. The response also carries `spotUsdc`, the wallet's spot USDC balance. Only the perpetuals balance can be used as margin, so a wallet that looks funded but cannot open a position usually has its USDC sitting in spot — move it with `/api/v1/perp/transfer`. `spotUsdc` is `null` when the spot balance could not be read; the perpetuals figures are unaffected.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/perp/approve-builder-fee
Prepare a builder-fee approval
Build the one-time approval that lets orders be routed with Nansen's builder code. Hyperliquid refuses 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, so this approval is a **prerequisite for `/api/v1/perp/order` and `/api/v1/perp/close`**. It is needed once per wallet — check `/api/v1/perp/builder-fee` instead of prompting for it every session. Same **prepare → sign → execute** flow as the trading endpoints: sign the returned `eip712` payload and submit it to `/api/v1/perp/execute`. Sign it with the wallet's own key — an approval signed by an API (agent) wallet is not accepted. What you sign is a **ceiling, not a price**. The approval is for the untiered maximum builder fee, so the signing prompt shows the highest rate Nansen ever charges (0.08%) rather than the rate you will pay: each order is charged your Nansen Points tier rate, which is the same or lower. Signing the ceiling once is what keeps a tier change from ever needing…Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/perp/bridge/execute
Execute a bridge step
Submit a signed step of a Hyperliquid withdrawal. **Withdrawals only.** A deposit's transactions are signed and broadcast by you on the origin chain and never pass through this endpoint — if a quote's `execution_type` is `evm_transaction`, you do not need this call. `target_url` must be a URL the quote's `steps` gave you. It is checked against a strict host allowlist and only the withdrawal action is accepted, so this cannot be used as a general-purpose proxy. `body` is that step's payload with your signature filled in. **⚠️ This moves funds.** A `2xx` means the withdrawal was accepted; a refusal is returned as a `422` carrying the reason rather than a success envelope, so a `2xx` can be trusted. Poll `/api/v1/perp/bridge/status` with the quote's `request_id` to see it complete on the destination chain.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/perp/bridge/quote
Get a bridge quote
Quote moving USDC into or out of a Hyperliquid account. This is how you fund an account before trading and take funds off it afterwards — the perp endpoints move value only inside Hyperliquid, never across chains. Quoting places no transaction and moves no funds. **Supported routes:** deposits into Hyperliquid from Ethereum, Base, Arbitrum, Polygon and BNB Chain; withdrawals from Hyperliquid to Ethereum, Base and Arbitrum. Any other pair is rejected with a `422`. **Choose the balance.** On the Hyperliquid leg, pass `perps` or `spot` as the token to say which balance the funds land in (deposit) or come from (withdrawal). `perps` is usable as margin immediately; `spot` is not, and needs `/api/v1/perp/transfer` afterwards. Sourcing a withdrawal from the wrong balance is the usual reason one fails as insufficient on a wallet that looks funded. **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 …Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.GET/api/v1/perp/bridge/status
Check bridge status
Follow a Hyperliquid deposit or withdrawal through to the destination chain. Identify the transfer one of two ways: - `request_id` — from the bridge quote. The reliable choice for a **withdrawal**, whose Hyperliquid side produces no origin-chain transaction hash for you to poll. - `tx_hash` — the origin-chain transaction hash you broadcast for a **deposit**. It must be 0x-prefixed; an unprefixed hash is simply never found. `status` is normalized to `pending`, `success`, `failure`, `refund` or `not_found`. A just-broadcast transfer reads `not_found` briefly before it is indexed, so treat `not_found` as retryable for a short bounded window and terminal after that. `refund` means the funds went back to the origin chain instead of completing. `raw_status` carries the unnormalized status if you need finer detail.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.GET/api/v1/perp/builder-fee
Get builder-fee approval status
Report whether a wallet has approved the builder fee that order routing requires. Call this before placing a wallet's first order. `approved: false` means the exchange will reject orders from `/api/v1/perp/order` and `/api/v1/perp/close` until the wallet signs the approval from `/api/v1/perp/approve-builder-fee`. `required_fee` is the fee attached to each of **your** orders and `max_fee_rate` is what the wallet has approved so far — both in tenths of a basis point, so `80` means 8 basis points and `0` means no approval yet. The fee follows your Nansen Points tier, the same rate the Nansen app charges, so it drops as your tier rises. The approval you sign covers the untiered rate, which is the highest one, so a tier change never requires re-approving. `builder_address` is the address attached to orders; the prepare endpoints already include it in the action they build, so you only need it to display or verify what you are signing.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/perp/cancel
Prepare a perp cancel
Build an unsigned cancel for one resting order. Same **prepare → sign → execute** flow as `/api/v1/perp/order`: sign the returned `eip712` payload and submit it to `/api/v1/perp/execute`. This call cancels nothing on its own. `order_id` is the exchange's order id (`oid`) — take it from `/api/v1/perp/orders`, or from the execute response that placed the order. Cancelling an order that has already filled or been cancelled is rejected with a `422`.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/perp/close
Prepare a position close
Build an unsigned reduce-only market order that closes an open position. Same **prepare → sign → execute** flow as `/api/v1/perp/order`: sign the returned `eip712` payload and submit it to `/api/v1/perp/execute`. This call closes nothing on its own. `size` is how much of the position to close — pass the position's full size to close it completely. `is_buy` is the side of the *closing* order, which is the opposite of the position: `true` closes a short, `false` closes a long. `price` is the current mark price and is only used to derive the slippage-adjusted limit, since the order is immediate-or-cancel and reduce-only. Read the position's size and side from `/api/v1/perp/positions` rather than tracking them yourself — fills, funding and partial closes all move them. As with `/api/v1/perp/order`, the response echoes the rounded `size` and effective `price` encoded in the signed action.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/perp/execute
Submit a signed perp action
Submit an action you have signed to the Hyperliquid exchange. This is the only perp endpoint that changes anything: every other one either reads state or prepares an unsigned payload. **⚠️ There is no dry-run mode.** A successful call is a real order, cancel, leverage change or transfer against real funds, and no request field prevents that. Send `action` and `nonce` back exactly as a prepare endpoint returned them, plus the `{r, s, v}` signature you produced over that response's `eip712` payload. Re-serializing, reordering or editing any field breaks signature verification and the action is rejected. **Accepted actions:** `order`, `cancel`, `updateLeverage`, `updateIsolatedMargin`, `usdClassTransfer` and `approveBuilderFee`. Order actions must carry the builder code the prepare endpoint attached to them. **Rejections come back as `422`, not `200`.** The exchange reports a refused action inside an otherwise successful response, so this endpoint inspects the result and surfaces the reason as a `422` — a …Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/perp/leverage
Prepare a leverage update
Build an unsigned leverage and margin-mode change for one asset. Same **prepare → sign → execute** flow as `/api/v1/perp/order`: sign the returned `eip712` payload and submit it to `/api/v1/perp/execute`. This call changes nothing on its own. Leverage is set per asset rather than per account, and applies to positions opened afterwards — it does not re-margin a position you already hold. The maximum differs by asset, so read `max_leverage` from `/api/v1/perp/meta` first; a value above it is rejected by the exchange. `is_cross` chooses cross margin (the account's whole margin backs the position) or isolated margin (only the margin committed to that position does).Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.GET/api/v1/perp/meta
Get perp asset metadata
Fetch the tradeable perpetual assets and their trading constraints. Each asset reports `asset_id`, `name` — the symbol to pass as `coin` on the trading endpoints — `sz_decimals`, the size precision the exchange accepts and therefore what order sizes are rounded to, and `max_leverage`. Worth reading before a wallet's first order on an asset: an unknown symbol is rejected with a `422`, and leverage above the asset's maximum is rejected by the exchange.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/perp/order
Prepare a perp order
Build an unsigned Hyperliquid order for you to sign locally. This is the first step of the **prepare → sign → execute** flow. Nothing reaches the exchange until you submit the signed payload to `/api/v1/perp/execute`, so this call places no order and moves no funds. **Prerequisite:** orders are routed with Nansen's builder code, and Hyperliquid rejects them until the wallet has approved a matching fee rate. Check `/api/v1/perp/builder-fee` first and, if `approved` is false, run the one-time approval through `/api/v1/perp/approve-builder-fee`. **What you get back:** `action` (the exchange action), `nonce`, and `eip712` (the typed data to sign). Sign the EIP-712 payload with the wallet's key — the key never leaves your side — then post `action`, `nonce` and the resulting `{r, s, v}` signature to `/api/v1/perp/execute` exactly as returned. Any edit to `action` or `nonce` invalidates the signature. An order may be signed by the wallet's own key or by an API (agent) wallet the wallet has approved. The `nonce` …Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.GET/api/v1/perp/orders
Get open perp orders
Fetch a wallet's resting limit orders and untriggered trigger orders. The take-profit and stop-loss legs of a bracket order appear here until they trigger. Use each entry's order id (`oid`) as the `order_id` for `/api/v1/perp/cancel`. Orders that have already filled or been cancelled are not returned.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.GET/api/v1/perp/positions
Get open perp positions
Fetch a wallet's open perpetual positions — asset, signed size (negative for a short), entry price, leverage, unrealized PnL and liquidation price. This is where the `size` and `is_buy` for `/api/v1/perp/close` come from: read the position instead of tracking it yourself, since fills, funding and partial closes all move it. An empty list means the wallet holds no open positions.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/perp/transfer
Prepare a Spot<->Perps transfer
Build an unsigned USDC transfer between a wallet's spot and perpetuals balances. Same **prepare → sign → execute** flow as `/api/v1/perp/order`: sign the returned `eip712` payload and submit it to `/api/v1/perp/execute`. This call moves nothing on its own. **Only the perpetuals balance can be used as margin.** USDC that arrives on Hyperliquid by a direct send lands in the spot balance, where perp trading cannot see it — which is what this endpoint is for. `to_perp: true` moves spot → perps, `false` moves perps → spot. `/api/v1/perp/account` reports both balances, so check there when a wallet looks funded but cannot open a position. This is a wallet-signed action, so its EIP-712 domain and types differ from an order's. Sign whatever the `eip712` field contains rather than hard-coding one payload shape.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/portfolio/defi-holdings
Get Portfolio DeFi Holdings Data
Get simplified DeFi holdings for a wallet address with aggregated tokens and protocol summaries in a user-friendly format.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/prediction-market/address-summary
Get Prediction Market Address Summary
Get wallet-level PnL summary for a single Polymarket trader. Returns realized PnL, unrealized PnL, win rate, and wallet age. **What it helps to answer:** 1. **What is this trader's overall Polymarket performance?** 2. **How many markets has this trader won vs traded?** 3. **How old is this wallet and when did it start trading?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/prediction-market/categories
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?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/prediction-market/event-screener
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?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/prediction-market/market-screener
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?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/prediction-market/ohlcv
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?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/prediction-market/orderbook
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?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/prediction-market/pnl-by-address
Get Prediction Market PnL by Address
Get profit and loss across all prediction markets for a specific wallet address. Shows per-market PnL including buy costs, sell proceeds, and redemption values. **What it helps to answer:** 1. **What is a trader's total PnL across all prediction markets?** 2. **Which markets has this address traded, and what were the results?** 3. **Does this trader have unrealized positions?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/prediction-market/pnl-by-market
Get Prediction Market PnL by Market
Get profit and loss breakdown for all traders in a specific prediction market. Includes buy cost, sell proceeds, redemption values, and unrealized positions. **What it helps to answer:** 1. **Who are the biggest winners and losers in this market?** 2. **What is the PnL distribution across traders?** 3. **How much unrealized value exists in open positions?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/prediction-market/position-detail
Get Prediction Market Position Detail
Get detailed per-token position data for all holders in a specific prediction market. Includes token balances, entry prices, current prices, and per-token PnL. **What it helps to answer:** 1. **What are the exact positions of each holder in this market?** 2. **What is the average entry price vs current price for each position?** 3. **How much has each token position gained or lost?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/prediction-market/top-holders
Get Prediction Market Top Holders
Get the largest position holders for a Polymarket prediction market. Positions are computed from on-chain ERC-1155 token transfers on Polygon, with SAFE proxy wallet resolution to identify actual users. **What it helps to answer:** 1. **Who are the biggest holders in this prediction market?** 2. **What are the position sizes and entry prices of top holders?** 3. **What is the unrealized PnL of major positions?** 4. **Are whales positioned Yes or No?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/prediction-market/trades-by-address
Get Prediction Market Trades by Address
Get all trades for a specific wallet address across all prediction markets. Trades are decoded from on-chain OrderFilled events on Polygon. **What it helps to answer:** 1. **What trades has this address made on Polymarket?** 2. **When did this trader buy or sell, and at what prices?** 3. **What markets has this address been active in?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/prediction-market/trades-by-market
Get Prediction Market Trades by Market
Get recent trades for a Polymarket prediction market. Trades are decoded from on-chain OrderFilled events on Polygon, joined with market metadata. **What it helps to answer:** 1. **What are the most recent trades in this market?** 2. **Who is buying and selling, and at what prices?** 3. **What is the trade size distribution?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/profiler/address/counterparties
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 sourcesPrice unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/profiler/address/counterparties/batch
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 entit…Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/profiler/address/current-balance
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/profiler/address/first-funder
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/profiler/address/historical-balances
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 periodsPrice unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/profiler/address/labels
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/profiler/address/pnl
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 investmentPrice unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/profiler/address/pnl-summary
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/profiler/address/premium-labels
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/profiler/address/related-wallets
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/profiler/address/transactions
Get Address Transactions Data
Retrieve recent blockchain transactions for an address including token transfers, native currency movements, and contract interactions.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/profiler/dex-trades
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?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/profiler/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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/profiler/perp-positions
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?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/profiler/perp-trades
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?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/search/entity-name
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"…Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/search/general
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", …Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.GET/api/v1/search/token-sectors
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 bef…Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.PATCH/api/v1/smart-alert
Update a smart alert
Update an existing smart alert. Provide the alert `id` plus any fields you want to change; omitted fields are left unchanged.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/smart-alert
Create a smart alert
Create a smart alert that watches on-chain activity and notifies the configured channels. Choose a `type` (common-token-transfer, sm-token-flows, or smart-contract-call), an evaluation `timeWindow`, one or more delivery `channels`, and the type-specific `data` filters. If `createdBy` is omitted it defaults to `agent`.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.GET/api/v1/smart-alert/list
List smart alerts
Return every smart alert belonging to the authenticated user.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.PATCH/api/v1/smart-alert/toggle
Enable or disable a smart alert
Toggle an alert on or off without changing its configuration. Set `isEnabled` to `true` to resume notifications or `false` to pause them.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.DELETE/api/v1/smart-alert/{alert_id}
Delete a smart alert
Permanently delete a smart alert by its ID.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/smart-money/dcas
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/smart-money/dex-trades
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/smart-money/historical-holdings
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 behaviorPrice unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/smart-money/holdings
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 tokensPrice unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/smart-money/netflow
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 transfersPrice unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/smart-money/perp-trades
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)Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/smart-money/pnl-leaderboard
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/tgm/dex-trades
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/tgm/flow-intelligence
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/tgm/flows
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`…Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/tgm/holders
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, Fun…Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/tgm/indicators
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 statePrice unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/tgm/jup-dca
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/tgm/perp-pnl-leaderboard
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 …Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/tgm/perp-positions
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?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/tgm/perp-trades
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 parametersPrice unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/tgm/pnl-leaderboard
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/tgm/position-intelligence
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/tgm/token-information
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/tgm/token-ohlcv
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 …Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/tgm/transfers
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/tgm/who-bought-sold
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/token-screener
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?**Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.GET/api/v1/trade/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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/trade/execute
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/trade/prepare
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 whi…Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.GET/api/v1/trade/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/trad…Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1/transaction-with-token-transfer-lookup
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1beta1/profiler/address/historical-token-balances
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1beta1/profiler/address/historical-transactions
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 queryPrice unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1beta1/profiler/historical-transaction-lookup
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1beta1/smart-money/historical-token-balances
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1beta1/tgm/historical-dex-trades
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` insteadPrice unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1beta1/tgm/historical-pnl-leaderboard
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 paginationPrice unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1beta1/tgm/historical-token-flow-summary
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 updatesPrice unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1beta1/tgm/historical-token-ohlcv
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_…Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1beta1/tgm/historical-token-quant-scores
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.Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1beta1/tgm/historical-top-holders
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.).Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1beta1/tgm/historical-who-bought-sold
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)Price unavailableThe operation requires declared authentication; API keys, bearer tokens and other schemes are not evidence of AEP support.POST/api/v1beta1/token-screener/historical