> 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/connecting/tools.md).

# Full tool catalog

Every tool on the Nansen MCP server, with what it does and what a call costs in API credits.

These are the tools you get when you [connect to Nansen MCP manually](/mcp/connecting.md) with an API key.

**Total tools:** 50

{% hint style="info" %}
The connectors for ChatGPT, Claude, and Grok use a separate OAuth surface with **12 curated tools**, not this full catalog: `general_search`, `token_info`, `token_ohlcv`, `token_quant_scores`, `token_discovery_screener`, `token_recent_flows_summary`, `token_who_bought_sold`, `smart_traders_and_funds_token_balances`, `address_portfolio`, `address_counterparties`, `address_related_addresses`, `wallet_pnl_summary`. See [Connectors](/mcp/connectors.md). The other 38 tools are only available here.
{% endhint %}

> **Protocol:** JSON-RPC 2.0 over Streamable HTTP (SSE)\
> **Endpoint:** `https://mcp.nansen.ai/ra/mcp`\
> **Auth:** `NANSEN-API-KEY` header\
> **Required header:** `Accept: application/json, text/event-stream`

### How credits work

Tools call the [Nansen API](/api/overview.md) with your API key, so each call is billed at the same [credit rates](/getting-started/credits.md) as the endpoint it uses.

* **Per API request.** Most tools make one request. Some make more, depending on their arguments. The table notes which ones.
* **Successful requests only.** Each successful underlying API request is charged, and failed requests are not. A tool call that fails can still cost credits for requests that succeeded before the failure. Listing tools is free.
* **Premium labels.** Four tools return Nansen's premium wallet labels: `token_current_top_holders`, `token_pnl_leaderboard`, `hyperliquid_leaderboard`, and `wallet_pnl_for_token` on Hyperliquid. They cost 150 credits per call and need a paid plan. On a Free key they return a plan upgrade error.
* **Address lookups.** `general_search` is free for tokens and entities. Labeling an address, or resolving an `.eth` or `.sol` name, costs 500 credits.
* **Token name lookup.** `token_current_top_holders`, `token_flows`, `token_pnl_leaderboard`, `token_ohlcv`, and `token_recent_flows_summary` look up the token's name before the main call. That lookup is free for most tokens. For a token missing from Nansen's search index, it can cost an extra 500 credits.

Check what your calls cost at [Nansen API usage](https://app.nansen.ai/api?tab=usage-analytics).

### Quick reference

Credits are per tool call. **Connector** marks the tools that are also in the [curated set](/mcp/connectors.md#curated-tools).

#### Search

| Tool                 | Description                                                                              | Credits                         | Connector |
| -------------------- | ---------------------------------------------------------------------------------------- | ------------------------------- | --------- |
| `general_search`     | Find tokens, entities, and wallets. Label an address or resolve an `.eth` or `.sol` name | 0; 500 for an address or domain | ✓         |
| `entity_name_search` | Get exact entity names from a partial name                                               | 0                               |           |
| `token_sectors`      | List valid sectors for the token screener                                                | 0 (1 on Free)                   |           |

#### Smart Money

| Tool                                                | Description                                                 | Credits | Connector |
| --------------------------------------------------- | ----------------------------------------------------------- | ------- | --------- |
| `smart_traders_and_funds_token_balances`            | Aggregated Smart Money token holdings and 24h change        | 5       | ✓         |
| `smart_traders_and_funds_historical_token_balances` | Day-by-day history of Smart Money holdings                  | 1       |           |
| `smart_traders_and_funds_netflow`                   | Smart Money net USD flow per token over 1h, 24h, 7d, or 30d | 5       |           |
| `smart_traders_and_funds_dex_trades`                | DEX trades by individual Smart Money wallets                | 5       |           |
| `smart_traders_and_funds_perp_trades`               | Smart Money perpetual trades on Hyperliquid                 | 5       |           |
| `smart_traders_and_funds_dcas`                      | Smart Money Jupiter DCA orders (Solana)                     | 5       |           |
| `smart_traders_and_funds_pnl_leaderboard`           | Smart Money wallets ranked by PnL                           | 5       |           |

#### Tokens

| Tool                         | Description                                                                            | Credits                                       | Connector |
| ---------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------- | --------- |
| `token_info`                 | Token metadata, market data, supply, liquidity, and holders, or Hyperliquid perp stats | 1                                             | ✓         |
| `token_ohlcv`                | OHLCV price candles with an automatic interval                                         | 1                                             | ✓         |
| `token_technical_indicators` | SMA, EMA, RSI, MACD, Bollinger Bands, ATR, and VWAP                                    | 1                                             |           |
| `token_quant_scores`         | Nansen quantitative risk and reward indicators                                         | 5                                             | ✓         |
| `nansen_score_top_tokens`    | Daily top tokens by Nansen Score                                                       | 1                                             |           |
| `token_discovery_screener`   | Screen spot tokens and Hyperliquid perps across chains                                 | 1; 2 when mixing spot chains with Hyperliquid | ✓         |
| `token_recent_flows_summary` | Recent flows by segment: Smart Money, whales, exchanges, fresh wallets                 | 1                                             | ✓         |
| `token_flows`                | Hourly flows for one holder segment                                                    | 1                                             |           |
| `token_who_bought_sold`      | Wallets that bought or sold a token on DEXs, with labels                               | 1                                             | ✓         |
| `token_dex_trades`           | DEX trades for a token, or perp trades for a Hyperliquid symbol                        | 1                                             |           |
| `token_transfers`            | Token transfer history (not native coins)                                              | 1                                             |           |
| `token_current_top_holders`  | Top holders with premium labels, or Hyperliquid perp positions                         | 150; 5 for perps                              |           |
| `token_pnl_leaderboard`      | Trader PnL leaderboard for a token or perp, with premium labels                        | 150                                           |           |
| `token_jup_dca`              | Jupiter DCA orders for a Solana token                                                  | 1                                             |           |

#### Wallets and entities

| Tool                           | Description                                                                        | Credits                                                      | Connector |
| ------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------ | --------- |
| `address_portfolio`            | Token balances, DeFi positions, and Hyperliquid positions, or an entity's holdings | 1; 2 for a wallet with mode `all`; 0 with mode `hyperliquid` | ✓         |
| `address_historical_balances`  | Historical token and native coin balances                                          | 1                                                            |           |
| `address_transactions`         | The 20 most recent transactions                                                    | 1                                                            |           |
| `address_dex_trades`           | A wallet's DEX swaps or Hyperliquid perp trades                                    | 1                                                            |           |
| `address_labels`               | Standard Nansen labels for an address                                              | 100                                                          |           |
| `address_counterparties`       | Top counterparties by transfer volume                                              | 5                                                            | ✓         |
| `address_counterparties_batch` | Counterparties for up to 10 wallets in one call                                    | 5                                                            |           |
| `address_related_addresses`    | First funders, signers, deployers, and created contracts                           | 1 per chain; with chain `all`, 1 plus 1 per active chain     | ✓         |
| `address_first_funder`         | The first funder of an EVM wallet                                                  | 1                                                            |           |
| `address_perp_positions`       | Open Hyperliquid positions and liquidation risk                                    | 1                                                            |           |
| `wallet_pnl_summary`           | Realized PnL, plus Hyperliquid unrealized PnL                                      | 1 per chain; 2 for an EVM address with the default chain     | ✓         |
| `wallet_pnl_for_token`         | A wallet's PnL for one token                                                       | 1; 150 on Hyperliquid                                        |           |

#### Chains and transactions

| Tool                      | Description                                        | Credits | Connector |
| ------------------------- | -------------------------------------------------- | ------- | --------- |
| `growth_chain_rank`       | Chain rankings by growth metrics                   | 1       |           |
| `transaction_lookup`      | Transaction details with token transfers (EVM)     | 1       |           |
| `hyperliquid_leaderboard` | Hyperliquid trader leaderboard with premium labels | 150     |           |

#### Prediction markets

| Tool                                | Description                                              | Credits | Connector |
| ----------------------------------- | -------------------------------------------------------- | ------- | --------- |
| `prediction_market_lookup`          | Find Polymarket events and markets by name, slug, or URL | 0       |           |
| `prediction_market_screener`        | Browse markets, events, and categories                   | 1       |           |
| `prediction_market_ohlcv`           | Odds and volume candles for a market                     | 1       |           |
| `prediction_market_orderbook`       | Live orderbook for a market                              | 1       |           |
| `prediction_market_trades`          | Recent trades in a market                                | 1       |           |
| `prediction_market_top_holders`     | Largest holders of a market                              | 5       |           |
| `prediction_market_pnl_leaderboard` | PnL leaderboard for a market                             | 5       |           |
| `prediction_market_position_detail` | Position breakdown for a market                          | 5       |           |
| `prediction_market_address_trades`  | Trades by a Polymarket wallet                            | 1       |           |
| `prediction_market_address_summary` | Summary of a Polymarket wallet                           | 1       |           |
| `prediction_market_address_pnl`     | A Polymarket wallet's PnL by market                      | 1       |           |

### Common gotchas

1. **Argument wrapping.** Most tools take their arguments inside `{"request": {...}}`. Four take flat arguments: `general_search`, `entity_name_search`, `transaction_lookup`, and `token_sectors` (no arguments).
2. **Wallet fields.** Most wallet tools take a single `address`. `address_portfolio`, `wallet_pnl_summary`, and `wallet_pnl_for_token` take `walletAddress`. Only `address_counterparties_batch` takes an array, `walletAddresses`, with up to 10 addresses.
3. **Date ranges.** Ranges are objects: `{"from": "...", "to": "..."}`. Values can be `YYYY-MM-DD` or relative tokens such as `NOW`, `7D_AGO`, `12H_AGO`, and `30MIN_AGO`, on every tool. The field name varies by tool (`dateRange`, `date`, `timeRange`), so check the tool's input schema.
4. **Case-sensitive enums.** Trade direction is `"BUY"` or `"SELL"`, not lowercase.
5. **Chains.** Defaults differ by tool, so check the input schema. Pass a specific chain when you know it.
   * **Chain required:** `token_transfers`, `token_who_bought_sold`, `token_ohlcv`, and `token_technical_indicators`.
   * **One concrete chain required:** `address_dex_trades`. It rejects a missing chain, `all`, and `evm`. Use a chain such as `ethereum`.
   * **Default `ethereum`:** the other single-token tools, such as `token_info` and `token_recent_flows_summary`.
   * **Default `ethereum`, `solana`, `bnb`, and `base`:** `token_discovery_screener`.
   * **Default `all` (every supported chain):** most wallet tools. With `all`, `address_related_addresses` makes one billed request per active chain.
   * **Default `evm`:** `address_transactions`, `wallet_pnl_summary`, and `wallet_pnl_for_token`.
6. **Variable cost.** Check [How credits work](#how-credits-work) before calling `general_search` on addresses, or any of the premium-label tools.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nansen.ai/mcp/connecting/tools.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.