{ "commands": { "perp": { "description": "Hyperliquid perpetual trading commands", "subcommands": { "order": { "submitsTo": "https://api.hyperliquid.xyz/exchange", "apiEndpoints": [ "/api/v1/perp/meta", "/api/v1/perp/builder-fee", "/api/v1/sanctions/screen" ], "description": "Place a perp order (limit or market, with optional take-profit/stop-loss)", "options": { "coin": { "type": "string", "required": true, "description": "Asset symbol, e.g. BTC, ETH (alias: --symbol)" }, "side": { "type": "string", "required": true, "enum": [ "buy", "long", "sell", "short" ], "description": "buy/long opens a long, sell/short opens a short" }, "size": { "type": "string", "required": true, "description": "Position size in base asset units" }, "price": { "type": "string", "required": true, "description": "Limit price (or mark price for market orders)" }, "type": { "type": "string", "default": "limit", "enum": [ "limit", "market" ], "description": "Order type" }, "tif": { "type": "string", "default": "Gtc", "enum": [ "Gtc", "Ioc", "Alo" ], "description": "Time-in-force" }, "slippage": { "type": "string", "default": "0.03", "description": "Slippage tolerance for market orders as a decimal in [0,1] (0.03 = 3%)" }, "take-profit": { "type": "string", "description": "Take-profit trigger price" }, "stop-loss": { "type": "string", "description": "Stop-loss trigger price" }, "wallet": { "type": "string", "description": "Wallet name (defaults to the configured default wallet)" } } }, "cancel": { "submitsTo": "https://api.hyperliquid.xyz/exchange", "apiEndpoints": [ "/api/v1/perp/meta", "/api/v1/sanctions/screen" ], "description": "Cancel an open order by order id", "options": { "coin": { "type": "string", "required": true, "description": "Asset symbol (alias: --symbol)" }, "oid": { "type": "string", "required": true, "description": "Order id to cancel" }, "wallet": { "type": "string", "description": "Wallet name" } } }, "close": { "submitsTo": "https://api.hyperliquid.xyz/exchange", "apiEndpoints": [ "/api/v1/perp/positions", "/api/v1/perp/meta", "/api/v1/perp/builder-fee", "/api/v1/sanctions/screen" ], "description": "Close a position (reduce-only market order)", "options": { "coin": { "type": "string", "required": true, "description": "Asset symbol (alias: --symbol)" }, "size": { "type": "string", "required": true, "description": "Size to close in base asset units" }, "price": { "type": "string", "required": true, "description": "Mark price" }, "side": { "type": "string", "required": true, "enum": [ "buy", "sell" ], "description": "sell closes a long, buy closes a short" }, "slippage": { "type": "string", "default": "0.03", "description": "Slippage tolerance as a decimal in [0,1] (0.03 = 3%)" }, "wallet": { "type": "string", "description": "Wallet name" } } }, "leverage": { "submitsTo": "https://api.hyperliquid.xyz/exchange", "apiEndpoints": [ "/api/v1/perp/meta", "/api/v1/sanctions/screen" ], "description": "Set leverage and margin mode for an asset", "options": { "coin": { "type": "string", "required": true, "description": "Asset symbol (alias: --symbol)" }, "leverage": { "type": "string", "required": true, "description": "Leverage multiplier (positive integer, capped at the asset maximum)" }, "margin-type": { "type": "string", "default": "cross", "enum": [ "cross", "isolated" ], "description": "Margin mode" }, "wallet": { "type": "string", "description": "Wallet name" } } }, "transfer": { "submitsTo": "https://api.hyperliquid.xyz/exchange", "apiEndpoints": [ "/api/v1/sanctions/screen" ], "description": "Move USDC between a wallet's Spot and Perps balances", "options": { "direction": { "type": "string", "required": true, "enum": [ "spot-to-perp", "perp-to-spot" ], "description": "Transfer direction" }, "amount": { "type": "string", "required": true, "description": "USDC amount to transfer" }, "wallet": { "type": "string", "description": "Wallet name (defaults to the configured default wallet)" } } }, "approve-builder-fee": { "submitsTo": "https://api.hyperliquid.xyz/exchange", "apiEndpoints": [ "/api/v1/perp/builder-fee", "/api/v1/sanctions/screen" ], "description": "Authorize the Nansen builder fee (one-time; auto-fired on the first order/close)", "options": { "wallet": { "type": "string", "description": "Wallet name (defaults to the configured default wallet)" } } }, "positions": { "endpoint": "/api/v1/perp/positions", "description": "View open positions", "options": { "wallet": { "type": "string", "description": "Wallet name" } } }, "orders": { "endpoint": "/api/v1/perp/orders", "description": "View open/resting orders", "options": { "wallet": { "type": "string", "description": "Wallet name" } } }, "account": { "endpoint": "/api/v1/perp/account", "description": "View account state (account value, unrealized PnL, margin, withdrawable)", "options": { "wallet": { "type": "string", "description": "Wallet name" } } }, "meta": { "endpoint": "/api/v1/perp/meta", "description": "View available perp assets (id, size decimals, max leverage)", "options": { "filter": { "type": "string", "description": "Filter assets by name substring (also shows the full matching set)" }, "all": { "type": "boolean", "description": "Show all assets instead of the first 20" } } } }, "notes": "Signed locally and submitted directly to Hyperliquid. apiEndpoints lists the Nansen API routes each command reads (compliance screening, market metadata, builder-fee status)." }, "bridge": { "description": "Move funds between Base and Hyperliquid", "notes": "Supported routes: base -> hyperliquid (deposit); hyperliquid -> base, hyperliquid -> ethereum, hyperliquid -> arbitrum (withdrawal). Any other combination is rejected. Deposits broadcast an EVM transaction from the local wallet, so they require a locally signable origin chain; withdrawals sign a Hyperliquid action and never transact on the destination chain.", "routes": [ { "origin": "base", "destination": "hyperliquid", "direction": "deposit" }, { "origin": "hyperliquid", "destination": "base", "direction": "withdrawal" }, { "origin": "hyperliquid", "destination": "ethereum", "direction": "withdrawal" }, { "origin": "hyperliquid", "destination": "arbitrum", "direction": "withdrawal" } ], "subcommands": { "quote": { "endpoint": "/api/v1/perp/bridge/quote", "description": "Get a bridge quote and cache it locally for execute (quotes expire after 1 hour)", "options": { "from-chain": { "type": "string", "required": true, "enum": [ "base", "hyperliquid" ], "description": "Source chain (alias: --from)" }, "to-chain": { "type": "string", "required": true, "enum": [ "hyperliquid", "base", "ethereum", "arbitrum" ], "description": "Destination chain (alias: --to)" }, "from-token": { "type": "string", "required": true, "description": "Source token symbol (USDC) or address (alias: --token)" }, "to-token": { "type": "string", "default": "USDC", "description": "Destination token symbol or address" }, "amount": { "type": "string", "required": true, "description": "Amount in base units by default. USDC is 6 decimals on EVM chains but 8 on Hyperliquid, so prefer --amount-unit to avoid the per-chain magnitude trap." }, "amount-unit": { "type": "string", "enum": [ "token", "usd" ], "description": "Interpret --amount as a human token amount or a USD amount. Omit for base units." }, "slippage": { "type": "number", "default": 50, "description": "Slippage in whole basis points, 0-10000 (50 = 0.5%)" }, "recipient": { "type": "string", "description": "Destination wallet address (defaults to the signing wallet)" }, "wallet": { "type": "string", "description": "Wallet name (defaults to the configured default wallet)" } }, "prerequisites": [ "A wallet must be configured. Run: nansen wallet create" ] }, "execute": { "endpoint": "/api/v1/perp/bridge/execute", "apiEndpoints": [ "/api/v1/perp/bridge/execute", "/api/v1/perp/bridge/status", "/api/v1/sanctions/screen" ], "description": "Execute a cached bridge quote. Screens the signing wallet, signs, submits, then polls to completion.", "notes": "The wallet must match the one the quote was created for. A deposit broadcasts its EVM transaction straight to a public RPC rather than through the Nansen API; only the Hyperliquid signature legs are proxied. Quotes are single-use. If a deposit transaction is stuck in the mempool, replace it by requesting a fresh quote and executing it with --nonce set to the stuck nonce and a higher --priority-fee; a replacement must reuse the nonce and outbid the original by roughly 10%.", "options": { "quote": { "type": "string", "required": true, "description": "Quote ID returned by bridge quote" }, "wallet": { "type": "string", "description": "Wallet name (defaults to the configured default wallet)" }, "priority-fee": { "type": "string", "description": "Priority fee in gwei, overriding the quoted one (EVM deposit legs only)" }, "max-fee": { "type": "string", "description": "Fee cap in gwei, overriding the computed one (EVM deposit legs only)" }, "nonce": { "type": "string", "description": "Sign at this nonce instead of the next one, to replace a stuck transaction (EVM deposit legs only)" } }, "prerequisites": [ "A wallet must be configured. Run: nansen wallet create" ] }, "status": { "endpoint": "/api/v1/perp/bridge/status", "description": "Check the status of a bridge transfer", "options": { "request-id": { "type": "string", "description": "Bridge request ID (required unless --tx-hash is given)" }, "tx-hash": { "type": "string", "description": "Source chain transaction hash (required unless --request-id is given)" } } } } }, "research": { "description": "Research and analytics commands", "subcommands": { "portfolio": { "subcommands": { "defi": { "endpoint": "/api/v1/portfolio/defi-holdings", "description": "DeFi holdings across protocols", "options": { "wallet": { "type": "string", "required": true, "description": "Wallet address to fetch DeFi positions for" } } } }, "description": "Portfolio analytics" }, "smart-money": { "subcommands": { "netflow": { "endpoint": "/api/v1/smart-money/netflow", "description": "Net capital flows (inflows vs outflows)", "options": { "chain": { "type": "string", "default": "solana", "description": "Chain to query" } } }, "dex-trades": { "endpoint": "/api/v1/smart-money/dex-trades", "description": "Real-time DEX trading activity", "options": { "chain": { "type": "string", "default": "solana", "description": "Chain to query" } } }, "perp-trades": { "endpoint": "/api/v1/smart-money/perp-trades", "description": "Perpetual trading on Hyperliquid" }, "dcas": { "endpoint": "/api/v1/smart-money/dcas", "description": "DCA strategies on Jupiter" }, "holdings": { "endpoint": "/api/v1/smart-money/holdings", "description": "Aggregated token balances", "options": { "chain": { "type": "string", "default": "solana", "description": "Chain to query" } } }, "historical-holdings": { "endpoint": "/api/v1/smart-money/historical-holdings", "description": "Historical holdings over time", "options": { "chain": { "type": "string", "default": "solana", "description": "Chain to query" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" } } } }, "description": "Smart Money analytics - track sophisticated market participants" }, "profiler": { "subcommands": { "transactions": { "endpoint": "/api/v1/profiler/address/transactions", "description": "Transaction history", "options": { "address": { "type": "string", "required": true, "description": "Wallet address to profile" }, "chain": { "type": "string", "default": "ethereum", "description": "Chain to profile the address on" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" } } }, "pnl-summary": { "endpoint": "/api/v1/profiler/address/pnl-summary", "description": "Summarized PnL metrics", "options": { "address": { "type": "string", "required": true, "description": "Wallet address to profile" }, "chain": { "type": "string", "default": "ethereum", "description": "Chain to profile the address on" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" } } }, "balance": { "endpoint": "/api/v1/profiler/address/current-balance", "description": "Current token holdings", "options": { "address": { "type": "string", "required": true, "description": "Wallet address to profile" }, "chain": { "type": "string", "default": "ethereum", "description": "Chain to profile the address on" } } }, "counterparties": { "endpoint": "/api/v1/profiler/address/counterparties", "description": "Top counterparties by volume", "options": { "address": { "type": "string", "required": true, "description": "Wallet address to profile" }, "chain": { "type": "string", "default": "ethereum", "description": "Chain to profile the address on" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" } } }, "historical-balances": { "endpoint": "/api/v1/profiler/address/historical-balances", "description": "Historical balances over time", "options": { "address": { "type": "string", "required": true, "description": "Wallet address to profile" }, "chain": { "type": "string", "default": "ethereum", "description": "Chain to profile the address on" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" } } }, "related-wallets": { "endpoint": "/api/v1/profiler/address/related-wallets", "description": "Find wallets related to an address", "options": { "address": { "type": "string", "required": true, "description": "Wallet address to profile" }, "chain": { "type": "string", "default": "ethereum", "description": "Chain to profile the address on" } } }, "first-funder": { "endpoint": "/api/v1/profiler/address/first-funder", "description": "Find the first wallet that funded an EVM address", "options": { "address": { "type": "string", "required": true, "description": "Address whose first funder to find" } } }, "pnl": { "endpoint": "/api/v1/profiler/address/pnl", "description": "PnL and trade performance", "options": { "address": { "type": "string", "required": true, "description": "Wallet address to profile" }, "chain": { "type": "string", "default": "ethereum", "description": "Chain to profile the address on" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" } } }, "labels": { "endpoint": "/api/v1/profiler/address/labels", "description": "Behavioral and entity labels", "options": { "address": { "type": "string", "required": true, "description": "Wallet address to profile" }, "chain": { "type": "string", "default": "ethereum", "description": "Chain to profile the address on" } } }, "perp-positions": { "endpoint": "/api/v1/profiler/perp-positions", "description": "Current perpetual positions", "options": { "address": { "type": "string", "required": true, "description": "Hyperliquid trader address" } } }, "perp-trades": { "endpoint": "/api/v1/profiler/perp-trades", "description": "Perpetual trading history", "options": { "address": { "type": "string", "required": true, "description": "Hyperliquid trader address" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" } } }, "dex-trades": { "endpoint": "/api/v1/profiler/dex-trades", "description": "DEX trade history for a wallet", "options": { "address": { "type": "string", "required": true, "description": "Wallet address to profile" }, "chain": { "type": "string", "default": "ethereum", "description": "Chain to profile the address on" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" } } }, "search": { "endpoint": "/api/v1/search/entity-name", "description": "Search for entities by name", "options": { "query": { "type": "string", "required": true, "description": "Entity or label name to search for" } } }, "batch": { "description": "Batch profile multiple addresses", "options": { "chain": { "type": "string", "default": "ethereum", "description": "Chain to profile every address on" }, "include": { "type": "string", "default": "labels,balance", "description": "Comma-separated sections to fetch per address: labels, balance, pnl" }, "delay": { "type": "number", "default": 1000, "description": "Delay in milliseconds between API calls" } } }, "trace": { "description": "Multi-hop counterparty trace (BFS)", "options": { "address": { "type": "string", "required": true, "description": "Address to start tracing from" }, "chain": { "type": "string", "default": "ethereum", "description": "Chain to profile the address on" }, "depth": { "type": "number", "default": 2, "description": "Hops to follow from the starting address (1-5)" }, "width": { "type": "number", "default": 10, "description": "Counterparties to follow at each hop" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days at each hop" }, "delay": { "type": "number", "default": 1000, "description": "Delay in milliseconds between API calls" } } }, "compare": { "description": "Compare two wallets (shared counterparties, tokens)", "options": { "addresses": { "type": "string", "required": true, "description": "Comma-separated list (or JSON array) of wallet addresses to compare" }, "chain": { "type": "string", "default": "ethereum", "description": "Chain to compare the wallets on" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" } } } }, "description": "Wallet profiling - detailed information about any blockchain address" }, "token": { "subcommands": { "flows": { "endpoint": "/api/v1/tgm/flows", "description": "Token flow metrics", "options": { "chain": { "type": "string", "default": "solana", "description": "Chain the token lives on" }, "token": { "type": "string", "required": true, "description": "Token contract address (mint address on Solana)" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" }, "label": { "description": "Holder segment to filter flows by", "enum": [ "top_100_holders", "smart_money", "public_figure", "whale", "exchange" ], "default": "top_100_holders" } } }, "who-bought-sold": { "endpoint": "/api/v1/tgm/who-bought-sold", "description": "Recent buyers and sellers", "options": { "chain": { "type": "string", "default": "solana", "description": "Chain the token lives on" }, "token": { "type": "string", "required": true, "description": "Token contract address (mint address on Solana)" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" }, "buy-or-sell": { "description": "Filter by buy or sell side", "enum": [ "BUY", "SELL" ], "default": "BUY" } } }, "dex-trades": { "endpoint": "/api/v1/tgm/dex-trades", "description": "DEX trading activity", "options": { "chain": { "type": "string", "default": "solana", "description": "Chain the token lives on" }, "token": { "type": "string", "required": true, "description": "Token contract address (mint address on Solana)" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" } } }, "transfers": { "endpoint": "/api/v1/tgm/transfers", "description": "Token transfer history", "options": { "chain": { "type": "string", "default": "solana", "description": "Chain the token lives on" }, "token": { "type": "string", "required": true, "description": "Token contract address (mint address on Solana)" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" } } }, "holders": { "endpoint": "/api/v1/tgm/holders", "description": "Token holder analysis", "options": { "chain": { "type": "string", "default": "solana", "description": "Chain the token lives on" }, "token": { "type": "string", "required": true, "description": "Token contract address (mint address on Solana)" }, "premium-labels": { "description": "Include premium Nansen labels in the response (true=premium, false=free-tier). When omitted, uses API default.", "type": "boolean" } } }, "pnl": { "endpoint": "/api/v1/tgm/pnl-leaderboard", "description": "PnL leaderboard", "options": { "chain": { "type": "string", "default": "solana", "description": "Chain the token lives on" }, "token": { "type": "string", "required": true, "description": "Token contract address (mint address on Solana)" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" }, "premium-labels": { "description": "Include premium Nansen labels in the response (true=premium, false=free-tier). When omitted, uses API default.", "type": "boolean" } } }, "perp-pnl-leaderboard": { "endpoint": "/api/v1/tgm/perp-pnl-leaderboard", "description": "Perp PnL leaderboard by token", "options": { "symbol": { "type": "string", "required": true, "description": "Perp symbol, e.g. BTC" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" }, "premium-labels": { "description": "Include premium Nansen labels in the response (true=premium, false=free-tier). When omitted, uses API default.", "type": "boolean" } } }, "perp-positions": { "endpoint": "/api/v1/tgm/perp-positions", "description": "Open perp positions by token symbol", "options": { "symbol": { "type": "string", "required": true, "description": "Perp symbol, e.g. BTC" } } }, "perp-trades": { "endpoint": "/api/v1/tgm/perp-trades", "description": "Perp trades by token symbol", "options": { "symbol": { "type": "string", "required": true, "description": "Perp symbol, e.g. BTC" }, "days": { "type": "number", "default": 30, "description": "Lookback window in days" } } }, "flow-intelligence": { "endpoint": "/api/v1/tgm/flow-intelligence", "description": "Detailed flow intelligence by label", "options": { "chain": { "type": "string", "default": "solana", "description": "Chain the token lives on" }, "token": { "type": "string", "required": true, "description": "Token contract address (mint address on Solana)" }, "timeframe": { "type": "string", "default": "1d", "description": "Time window for the flow metrics" } } }, "info": { "endpoint": "/api/v1/tgm/token-information", "description": "Get detailed information for a specific token", "options": { "chain": { "type": "string", "default": "solana", "description": "Chain the token lives on" }, "token": { "type": "string", "required": true, "description": "Token contract address (mint address on Solana)" }, "timeframe": { "type": "string", "default": "1d", "description": "Time window for the price-change and volume fields" } } }, "indicators": { "endpoint": "/api/v1/tgm/indicators", "description": "Risk and reward indicators for a token (Nansen Score)", "options": { "chain": { "type": "string", "default": "ethereum", "description": "Chain the token lives on" }, "token": { "type": "string", "required": true, "description": "Token contract address" } } }, "ohlcv": { "endpoint": "/api/v1/tgm/token-ohlcv", "description": "OHLCV candle data for a token", "options": { "chain": { "type": "string", "default": "solana", "description": "Chain the token lives on" }, "token": { "type": "string", "required": true, "description": "Token contract address (mint address on Solana)" }, "timeframe": { "type": "string", "default": "1d", "description": "Candle interval" } } }, "jup-dca": { "endpoint": "/api/v1/tgm/jup-dca", "description": "Jupiter DCA orders for token", "options": { "token": { "type": "string", "required": true, "description": "Token mint address" } } }, "screener": { "endpoint": "/api/v1/token-screener", "description": "Discover and filter tokens", "options": { "timeframe": { "type": "string", "default": "24h", "description": "Time window for volume, flow, and price-change metrics" }, "chain": { "type": "string", "default": "solana", "description": "Chain the token lives on" }, "include-stablecoins": { "description": "Whether to include stablecoins in screener results (default true on API side)", "default": true } } }, "top-tokens": { "endpoint": "/api/v1/nansen-score/top-tokens", "description": "Top tokens ranked by Nansen Score (public endpoint, any authenticated API key)", "options": { "market-cap": { "description": "Filter by market cap group", "enum": [ "lowcap", "midcap", "largecap" ] }, "limit": { "type": "number", "default": 25, "description": "Number of tokens to return" } } } }, "description": "Token God Mode - deep analytics for any token" }, "search": { "endpoint": "/api/v1/search/general", "description": "Search for tokens and entities across Nansen", "options": { "query": { "type": "string", "required": true, "description": "Token name, symbol, or address, or an entity name" }, "type": { "type": "string", "default": "any", "enum": ["any", "token", "entity"], "description": "Result type: token, entity, or any" }, "limit": { "type": "number", "default": 25, "description": "Maximum number of results" } } }, "perp": { "subcommands": { "screener": { "endpoint": "/api/v1/perp-screener", "description": "Screen perpetual futures contracts", "options": { "days": { "type": "number", "default": 30, "description": "Lookback window in days" }, "trader-type": { "description": "Filter by trader type. One of: all, sm, whale, public_figure, high_winrate_hl_perps_trader. Defaults to all.", "enum": [ "all", "sm", "whale", "public_figure", "high_winrate_hl_perps_trader" ] }, "sectors-filter": { "description": "Comma-separated sector:subcategory pairs to filter by, e.g. \"Crypto:AI,TradFi:Stocks\"." }, "sm-label-filter": { "description": "Comma-separated Nansen SM labels to filter by, e.g. \"30D Smart Trader\". Only applies when trader-type is all or sm." }, "trader-label-filter": { "description": "Comma-separated HL perps trader labels to filter by, e.g. \"HL Perps Whale\". Only applies when trader-type is all or sm." } } }, "leaderboard": { "endpoint": "/api/v1/perp-leaderboard", "description": "Perpetual futures PnL leaderboard", "options": { "days": { "type": "number", "default": 30, "description": "Lookback window in days" }, "premium-labels": { "description": "Include premium Nansen labels in the response (true=premium, false=free-tier). When omitted, uses API default.", "type": "boolean" } } } }, "description": "Perpetual futures analytics" }, "prediction-market": { "subcommands": { "ohlcv": { "endpoint": "/api/v1/prediction-market/ohlcv", "description": "Get Prediction Market OHLCV Candles", "options": { "market-id": { "type": "string", "required": true, "description": "Polymarket market ID (numeric, from the screener)" } } }, "orderbook": { "endpoint": "/api/v1/prediction-market/orderbook", "description": "Get Prediction Market Orderbook", "options": { "market-id": { "type": "string", "required": true, "description": "Polymarket market ID (numeric, from the screener)" } } }, "top-holders": { "endpoint": "/api/v1/prediction-market/top-holders", "description": "Get Prediction Market Top Holders", "options": { "market-id": { "type": "string", "required": true, "description": "Polymarket market ID (numeric, from the screener)" } } }, "trades-by-market": { "endpoint": "/api/v1/prediction-market/trades-by-market", "description": "Get Prediction Market Trades by Market", "options": { "market-id": { "type": "string", "required": true, "description": "Polymarket market ID (numeric, from the screener)" } } }, "market-screener": { "endpoint": "/api/v1/prediction-market/market-screener", "description": "Get Prediction Market Screener", "options": { "query": { "type": "string", "default": "", "description": "Text filter on market titles" }, "sort-by": { "description": "Deprecated: use --sort field:dir instead" }, "tags": { "type": "string", "description": "Comma-separated Polymarket tags to filter by" }, "min-liquidity": { "type": "number", "description": "Minimum liquidity in USD" }, "max-liquidity": { "type": "number", "description": "Maximum liquidity in USD" }, "min-unique-traders-24h": { "type": "number", "description": "Minimum unique traders in the last 24 hours" }, "max-unique-traders-24h": { "type": "number", "description": "Maximum unique traders in the last 24 hours" }, "min-volume-24hr": { "type": "number", "description": "Minimum 24-hour volume in USD" }, "max-volume-24hr": { "type": "number", "description": "Maximum 24-hour volume in USD" }, "neg-risk": { "type": "boolean", "enum": ["true", "false"], "description": "Only negative-risk markets (true, or the bare flag) or only standard markets (false)" }, "min-open-interest": { "type": "number", "description": "Minimum open interest in USD" }, "max-open-interest": { "type": "number", "description": "Maximum open interest in USD" }, "end-date-before": { "type": "string", "description": "Only markets ending before this date (ISO 8601)" }, "end-date-after": { "type": "string", "description": "Only markets ending after this date (ISO 8601)" }, "min-price": { "type": "number", "description": "Minimum outcome price (0-1)" }, "max-price": { "type": "number", "description": "Maximum outcome price (0-1)" } } }, "event-screener": { "endpoint": "/api/v1/prediction-market/event-screener", "description": "Get Prediction Market Event Screener", "options": { "query": { "type": "string", "default": "", "description": "Text filter on event titles" }, "sort-by": { "description": "Deprecated: use --sort field:dir instead" }, "tags": { "type": "string", "description": "Comma-separated Polymarket tags to filter by" }, "min-liquidity": { "type": "number", "description": "Minimum liquidity in USD" }, "max-liquidity": { "type": "number", "description": "Maximum liquidity in USD" }, "min-unique-traders-24h": { "type": "number", "description": "Minimum unique traders in the last 24 hours" }, "max-unique-traders-24h": { "type": "number", "description": "Maximum unique traders in the last 24 hours" }, "min-volume-24hr": { "type": "number", "description": "Minimum 24-hour volume in USD" }, "max-volume-24hr": { "type": "number", "description": "Maximum 24-hour volume in USD" }, "neg-risk": { "type": "boolean", "enum": ["true", "false"], "description": "Only negative-risk markets (true, or the bare flag) or only standard markets (false)" }, "min-open-interest": { "type": "number", "description": "Minimum open interest in USD" }, "max-open-interest": { "type": "number", "description": "Maximum open interest in USD" }, "end-date-before": { "type": "string", "description": "Only events ending before this date (ISO 8601)" }, "end-date-after": { "type": "string", "description": "Only events ending after this date (ISO 8601)" } } }, "pnl-by-market": { "endpoint": "/api/v1/prediction-market/pnl-by-market", "description": "Get Prediction Market PnL by Market", "options": { "market-id": { "type": "string", "required": true, "description": "Polymarket market ID (numeric, from the screener)" } } }, "pnl-by-address": { "endpoint": "/api/v1/prediction-market/pnl-by-address", "description": "Get Prediction Market PnL by Address", "options": { "address": { "type": "string", "required": true, "description": "Polymarket trader address" } } }, "position-detail": { "endpoint": "/api/v1/prediction-market/position-detail", "description": "Get Prediction Market Position Detail", "options": { "market-id": { "type": "string", "required": true, "description": "Polymarket market ID (numeric, from the screener)" } } }, "trades-by-address": { "endpoint": "/api/v1/prediction-market/trades-by-address", "description": "Get Prediction Market Trades by Address", "options": { "address": { "type": "string", "required": true, "description": "Polymarket trader address" } } }, "categories": { "endpoint": "/api/v1/prediction-market/categories", "description": "Get Prediction Market Categories" }, "address-summary": { "endpoint": "/api/v1/prediction-market/address-summary", "description": "Get wallet-level PnL summary for a Polymarket address", "options": { "address": { "type": "string", "required": true, "description": "Polymarket trader address" } } } }, "description": "Polymarket prediction market analytics" }, "points": { "description": "Nansen Points analytics", "subcommands": { "leaderboard": { "description": "Points leaderboard" } } }, "chain-rank": { "endpoint": "/api/v1/chains/chain-rank", "description": "Rank chains by growth metrics", "options": { "timeframe-days": { "type": "number", "enum": [7, 30, 365], "default": 7, "description": "Growth window in days" }, "chain-type": { "type": "string", "enum": ["all", "evm"], "default": "all", "description": "Include all chains or only EVM chains" } } }, "token-sectors": { "endpoint": "/api/v1/search/token-sectors", "description": "List token sectors available for filtering" }, "address-premium-labels": { "endpoint": "/api/v1/profiler/address/premium-labels", "description": "Get all labels for an address, including premium labels", "options": { "address": { "type": "string", "required": true, "description": "Address to fetch labels for" }, "chain": { "type": "string", "default": "all", "description": "Chain to fetch labels for, or all" }, "page": { "type": "number", "default": 1, "description": "1-based page number" }, "limit": { "type": "number", "default": 100, "description": "Labels per page" } } }, "smart-money-pnl-leaderboard": { "endpoint": "/api/v1/smart-money/pnl-leaderboard", "description": "Rank smart money wallets by PnL", "options": { "chains": { "default": "solana", "description": "Comma-separated chains" }, "timeframe-days": { "type": "number", "enum": [1, 7, 30, 90, 180], "default": 7, "description": "Timeframe in days" }, "filters": { "type": "string", "description": "Filters as JSON object" }, "sort": { "type": "string", "description": "Sort order (field[:asc|desc])" }, "page": { "type": "number", "default": 1, "description": "1-based page number; maps to pagination.page" }, "limit": { "type": "number", "description": "Max results per page; maps to pagination.per_page" } } }, "position-intelligence": { "endpoint": "/api/v1/tgm/position-intelligence", "description": "Aggregate Hyperliquid positions by trader cohort", "options": { "symbol": { "required": true, "description": "Hyperliquid asset symbol (--token-address is accepted as an alias)" } } }, "perp-pnl-summary": { "endpoint": "/api/v1/profiler/perp-pnl-summary", "description": "Summarize realized Hyperliquid PnL for an address", "options": { "address": { "type": "string", "required": true, "description": "Hyperliquid trader address" }, "from-date": { "required": true, "description": "Start of date range" }, "to-date": { "required": true, "description": "End of date range" } } }, "historical-token-ohlcv": { "endpoint": "/api/v1beta1/tgm/historical-token-ohlcv", "description": "Historical token OHLCV candles", "options": { "token-address": { "required": true, "description": "Token address or Hyperliquid asset symbol" }, "chain": { "type": "string", "enum": ["base", "bnb", "ethereum", "hyperliquid", "solana"], "default": "solana", "description": "Chain the token lives on" }, "from-date": { "required": true, "description": "Start of data window" }, "as-of-date": { "description": "End of data window; exactly one of --as-of-date or --as-of-ts is required" }, "as-of-ts": { "description": "Exact Hyperliquid cutoff timestamp; exactly one of --as-of-date or --as-of-ts is required" }, "timeframe": { "type": "string", "required": true, "enum": ["5m", "15m", "30m", "1h", "1d", "1w"], "description": "Candle interval" }, "apply-blacklist-filter": { "type": "boolean", "description": "Apply blacklist filtering for 1d/1w non-Hyperliquid requests" } } }, "transaction-with-token-transfer-lookup": { "endpoint": "/api/v1/transaction-with-token-transfer-lookup", "description": "Look up a transaction and its token/NFT transfers", "options": { "transaction-hash": { "type": "string", "required": true, "description": "Transaction hash to look up" }, "chain": { "type": "string", "enum": ["all", "arbitrum", "avalanche", "base", "bitcoin", "bnb", "ethereum", "hyperevm", "injective", "iotaevm", "linea", "mantle", "mantra", "monad", "near", "optimism", "plasma", "robinhood", "sei", "sonic", "starknet", "sui", "ton", "tron"], "default": "ethereum", "description": "Chain the transaction was made on" }, "block-timestamp": { "description": "Block timestamp (required for bitcoin, tron, ton, starknet, and sui)" } } }, "historical-dex-trades": { "endpoint": "/api/v1beta1/tgm/historical-dex-trades", "description": "Historical DEX trades for a token at a point in time", "options": { "token-address": { "required": true, "description": "Token address" }, "from-date": { "required": true, "description": "Start of date range (YYYY-MM-DD)" }, "to-date": { "required": true, "description": "End of date range (YYYY-MM-DD)" }, "chain": { "default": "solana", "description": "Chain" } } }, "historical-pnl-leaderboard": { "endpoint": "/api/v1beta1/tgm/historical-pnl-leaderboard", "description": "Historical PnL leaderboard for a token", "options": { "token-address": { "required": true, "description": "Token address" }, "from-date": { "required": true, "description": "Start of date range (YYYY-MM-DD)" }, "to-date": { "required": true, "description": "End of date range (YYYY-MM-DD)" }, "chain": { "default": "solana", "description": "Chain" } } }, "historical-token-flow-summary": { "endpoint": "/api/v1beta1/tgm/historical-token-flow-summary", "description": "Historical token flow summary (no pagination)", "options": { "token-address": { "required": true, "description": "Token address" }, "from-date": { "required": true, "description": "Start of date range (YYYY-MM-DD)" }, "to-date": { "required": true, "description": "End of date range (YYYY-MM-DD)" }, "chain": { "default": "solana", "description": "Chain" } } }, "historical-token-quant-scores": { "endpoint": "/api/v1beta1/tgm/historical-token-quant-scores", "description": "Historical token quantitative scores at a snapshot date", "options": { "token-address": { "required": true, "description": "Token address" }, "as-of-date": { "required": true, "description": "Snapshot date (YYYY-MM-DD)" }, "chain": { "default": "solana", "description": "Chain" } } }, "historical-top-holders": { "endpoint": "/api/v1beta1/tgm/historical-top-holders", "description": "Historical top holders of a token at a snapshot date", "options": { "token-address": { "required": true, "description": "Token address" }, "as-of-date": { "required": true, "description": "Snapshot date (YYYY-MM-DD)" }, "chain": { "default": "solana", "description": "Chain" } } }, "historical-who-bought-sold": { "endpoint": "/api/v1beta1/tgm/historical-who-bought-sold", "description": "Historical buyers/sellers of a token", "options": { "token-address": { "required": true, "description": "Token address" }, "from-date": { "required": true, "description": "Start of date range (YYYY-MM-DD)" }, "to-date": { "required": true, "description": "End of date range (YYYY-MM-DD)" }, "buy-or-sell": { "default": "BUY", "description": "BUY or SELL" }, "chain": { "default": "solana", "description": "Chain" } } }, "historical-smart-money-balances": { "endpoint": "/api/v1beta1/smart-money/historical-token-balances", "description": "Historical smart money token balances at a snapshot date (no order_by)", "options": { "as-of-date": { "required": true, "description": "Snapshot date (YYYY-MM-DD)" }, "chains": { "default": "solana", "description": "Comma-separated chains" } } }, "historical-token-screener": { "endpoint": "/api/v1beta1/token-screener/historical", "description": "Historical token screener over a trailing window", "options": { "timeframe-days": { "required": true, "type": "number", "description": "Trailing window size in days" }, "to-date": { "required": true, "description": "End date for the window (YYYY-MM-DD)" }, "chains": { "default": "solana", "description": "Comma-separated chains" } } }, "historical-wallet-balances": { "endpoint": "/api/v1beta1/profiler/address/historical-token-balances", "description": "Historical token balances for a wallet at a snapshot date", "options": { "address": { "required": true, "description": "Wallet address" }, "as-of-date": { "required": true, "description": "Snapshot date (YYYY-MM-DD)" }, "chain": { "default": "ethereum", "description": "Chain" } } }, "historical-tx-lookup": { "endpoint": "/api/v1beta1/profiler/historical-transaction-lookup", "description": "Lookup a historical transaction by hash", "options": { "transaction-hash": { "required": true, "description": "Transaction hash (0x-prefixed, 66 chars)" }, "as-of-date": { "required": true, "description": "Reference date for label and pricing resolution (YYYY-MM-DD)" }, "block-timestamp": { "description": "Block timestamp (YYYY-MM-DD HH:MM:SS) — skips slow hash-resolution step if provided" }, "chain": { "default": "ethereum", "description": "Chain (ethereum, bnb, base)" } } }, "historical-wallet-transactions": { "endpoint": "/api/v1beta1/profiler/address/historical-transactions", "description": "Historical transactions for a wallet at a snapshot date", "options": { "address": { "required": true, "description": "Wallet address" }, "as-of-date": { "required": true, "description": "Snapshot date (YYYY-MM-DD)" }, "chain": { "default": "ethereum", "description": "Chain" } } } } }, "alerts": { "description": "Smart alert management — create, update, toggle, delete alerts", "subcommands": { "list": { "description": "List all alerts", "returns": [ "id", "name", "type", "timeWindow", "isEnabled", "channels", "data", "description" ] }, "create": { "description": "Create a new alert", "options": { "name": { "type": "string", "required": true, "description": "Alert name" }, "type": { "type": "string", "required": true, "description": "Alert type (e.g. sm-token-flows, common-token-transfer)" }, "chains": { "type": "string", "description": "Comma-separated chains (e.g. ethereum,solana). Merged into data." }, "telegram": { "type": "string", "description": "Telegram chat ID for notifications" }, "slack": { "type": "string", "description": "Slack webhook URL for notifications" }, "discord": { "type": "string", "description": "Discord webhook URL for notifications" }, "webhook": { "type": "string", "description": "HTTP/HTTPS endpoint URL to POST alert payloads to" }, "webhook-secret": { "type": "string", "description": "Signing secret for webhook payload verification (optional, webhook only)" }, "data": { "type": "string", "description": "Alert config JSON. --chains is merged on top." }, "description": { "type": "string", "description": "Optional description" }, "disabled": { "type": "boolean", "description": "Create alert in disabled state" } } }, "update": { "description": "Update an existing alert. Usage: nansen alerts update [options]", "options": { "name": { "type": "string", "description": "Alert name" }, "type": { "type": "string", "description": "Alert type" }, "chains": { "type": "string", "description": "Comma-separated chains. Merged into data." }, "telegram": { "type": "string", "description": "Telegram chat ID" }, "slack": { "type": "string", "description": "Slack webhook URL" }, "discord": { "type": "string", "description": "Discord webhook URL" }, "webhook": { "type": "string", "description": "HTTP/HTTPS endpoint URL to POST alert payloads to" }, "webhook-secret": { "type": "string", "description": "Signing secret for webhook payload verification (optional, webhook only)" }, "data": { "type": "string", "description": "Alert config JSON. --chains merged on top." }, "description": { "type": "string", "description": "Description" }, "enabled": { "type": "boolean", "description": "Enable alert" }, "disabled": { "type": "boolean", "description": "Disable alert" } } }, "toggle": { "description": "Enable or disable an alert. Usage: nansen alerts toggle --enabled|--disabled", "options": { "enabled": { "type": "boolean", "description": "Enable alert" }, "disabled": { "type": "boolean", "description": "Disable alert" } } }, "delete": { "description": "Delete an alert. Usage: nansen alerts delete ", "options": {} } } }, "trade": { "description": "DEX trading commands", "subcommands": { "quote": { "description": "Get a DEX swap quote (same-chain or cross-chain)", "options": { "chain": { "type": "string", "default": "base", "description": "Source blockchain (solana or base)" }, "to-chain": { "type": "string", "description": "Destination blockchain for cross-chain swap (solana or base). Omit for same-chain. At least one side must be USDC or a native token (ETH, SOL). Non-native to non-native is not supported — swap to USDC first, then bridge. Bridge providers (Li.Fi or Relay) are selected automatically based on best price. Sub-dollar swaps are supported via Relay." }, "from": { "type": "string", "required": true, "description": "Token to sell (address or symbol)" }, "to": { "type": "string", "required": true, "description": "Token to buy (address or symbol, resolved against destination chain for cross-chain)" }, "amount": { "type": "string", "required": true, "description": "Amount to swap (base units by default, or token units with --amount-unit token, USD with --amount-unit usd, or percentage of balance with --amount-unit percent)" }, "amount-unit": { "type": "string", "description": "\"token\" to specify amount in token units (e.g. 0.5 SOL), \"usd\" to specify amount in USD (e.g. 50), \"percent\" to sell a percentage of your balance (e.g. 100 for all), or \"base\" for base units (default). The CLI resolves the current token price, decimals, and balance locally; the API always receives base units." }, "wallet": { "type": "string", "description": "Wallet name (or \"walletconnect\"/\"wc\" for WalletConnect, EVM only). A configured wallet is required — run `nansen wallet create` if you haven't set one up yet." }, "to-wallet": { "type": "string", "description": "Destination wallet address for cross-chain swaps. Auto-derived from wallet if omitted." }, "aggregator": { "type": "string", "description": "Force a specific aggregator: lifi, relay, jupiter, or okx. Filters the returned quote list client-side; errors if no quote from that aggregator was returned." }, "swap-mode": { "type": "string", "default": "exactIn", "enum": ["exactIn", "exactOut"], "description": "\"exactIn\" (default) to spend exactly --amount of the sell token, or \"exactOut\" to receive exactly --amount of the buy token. Not supported together with --amount-unit percent." }, "slippage": { "type": "string", "description": "Slippage tolerance as a decimal between 0 and 1 (e.g. 0.03 for 3%). Values outside that range are rejected." }, "auto-slippage": { "type": "boolean", "description": "Let slippage be calculated automatically instead of using a fixed --slippage." }, "max-auto-slippage": { "type": "string", "description": "Upper bound applied when --auto-slippage is enabled, as a decimal between 0 and 1 (e.g. 0.03 for 3%)." }, "max-input": { "type": "string", "description": "exactOut only: hard ceiling on the sell-token spend, in base units. Required on every chain for --swap-mode exactOut. Measured against the slippage-buffered spend (input + slippage), not the bare quote input, so it matches the amount that can actually leave the wallet. Persisted with the quote and enforced before signing — a quote whose buffered spend exceeds it is refused." } }, "prerequisites": [ "A local wallet must be configured. Run: nansen wallet create" ] }, "execute": { "description": "Sign and broadcast a quoted trade", "options": { "quote": { "type": "string", "required": true, "description": "Quote ID returned by `nansen trade quote` (alias: --quote-id)." }, "chain": { "type": "string", "default": "base", "description": "Blockchain (solana or base)" }, "wallet": { "type": "string", "description": "Wallet name, or \"walletconnect\"/\"wc\" for WalletConnect (EVM only)" }, "gasless": { "type": "boolean", "description": "Relay-only: have Relay's solver pay gas + broadcast (user signs only). Requires the selected quote's aggregator to be \"relay\". Not supported via WalletConnect." }, "quote-index": { "type": "string", "description": "Pin a specific quote by 0-based index when the cached quote returned several. Must be within range; there is no fallback to the other quotes." }, "no-simulate": { "type": "boolean", "description": "Skip the pre-broadcast simulation (the eth_call revert check)." }, "no-verify-outcome": { "type": "boolean", "description": "Skip swap-outcome verification. That check simulates the swap and confirms the wallet's balance changes match the quote (input spent within your max, expected output received, no other asset moved) before broadcasting; it needs a simulation-capable endpoint (NANSEN_BASE_SIM_RPC on EVM, NANSEN_SOLANA_SIM_RPC on Solana) and degrades with a warning when none is available." }, "no-revoke-excessive-allowance": { "type": "boolean", "description": "Skip revoking an existing on-chain ERC-20 allowance before re-approving when it exceeds 10x this trade's scoped amount. By default, an oversized or legacy allowance is revoked to zero and a fresh trade-scoped allowance is granted. WalletConnect users will see separate wallet prompts for the revoke and re-approval." } } }, "bridge-status": { "description": "Check cross-chain bridge transaction status. Aggregator (Li.Fi or Relay) is auto-detected from a local tx record saved at execute time (kept 30 days); pass --aggregator to override when polling from a different machine.", "options": { "tx-hash": { "type": "string", "required": true, "description": "Source chain transaction hash" }, "from-chain": { "type": "string", "required": true, "description": "Source chain (solana or base)" }, "to-chain": { "type": "string", "required": true, "description": "Destination chain (solana or base)" }, "aggregator": { "type": "string", "description": "lifi or relay. Overrides auto-detection — use when polling from a different machine or after the 30-day local record TTL has expired." } } }, "limit-order": { "description": "Limit order management (Solana only)", "subcommands": { "create": { "description": "Place a new limit order", "options": { "from": { "type": "string", "required": true, "description": "Token to sell (address or symbol)" }, "to": { "type": "string", "required": true, "description": "Token to buy (address or symbol)" }, "amount": { "type": "string", "required": true, "description": "Amount in token units (e.g. 1.5 = 1.5 SOL)" }, "trigger-price": { "type": "number", "required": true, "description": "Trigger price in USD" }, "trigger-condition": { "type": "string", "required": true, "description": "Trigger when price is 'above' or 'below' target" }, "trigger-mint": { "type": "string", "required": true, "description": "Token whose price triggers the order (e.g. SOL)" }, "slippage-bps": { "type": "number", "description": "Slippage as a whole integer in basis points, 0-10000 (50 = 0.5%), omit for auto" }, "expires": { "type": "string", "default": "30d", "description": "Expiry duration (e.g. 24h, 7d, 30d) or epoch ms" }, "wallet": { "type": "string", "description": "Wallet name (or \"walletconnect\"/\"wc\")" } }, "chains": [ "solana" ], "prerequisites": [ "A Solana wallet must be configured. Run: nansen wallet create" ] }, "list": { "description": "List your limit orders", "options": { "state": { "type": "string", "description": "Filter by state (active, past)" }, "mint": { "type": "string", "description": "Filter by token mint address" }, "limit": { "type": "number", "default": 20, "description": "Max results per page" }, "offset": { "type": "number", "default": 0, "description": "Pagination offset" }, "sort": { "type": "string", "description": "Sort field" }, "dir": { "type": "string", "default": "desc", "description": "Sort direction (asc or desc)" }, "wallet": { "type": "string", "description": "Wallet name (or \"walletconnect\"/\"wc\")" } }, "chains": [ "solana" ] }, "cancel": { "description": "Cancel an open limit order", "options": { "order": { "type": "string", "required": true, "description": "Order ID to cancel" }, "wallet": { "type": "string", "description": "Wallet name (or \"walletconnect\"/\"wc\")" } }, "chains": [ "solana" ] }, "update": { "description": "Update trigger price or slippage on an existing order", "options": { "order": { "type": "string", "required": true, "description": "Order ID to update" }, "trigger-price": { "type": "number", "description": "New trigger price in USD" }, "slippage-bps": { "type": "number", "description": "New slippage as a whole integer in basis points (0-10000)" }, "wallet": { "type": "string", "description": "Wallet name (or \"walletconnect\"/\"wc\")" } }, "chains": [ "solana" ] } } } } }, "wallet": { "description": "Wallet management. x402 auto-payments are guarded by a client-side policy: per-payment USD cap via NANSEN_X402_MAX_AMOUNT (default 1.00; 'unlimited' to disable) and an optional recipient allowlist via NANSEN_X402_ALLOWED_PAYTO (comma-separated addresses).", "subcommands": { "create": { "description": "Create a new wallet" }, "list": { "description": "List all wallets" }, "show": { "description": "Show wallet details", "options": { "name": { "description": "Wallet name" } } }, "send": { "description": "Send tokens or native currency", "options": { "to": { "type": "string", "required": true, "description": "Recipient address" }, "chain": { "type": "string", "required": true, "enum": ["evm", "solana", "ethereum", "base"], "description": "Chain to send on (evm is an alias for ethereum)" }, "amount": { "type": "string", "required": true, "description": "Amount to send in human-readable units, e.g. 1.5" } } }, "export": { "description": "Export private keys" }, "delete": { "description": "Delete a wallet" }, "default": { "description": "Set default wallet" } } }, "account": { "description": "Show API key status, plan, and remaining credits. Does not consume credits." }, "auth": { "description": "Offline authentication status. Reports API key presence and source (env var vs config file), base URL, and x402 wallet readiness without any network call. Consumes no credits.", "subcommands": { "status": { "description": "Show where credentials come from, entirely offline", "returns": [ "logged_in", "api_key.present", "api_key.source", "api_key.masked", "config_file.path", "config_file.exists", "config_file.error", "base_url.value", "base_url.source", "x402.configured", "x402.wallets_dir", "x402.wallets_dir_error", "x402.wallet_count", "x402.default_wallet", "x402.default_wallet_provider", "x402.password.available", "x402.password.source", "x402.password.keychain_available", "offline" ], "examples": [ "nansen auth status --pretty" ] } } }, "doctor": { "description": "Diagnostics for the CLI setup: Node version, auth config, wallet storage and password hygiene, keychain availability, caches, telemetry, plus a safe API connectivity probe (unauthenticated, consumes no credits). Local checks work with the API unavailable; --offline skips network entirely.", "options": { "json": { "type": "boolean", "description": "Return machine-readable checks ({id, status, message, fix?}) instead of formatted text" }, "offline": { "type": "boolean", "description": "Skip the connectivity probe — no network access at all" } }, "examples": [ "nansen doctor", "nansen doctor --offline", "nansen doctor --json --pretty" ] }, "web": { "description": "Web search and fetch commands", "subcommands": { "search": { "description": "Search the web for one or more queries in parallel", "options": { "query": { "description": "Search query (can be repeated for multiple queries)" }, "num-results": { "description": "Number of results per query (1-20, default 10)", "default": 10 } }, "examples": [ "nansen web search \"bitcoin price\"", "nansen web search \"solana news\" --num-results 5", "nansen web search --query \"btc\" --query \"eth\"", "nansen web search \"btc\" --query \"eth\" # positional + flag merged" ] }, "fetch": { "description": "Fetch and analyze content from one or more URLs using AI", "options": { "url": { "description": "URL to fetch (can be repeated for multiple URLs)" }, "question": { "description": "Question to answer about the URL content", "required": true } }, "examples": [ "nansen web fetch https://nansen.ai --question \"What does Nansen do?\"", "nansen web fetch --url https://a.com --url https://b.com --question \"Compare these\"", "nansen web fetch https://a.com --url https://b.com --question \"Diff?\" # positional + flag merged" ] } } }, "agent": { "description": "Nansen AI research agent — ask questions about wallets, tokens, and on-chain activity", "options": { "expert": { "type": "boolean", "description": "Use expert mode (deeper analysis, slower). Default: fast mode." }, "conversation-id": { "type": "string", "format": "uuid", "description": "Continue a previous conversation by passing its UUID v4 ID" }, "json": { "type": "boolean", "description": "Output raw JSON (conversation_id, mode, text, tool_calls) instead of formatted text" } }, "examples": [ "nansen agent \"What are the top smart money inflows on Ethereum today?\"", "nansen agent \"Analyze wallet 0xd8dA...6045\" --expert", "nansen agent \"Tell me more\" --conversation-id " ], "returns": [ "conversation_id", "mode", "text", "tool_calls" ] }, "mcp": { "description": "Install, uninstall, or verify the hosted Nansen MCP server (https://mcp.nansen.ai/ra/mcp)", "subcommands": { "verify": { "description": "Check MCP server reachability and verify an API key on the paid data path (~1 credit)", "options": { "api-key": { "type": "string", "description": "API key to test; overrides NANSEN_API_KEY and ~/.nansen/config.json" }, "url": { "type": "string", "default": "https://mcp.nansen.ai/ra/mcp", "description": "Hosted MCP server URL. A saved API key is not sent to a non-default URL unless you pass --send-api-key, and never over plain HTTP to a non-loopback host." }, "send-api-key": { "type": "boolean", "description": "Presence-only flag — pass it bare, never with a value (`--send-api-key false` is rejected). Authorizes sending your saved API key to a custom --url (must be https:// or a loopback host). Not needed when you pass --api-key explicitly." }, "json": { "type": "boolean", "description": "Return machine-readable verification checks and exit non-zero on failure" } }, "examples": [ "npx -y nansen-cli mcp verify", "nansen mcp verify --json", "nansen mcp verify --url https://mcp.example.dev/ra/mcp --api-key ", "nansen mcp verify --url https://mcp.example.dev/ra/mcp --send-api-key" ] }, "install": { "description": "Add the Nansen MCP server to a client's config. Client (positional): claude-code, claude-desktop, or cursor. Uses the API key from `nansen login` / NANSEN_API_KEY; re-run after key rotation to update the entry.", "args": [ { "name": "client", "required": true, "enum": ["claude-code", "claude-desktop", "cursor"], "description": "MCP client to configure" } ], "options": { "dry-run": { "type": "boolean", "description": "Print the target config path and entry (API key redacted) without writing" } }, "examples": [ "nansen mcp install claude-code", "nansen mcp install cursor --dry-run" ] }, "uninstall": { "description": "Remove the Nansen MCP server entry from a client's config. Client (positional): claude-code, claude-desktop, or cursor.", "args": [ { "name": "client", "required": true, "enum": ["claude-code", "claude-desktop", "cursor"], "description": "MCP client to remove the entry from" } ], "options": { "dry-run": { "type": "boolean", "description": "Report whether the Nansen entry would be removed without writing" } }, "examples": [ "nansen mcp uninstall claude-code", "nansen mcp uninstall cursor --dry-run" ] } } }, "completion": { "description": "Generate a shell completion script from this schema (prints to stdout; nothing is written or fetched)", "subcommands": { "bash": { "description": "Print the bash completion script", "examples": [ "nansen completion bash > /etc/bash_completion.d/nansen", "eval \"$(nansen completion bash)\"" ] }, "zsh": { "description": "Print the zsh completion script", "examples": [ "nansen completion zsh > \"${fpath[1]}/_nansen\"" ] }, "fish": { "description": "Print the fish completion script", "examples": [ "nansen completion fish > ~/.config/fish/completions/nansen.fish" ] } } } }, "globalOptions": { "pretty": { "type": "boolean", "description": "Format JSON output for readability" }, "table": { "type": "boolean", "description": "Format output as human-readable table" }, "fields": { "type": "string", "description": "Comma-separated list of fields to include in output" }, "limit": { "type": "number", "description": "Maximum results per page for list-returning research commands; maps to pagination.per_page. General endpoints default to 10 (max 1000), while profiler address endpoints default to 20 (max 100). Supported by smart-money, profiler, token, perp, points, prediction-market, and supported research historical-* commands. Commands that declare their own limit option (search, token top-tokens, trade limit-order list) use those command-specific semantics instead; token ohlcv, profiler perp-positions, and historical-token-flow-summary do not support pagination. profiler labels defaults to 100 when omitted." }, "page": { "type": "number", "default": 1, "description": "1-based page number for list-returning research commands; maps to pagination.page. Supported by smart-money, profiler, token, perp, points, prediction-market, and supported research historical-* commands. Trade, wallet, and operational commands ignore it; token ohlcv, profiler perp-positions, and historical-token-flow-summary do not support pagination. profiler labels defaults to page 1 when omitted." }, "no-retry": { "type": "boolean", "description": "Disable automatic retry on rate limits/errors" }, "retries": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "default": 3, "description": "Max retry attempts (non-negative safe integer)" }, "cache-ttl": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "default": 300, "description": "Cache TTL in seconds (non-negative safe integer; 0 disables cache reads)" }, "format": { "type": "string", "enum": [ "json", "csv" ], "description": "Output format (default: json)" }, "x402-payment-signature": { "type": "string", "description": "Pre-signed x402 payment signature header" } }, "chains": [ "ethereum", "solana", "base", "bnb", "arbitrum", "polygon", "optimism", "avalanche", "linea", "scroll", "mantle", "ronin", "sei", "plasma", "sonic", "monad", "hyperevm", "iotaevm" ], "smartMoneyLabels": [ "Fund", "Smart Trader", "30D Smart Trader", "90D Smart Trader", "180D Smart Trader", "Smart HL Perps Trader" ] }