> For the complete documentation index, see [llms.txt](https://docs.nansen.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nansen.ai/mcp/connectors.md). # Connectors Connect Nansen to ChatGPT, Claude, Grok, or Muse with your Nansen account. OAuth sign-in, no API key. Read onchain data and send product feedback. A connector is the quickest way to use Nansen from an AI assistant. You install Nansen from a directory or set up a custom connector, sign in with your Nansen account, and approve access to data and product feedback. There is no API key to create or paste. | Client | How to connect | | ------------------------------ | ------------------------------------------------------------------------------- | | ChatGPT (web, desktop, mobile) | [Install from the ChatGPT plugin directory](/mcp/connectors/chatgpt.md) | | Claude (web, desktop, mobile) | [Install from the Claude connector directory](/mcp/connectors/claude.md) | | Claude Code | [Add the server and sign in with `/mcp`](/mcp/connectors/claude.md#claude-code) | | Claude in Slack | [Connect through Claude Tag](/mcp/connectors/claude-tag.md) | | Grok | [Add a custom connector](/mcp/connectors/grok.md) | | Muse | [Paste a prompt to set up a custom connector](/mcp/connectors/muse.md) | All connectors use the same server, `https://mcp.nansen.ai/ra/connector-curated/mcp`, which offers the [curated tools](#curated-tools). Each client controls which tools it publishes or makes available; a server update does not guarantee that every client has refreshed its catalog. If you need tools outside this set, or your client has no connector, see [Manually connecting to Nansen MCP](/mcp/connecting.md). ### How sign-in and billing work * **Sign-in:** OAuth with your Nansen account. The only scope requested is `nansen:read`. * **Billing:** data-tool calls spend the [API credits](/getting-started/credits.md) of the Nansen account you signed in with, not your ChatGPT, Claude, Grok, or Muse subscription. Calls are subject to that account's [rate limits](/getting-started/rate-limits.md). * **Cost per prompt:** one prompt can trigger several tool calls, and some calls cost more than others. See [credits per call](#credits-per-call). * **Access:** data tools read data; `submit_feedback` saves a report with Nansen. Connectors cannot trade, sign transactions, move assets, or change your saved feedback preference. * **Feedback:** preference reads, submissions and receipt reads cost zero credits, even with a zero balance. Submission still requires account rollout access and is subject to the separate seven-report weekly allowance. * **Usage:** check your balance and per-call usage at [Nansen API](https://app.nansen.ai/api?tab=usage-analytics). ### Curated tools The server offers 12 data tools and three feedback tools. Check the tool list in your client for current availability: | Tool | Title | Description | | ---------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `general_search` | Searching Nansen | Search for a token or entity, or resolve an address label or .eth/.sol domain, before detailed analysis. | | `token_info` | Loading token info | Get spot token metadata, market data, supply, liquidity, and holder counts, or Hyperliquid perp stats including mark price, funding rate, and open interest. | | `token_ohlcv` | Loading price data | Get open/high/low/close prices and volume for a spot token or Hyperliquid perp over any time range, including the latest price, at automatically chosen intervals. | | `token_quant_scores` | Loading token scores | Assess a spot token's risk and reward with Nansen quantitative indicators covering momentum, funding, liquidity, concentration, and supply. Hyperliquid perps are not supported. | | `token_discovery_screener` | Discovering tokens | Discover spot tokens by market, flow, sector, age, and trader filters, or Hyperliquid perps by open interest, funding, netflow, and cohorts. | | `token_recent_flows_summary` | Summarizing recent token flows | Compare recent on-chain flows across Smart Money, whales, exchanges, fresh wallets and other cohorts, or current aggregate long/short positioning by cohort on Hyperliquid. | | `token_who_bought_sold` | Finding token buyers and sellers | Find the wallets that bought or sold a token on decentralised exchanges in a period, with their Nansen labels and buy/sell volumes. | | `smart_traders_and_funds_token_balances` | Checking Smart Money positions | Get current token balances held by Smart Traders and funds, aggregated across wallets with 24h change. Excludes whales, large holders, and influencers. | | `address_portfolio` | Loading a wallet portfolio | Get a complete wallet portfolio, including token balances, DeFi positions, and supported Hyperliquid spot and perp positions, or an entity's aggregated token balances. | | `address_counterparties` | Finding wallet counterparties | Find the wallets and entities that transact most with a given address or entity, ranked by transfer volume, with the top tokens moved between them. | | `address_related_addresses` | Finding related wallets | Find special address relationships such as first funders, signers, multisig signers, deployers, and created contracts. | | `wallet_pnl_summary` | Analyzing wallet performance | Analyze spot/on-chain realized wallet PnL, or Hyperliquid realized PnL plus current unrealized PnL for open perp positions. | | `get_feedback_preferences` | Reading Nansen feedback preferences | Read the authenticated account's saved automatic feedback preference. Free; no report quota. Before a new automatic report about useful Nansen friction, draft a concise report without secrets or unnecessary conversation details and call this tool. Enabled permits sending subject to host and local-deny controls and account rollout. If off, unconfigured or unavailable, show the report and ask first. Refusal, host denial or inability to ask means no submission. An explicit request or approval permits only that report. Never enable the preference automatically. Direct lasting changes to Nansen app settings. Reads are fresh, use this account only, and do not authorize another account or server key. | | `submit_feedback` | Sending feedback to Nansen | Send feedback to Nansen, not GitBook. 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 automatic retries and tell the user the feature is not enabled for this account. Approval and saved preferences do not override rollout. Seven accepted reports per account per week across all clients, resetting Monday 00:00 UTC. Generate submission\_id once per new report; reuse it and the exact report for retries and re-invocations. Never replace an ID after a timeout. Limits: description/goal/expected/observed/workaround 2,000 Unicode characters each; endpoint/tool 256; 10 distinct request IDs of 128 characters; client name/version 64; total JSON body 16 KiB UTF-8. Missing capabilities need no endpoint, tool, or request ID. Omit secrets. Received means saved, not fixed. Failures preserve recovery guidance. No alternate-account or server-key fallback. | | `get_feedback` | Reading a Nansen feedback receipt | Read a Nansen feedback receipt for the same authenticated account. Costs zero credits. Lookup uses feedback\_id, consumes no report slot, and returns fresh status. Received means saved; reviewed means triaged; closed has a public disposition. No fix or delivery date is promised. Unknown, expired, and other-account IDs return the same not-found response. Never create a replacement report or use another account, an internal server key, or GitBook when lookup fails. | These are a curated subset of the [full tool catalog](/mcp/connecting/tools.md), which you get by [connecting manually with an API key](/mcp/connecting.md). ### Product feedback When your client exposes the feedback tools, ask it to read your current preference with `get_feedback_preferences`. This read is free and does not enable automatic reporting. If the preference is off, unconfigured or unavailable, the assistant should show its proposed report and ask before sending. Host approval controls still apply. One-report approval does not change the saved preference. `submit_feedback` saves a report; a received receipt means saved, with no promise of a fix or delivery date. Keep its `submission_id` and exact report after a timeout or other uncertain outcome. Use `get_feedback` with the returned `feedback_id` to read its receipt. Never create a replacement ID just to retry. If the API returns `feedback_not_enabled`, stop automatic retries and keep the submission ID. Reconnecting, buying credits or switching accounts is not a way around rollout. See [Feedback](/api/feedback.md) for permissions, quota and recovery details. ### Credits per call Data-tool calls are billed at the [credit rates](/getting-started/credits.md) of the Nansen API endpoints it uses. Each successful underlying API request is charged, so a tool call that fails can still cost credits for requests that succeeded before the failure. | Tool | Credits per call | Notes | | ---------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | `general_search` | 0, or 500 for an address | Token and entity searches are free. Labeling an address or resolving an `.eth` or `.sol` name costs 500. | | `token_info` | 1 | | | `token_ohlcv` | 1 | Plus 500 if the token is missing from Nansen's search index. See [token name lookup](#token-name-lookup). | | `token_discovery_screener` | 1 | 2 when one call screens both spot chains and Hyperliquid. | | `token_recent_flows_summary` | 1 | Plus 500 if the token is missing from Nansen's search index. See [token name lookup](#token-name-lookup). | | `token_who_bought_sold` | 1 | | | `address_portfolio` | 1 | 2 for a wallet with mode `all`, which adds DeFi positions. 0 with mode `hyperliquid`. An entity lookup costs 1 in any mode. | | `wallet_pnl_summary` | 1 per chain | 2 for an EVM address with the default chain, which adds Hyperliquid PnL. | | `address_related_addresses` | 1 per chain | With chain `all`, 1 plus 1 per chain the wallet is active on. | | `token_quant_scores` | 5 | | | `smart_traders_and_funds_token_balances` | 5 | | | `address_counterparties` | 5 | | | `get_feedback_preferences` | 0 | Reads the saved automatic-reporting preference. | | `submit_feedback` | 0 | Saves a report when permitted; uses a separate report allowance. | | `get_feedback` | 0 | Reads a receipt for the same account; uses no report allowance. | #### Token name lookup `token_ohlcv` and `token_recent_flows_summary` look up the token's name before the main request. The lookup is free for tokens in Nansen's search index, which covers most tokens. For a token missing from the index, the tool fetches the name from Nansen labels instead, which costs 500 credits. For every tool in the full catalog, see [Full tool catalog](/mcp/connecting/tools.md#quick-reference). ### When a call fails Connectors fail closed. A failed call returns a safe error message with a **request ID**. The message does not expose tokens, API keys, account IDs, or internal details. | What you see | What to do | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | A sign-in prompt again, or access denied | Reconnect with the intended Nansen account. | | Insufficient credits | Check the balance of the account you signed in with at [Nansen API](https://app.nansen.ai/api?tab=api), then add credits. | | Rate limit reached | Wait, then retry. Follow any retry guidance in the error. | | Error with a request ID | Send the request ID, your prompt, and the time to Nansen support. Do not share tokens, API keys, or screenshots of secrets. | | The assistant answers without calling Nansen | Make sure Nansen is enabled in the conversation and ask it explicitly to use Nansen. | Client-specific fixes are on each client's page. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.nansen.ai/mcp/connectors.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.