Nansen

Get Hyperliquid perpetual futures trader leaderboard with performance metrics. Returns: Trader performance rankings as markdown. Columns returned: - **Address** / **Label**: trader wallet, and its Nansen label if any - **Total PnL** (USD): realized + unrealized over the date range - **Realized PnL** (USD): net, from positions closed in the range. Being a net total it shows no per-trade outcome, so no win rate can be derived from it or any other column here - **Unrealized PnL** (USD): on positions still open, at the current mark price - **ROI** (%): Total PnL / (tr…

Discover and filter a daily list of attractive tokens using Nansen Score Indicators weighted by coefficients (= Performance Score). Use this tool when you don't know which tokens to buy and need recommendations based on backtested indicators. For specific token analysis (e.g., "should I buy AAVE?"), use token_quant_scores instead. **When to use this tool vs token_discovery_screener**: - Use **this tool** when you want **pre-scored buying recommendations** without specifying criteria. It answers "what should I buy?" by returning tokens that already meet a quantitative buying threshold (Perfor…

Prediction market PnL breakdown for a Polygon wallet, market by market. **When to use:** - Wallet-level Polymarket track record with per-market cost and proceeds. **Key fields:** - `Total PnL USD` = redemption + unrealized value + sell proceeds − buy cost, for that market only. - `Net Buy Cost USD` is what the wallet paid for shares. - `Net Sell Proceeds USD` is what it received for shares sold before resolution. - `Redemption Value USD` is the payout collected after the market settled. - `Unrealized Value USD` is the marked value of shares still held. - `Resolved` says whether the marke…

Prediction market summary metrics for a Polygon wallet. **When to use:** - First wallet-level Polymarket tool for a quick trader overview. - Use before detailed address trades/PnL when the user asks for a general wallet profile, activity summary, or whether a wallet is active on Polymarket. **Key fields:** - `Markets Traded` and `Markets Won` are lifetime counts; `Win Rate` is won / traded. - `Total PnL USD` = realized + unrealized. - `First Seen` and `Wallet Age (Days)` show how long the wallet has been active on Polymarket. **Pitfalls:** - The API gives no trade count, volume, or …

Prediction market trade history for a Polygon wallet. **Key fields:** - `Share Size` is quantity traded in the displayed outcome side. - `Value USD` applies to that row only, not the whole transaction. **Pitfalls:** - Use this for wallet trade activity, not profitability.

Search Polymarket for events and markets by name, topic, URL, or slug. **PM building blocks:** - An **event** is a grouped prediction topic containing many child markets. - A **market** is one tradable outcome with its own `marketId`. - Example: `2026 NCAA Tournament Winner` is an event; `Will Duke win the 2026 NCAA Tournament?` is a market. Detail tools require `marketId`, not `eventId`. **When to use:** - First tool when the user asks about a specific PM topic, event, slug, or Polymarket URL but does not provide `marketId`. - Optionally provide `queryVariant` as a cleaner short keywo…

Historical odds/volume candles for a Polymarket market. **When to use:** - Current odds / implied probability, price history, and recent probability changes on a specific market. **Key fields:** - `Close` is the share price for the displayed outcome side. - In binary markets, Yes and No shares are complementary and sum to about $1. **Pitfalls:** - Each response is for one exact `marketId` — do not mix dates or prices across different markets. - If no candles are returned for the requested window, say so directly — do not estimate. **Prerequisites:** If `marketId` is unknown, call `…

Live orderbook for a Polymarket market. **When to use:** - Bid/ask depth, liquidity, and yes-share / no-share order structure. **Key fields:** - `Order Size` is share quantity, not USD. Do not describe share size as dollar depth unless you calculate `shares × price`. **Yes/No price relationship:** - Yes and No are complementary (Yes + No ≈ $1). A No bid at price $X means willingness to buy No when Yes is near $(1−X). - A cluster of No bids at low prices (e.g. $0.20) is resistance for Yes rallying to ~$0.80, NOT a support floor for the current Yes price. - When comparing OHLCV odds aga…

PnL leaderboard for a Polymarket market. **When to use:** - Only for profitability claims. **Key fields:** - `Total PnL USD` = redemption + unrealized value + sell proceeds − buy cost, for this market only. - `Net Buy Cost USD` is what the wallet paid for shares. - `Net Sell Proceeds USD` is what it received for shares sold before resolution. - `Redemption Value USD` is the payout collected after the market settled. - `Unrealized Value USD` is the marked value of shares still held. - `Side Held` reflects current side exposure where the API provides it. **Pitfalls:** - The API gives no R…

Detailed position breakdown for a Polymarket market. **Key fields:** - `Position Size (Shares)` is the share quantity still held. - `Buy Cost USD` and `Sell Proceeds USD` are the cash paid and received for this outcome token. - `Unrealized Value USD` is the marked value of shares still held; `Redemption Value USD` is the payout collected after settlement. - `Position PnL USD` applies to the displayed row only — not the wallet's total PM activity. **Pitfalls:** - Each row is one outcome token of one wallet. A wallet holding both sides appears twice. **Prerequisites:** If `marketId` i…

Browse and sort Polymarket markets, events, or categories. **When to use:** - Broad discovery, screening, and ranked browsing across many markets. - Do NOT use this to resolve one named market/event/slug/URL — use `prediction_market_lookup` instead. **Query tips:** - Literal-style matching on text and slugs, not fuzzy web search. - Prefer one short topic or slug fragment (e.g. `fed cuts`, `zelensky`, `ncaa tournament`). - Do not bundle unrelated topics (e.g. `bitcoin ethereum politics weather`). If a broad question spans several topics, run separate screener queries for each. - If a …

Largest current holders for a Polymarket market. **Key fields:** - Positions are share balances, not USD notional. - `Position Value USD` is current marked value, not payout at resolution. - `Side Held` is the share side currently held. **Pitfalls:** - The visible holder table is the source of truth for holder-side concentration — do not infer risk, max loss, or potential profit unless the tool output explicitly provides it. - Output summary is based only on shown rows, not the entire holder table. - Large visible positions or labels do not by themselves identify smart money unless Nan…

Recent trades for a Polymarket market. **When to use:** - Source of truth for recent fills and latest trade-tape pricing. - Do not overwrite recent trade prices with older OHLCV candles. **Key fields:** - `Share Size` is quantity; `Value USD` is dollar value. - Each row is one visible trade leg — `Value USD` applies to that row, not the whole transaction hash. **Pitfalls:** - Large visible trades do not by themselves identify smart money or institutions. **Prerequisites:** If `marketId` is unknown, call `prediction_market_lookup` first.

Get Jupiter DCA (dollar-cost-averaging) orders opened by smart traders and funds on Solana, including deposit size, amount spent so far and order status. Use this for scheduled accumulation intent; use smart_traders_and_funds_dex_trades for one-off swaps.

Get individual (per wallet, per transaction) DEX trades made by smart traders and funds (EXCLUDES whales, large holders, influencers, etc.) across all chains (default is ['all']) or specific chain(s). Use this to see exactly which wallet bought or sold what; use smart_traders_and_funds_netflow for the aggregated view.

Get the day-by-day history of aggregated smart trader and fund token balances (EXCLUDES whales, large holders, influencers, etc.) for a date range on base, bnb, ethereum, monad, robinhood or solana. Use this to see how smart money holdings changed over time; use smart_traders_and_funds_token_balances for the current snapshot. This endpoint uses inclusive UTC calendar dates, not rolling timestamps.

Get aggregated (not per wallet) smart trader and fund (EXCLUDES whales, large holders, influencers, etc.) net USD flow per token over 1h/24h/7d/30d, per chain for all chains (default is ['all']) or specific chain(s). Use this for what smart money is buying or selling right now; use smart_traders_and_funds_token_balances for what they hold.

Get recent Hyperliquid perpetual futures trades from Smart Money addresses across all tokens. Optional labels narrow this cohort; they do not search all addresses with that label. For a broad view of Smart Money activity across all tokens, use token_discovery_screener with traderType="sm". **Note:** This endpoint is Hyperliquid-only (perpetual futures data). It returns recent trades only (no date filtering available). Columns returned: - **Time**: Timestamp when the trade occurred (datetime: YYYY-MM-DD HH:MM:SS) - **Side**: Position direction - Long or Short - **Action**: Order action - Add…

Rank smart trader and fund addresses (EXCLUDES whales, large holders, influencers, etc.) by realized, unrealized and total USD PnL over a 1/7/30/90/180 day window, with ROI, win rate and trade counts. Use this to find the best performing smart money wallets; use token_pnl_leaderboard for the best performers on one specific token.

Get aggregated (not per wallet) smart trader and fund (EXCLUDES whales, large holders, influencers, etc.) token balances and 24h change per chain for all chains (default is ['all'], which queries all supported chains) or specific chain(s). Use filters to narrow down the results.

Submit product feedback for the authenticated Nansen account. Costs zero credits, including with zero balance. Send when the user requests or approves this report. Before a new automatic report, call get_feedback_preferences for a fresh account preference. If it is off, unconfigured or unavailable, show the report and ask before sending. If the user refuses or you cannot ask, do not send. Enabled permits sending subject to host controls. One report approval does not change the preference. Never enable it yourself. Host denial means no submission. A feedback_not_enabled refusal means stop auto…

Get upto 25 (per page) top holders information for a specific token. **Note:** Using `labelType: smart_money` is not a good proxy for an overall market view. Use it only if user explicitly requests it, or to combine it with other non smart money data. **Modes:** - `onchain_tokens` (default): Analyze on-chain tokens by contract address - `perps`: Analyze Hyperliquid perpetual futures by symbol (chain auto-set to "hyperliquid") Columns returned (onchain_tokens mode): - **Address**: Wallet/contract address of the token holder - **Label**: Nansen label (e.g., exchange, whale, etc.) - **Balance*…

Get DEX trades for a specific token. **Modes:** - `onchain_tokens` (default): Analyze on-chain tokens by contract address - `perps`: Analyze Hyperliquid perpetual futures by symbol (chain auto-set to "hyperliquid") **NOTE:** In onchain_tokens mode, only ETH is supported among native tokens. For other native tokens (SOL, BTC, BNB, etc.), use perps mode instead.

Get comprehensive token screening data across multiple blockchain networks with advanced filtering. A maximum of 25 results per page are returned out of 1000s of tokens. Use the sorting and filtering options to narrow down the results. In a mixed spot + hyperliquid request, `page` applies to both the spot and perps sections. A maximum of 5 chains can be specified per request (excess chains are automatically trimmed). This tool helps with token discovery and finding trending tokens by combining different metrics: volume, liquidity, market cap, smart money activity, and token age. **IMPORTANT…

Get hourly token-flow history for ONE holder segment over a date range. Use `token_recent_flows_summary` instead for an on-chain snapshot across ALL wallet categories. **Note:** Using `holder_segment: smart_money` is not a good proxy for an overall market view. Use it only if user explicitly requests it, or to combine it with other non smart money data. This is a **more granular** tool than `token_recent_flows_summary` and provides the TOTAL flows over the entire time frame broken down by segment. **Modes:** - `onchain_tokens` (default): Analyze on-chain tokens by contract address - `perps`…

Get token information — spot on-chain details or Hyperliquid perpetual futures stats. On-chain tokens mode (default): Returns token details (name, symbol, market cap, FDV, supply, deployment date, socials) and spot trading metrics (volume, buys/sells, buyers/sellers, holders, liquidity). Perps mode: Returns Hyperliquid perp stats — mark price, funding, open interest, buy/sell pressure, trader participation. Returns: Token information as markdown. On-chain tokens fields: - **Market Cap / FDV**: Market capitalization and fully diluted valuation - **Circulating / Total Supply*…

Get Jupiter DCA (dollar-cost-averaging) orders opened against a Solana token, with deposit size, amount spent so far, amount accumulated and order status. Use this to see scheduled buying or selling pressure that has not hit the market yet; use token_dex_trades for trades already executed. Solana tokens only.

Get OHLCV (Open, High, Low, Close, Volume) price data for a token with automatic interval resolution. Supports EVM chains and Solana for on-chain tokens, AND Hyperliquid perpetual futures. For Hyperliquid perps, pass `chain="hyperliquid"` and use the perp symbol as `tokenAddress` (e.g. "BTC", "HYPE" for native perps; "XYZ:ORDI" for XYZ-namespaced perps — prefix is normalized automatically). **YOU MUST USE THIS** over `general_search` to get prices. **`general_search` prices are delayed and often incorrect.** To get **LATEST** price set from to '5MIN_AGO' and to to 'NOW'. Resolution is auto…

Upto 25 results (per page) of trader PnL for a token. Use the sorting and filtering options to narrow down the results. **Modes:** - `onchain_tokens` (default): Analyze on-chain tokens by contract address - `perps`: Analyze Hyperliquid perpetual futures by symbol (chain auto-set to "hyperliquid") — supports native tokens **NOTE:** This tool does not support native tokens (so11111111111111111111111111111111111111112, 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee) in `onchain_tokens` mode. Native tokens (by symbol - SOL, ETH, ARB etc) ARE fully supported in `perps` mode. Returns: Trader perf…

Get Nansen Score Indicators for a token - quantitative risk and reward signals. Use this tool when assessing a token's risk/reward profile, evaluating buy/sell decisions, or when the user needs quantitative data to make trading decisions. Returns: Token risk/reward indicators as markdown with interpretation guidance. Token info: - **Market Cap**: Current market cap in USD - **Market Cap Group**: largecap (>$1B), midcap ($100M-$1B), or lowcap (<$100M) - **Is Stablecoin**: Whether token is a stablecoin (some indicators don't apply to stablecoins) Fields returned per i…

Get an on-chain flow snapshot across **ALL** wallet categories in one call. This tool supports native ETH on Ethereum and native SOL on Solana, and is the correct choice for standard lookbacks such as 1d. Returns **TOTAL** token flows per segment: 1. Public Figures 2. Top PnL Traders 3. Whales 4. Smart Traders 5. Exchanges 6. Fresh Wallets Inflow and outflow of tokens between the segments is CRITICAL in identifying token price trends. The values provided are **aggregated over the specific lookback period (last 5min, 1d, 7d etc) specified**. If you have SPECIFIC date …

List valid token sectors for token discovery filters.

Get a technical-analysis snapshot for a token: SMA(20/50/200), EMA(12/26), RSI(14), MACD(12,26,9), Bollinger Bands(20, 2σ), ATR(14), and rolling VWAP(20), computed from the last 260 closed candles at an explicit timeframe. Supports EVM chains and Solana for on-chain tokens, AND Hyperliquid perpetual futures. For Hyperliquid perps, pass `chain="hyperliquid"` and use the perp symbol as `tokenAddress` (e.g. "BTC", "HYPE" for native perps; "XYZ:ORDI" for XYZ-namespaced perps — prefix is normalized automatically). **YOU MUST USE THIS** for technical analysis instead of computing indicators from r…

Get 25 token transfers (per page) for a specific token based on the sort order. Default: the last 24 hours, largest transfers first (orderBy "amount", "desc"). Direction rules (fromAddress = the sender, toAddress = the receiver): - "Transfers of X", "X's transfers", "track X", and "what is X doing" do not name a direction. For these, make two calls with the same address: one with fromAddress, one with toAddress. Sort both by amount. Each call then shows different transactions: the largest sent and the largest received. - Use only fromAddress when the user asks what X sent (outflows, w…

Get TOTAL amount of tokens bought/sold by address for a token on DEX (Decentralised Exchanges) ONLY. Use this tool to find out WHO is buying or selling a token (on DEX) AND then you can check if they are liquidating profits or accumulating more. Returns: Aggregated buyer/seller activity as markdown. Returns empty string if no trading data found. Columns returned: - **Address**: Trader's wallet address - **Label**: Nansen label of the address - **Bought Token Volume**: Total quantity of tokens purchased - **Sold Token Volume**: Total quantity of tokens sold - **Gr…

Get comprehensive transaction details including token transfers.

Get PnL stats for a specific token traded by the input address during a specific date range. Use this tool for analysing the performance of the wallet for the specific token over a time period. Chain: pass 'hyperliquid' for a perp coin — there `tokenAddress` is the perp SYMBOL (e.g. 'BTC', 'HYPE', 'xyz:CL'), not a contract address. Every other chain expects a token contract address.

Get aggregate stats of overall realized PnL for the input address. For Hyperliquid perp traders (chain='hyperliquid'), includes realized PnL from fills plus a current unrealized snapshot of open positions. For chain='all'/'evm' on an EVM address, reports spot/on-chain and Hyperliquid perp results as separate sections (never summed). For a single named chain, this tool covers realized PnL only. Use this tool for analysing the performance of the wallet over a time period.