Nansen API offers programmatic access to high-quality onchain data and advanced blockchain analytics across numerous networks. The API aims to equip users with the necessary data to gain a competitive edge, identify opportunities, perform due diligence, and make informed decisions within the dynamic crypto market. It effectively translates the complexity of raw blockchain data into actionable intelligence, accessible through a structured API interface.

Key Capabilities

• Proprietary Data Labeling: Nansen applies unique, human-readable labels to hundreds of millions of blockchain addresses. These labels identify specific entities such as exchanges, funds, market makers, notable individual investors that allows users to understand who is behind onchain activities, providing crucial context that raw, pseudonymous data lacks. Accessing this labelled data via the API is a core component of Nansen's offering.

• Unique Datasets and Insights: The API provides access to data points and analytics not readily available elsewhere, such as Smart Money analytics.

• Comprehensive Multi-Chain Coverage: The API consolidates data from multiple blockchain networks, allowing users to track assets and activities across different ecosystems through a single integration point.

These features collectively enable the API to deliver not just data, but contextualized intelligence, transforming raw onchain events into a clearer picture of market dynamics and participant behavior.

Jump right in

The Nansen API employs rate limits and usage quotas to ensure fair usage and maintain performance for all users.

Professional Tier Rate Limits:

This tier provides access to all APIs with near real-time data. The current rate limits are 20 requests per second and 500 requests per minute. Monthly quotas will also apply. Details regarding total credit numbers and credit consumption per API call will be released separately.

Exceeding Rate Limits:

If you exceed the defined rate limits, the API will return an error response. You should expect a 429 Too Many Requests HTTP status code.

Usage Tips

Querying Transactions across all chains

You can also query balances across all chains using this

"chain": "all",

Usage Tips

Querying PnL across all chains

You can also query balances across all chains using this

"chain": "all",

Usage Tips

Querying Entity Balances

You can also pull balances for any labeled entity (e.g., Binance, Paradigm Fund) instead of raw wallet addresses.

• Provide exactly one of:

  • walletAddresses – array of addresses or

  • entityId – string name or UUID of the entity

• Leave the other field empty / omitted.

• All other parameters work exactly the same.

Example request of entity lookup

Querying Balances across all chains

You can also query balances across all chains using this

Using /flows Endpoint

The /flows endpoint allows you to analyze historical inflows and outflows of token holdings across specific wallet labels (e.g., Smart Money, Whales, Public Figures, etc.) on supported blockchains. This enables powerful workflows to investigate token accumulation or distribution trends by high-signal wallet groups over time.

This guide walks through how to use the endpoint in a workflow to explore Smart Money behavior for a given token on a given chain.

Usecase 1: Track Smart Money Accumulation Trends

This workflow helps you:

• Identify what tokens Smart Money is holding (e.g., via /holdings or /inflows)

• Investigate how inflows/outflows of Smart Money have evolved over time

• Combine historical activity with price trends for better decision-making

Step by Step Guide:

1. Start with /holdings endpoint to identify what tokens Smart Money is holding.

2. Pick a token of interest based on value and activity patterns.

3. Use the /flows endpoint with the token address and smart_money label to view inflow/outflow trends.

4. Specify timeframe (e.g., last 30 days) and examine how Smart Money behavior is evolving.

Usecase 2: Monitor Exchange Flows

This workflow helps you:

• Track how much of a token is being sent to or from exchange wallets

• Spot accumulation or distribution trends by observing net exchange flow

• Correlate token price movement with CEX behavior patterns

Step by Step Guide:

1. Identify the token of interest (e.g., USDC, ETH, SOL).

2. Choose the chain where it is active.

3. Use label: "exchange" to track exchange wallets.

4. Analyze net flows:

   • High inflow = Possible sell pressure

   • High outflow = Possible accumulation

5. Correlate flow data with price action or events (e.g., listings, unlocks, news).

Connect your AI tools (Eg. Claude, Cursor) using Anthropic's Model Context Protocol, a standard that lets AI tools interact with Nansen data.

What is Nansen MCP?

Nansen MCP is a Model Context Protocol (MCP) server that provides access to Nansen's institutional-grade blockchain intelligence platform. It transforms Nansen's onchain intelligence into an accessible interface that AI agents, developers, and researchers can use to analyze crypto markets and blockchain activity.

Core Offering

• MCP Protocol: Built on the standardized Model Context Protocol, ensuring compatibility with AI tools like Claude, Cursor, and other MCP-compatible clients

• Multi-Chain Coverage: Supports 25+ major blockchains including Ethereum, Solana, Bitcoin, Arbitrum, Base, Polygon, and more

• Real-Time Data: Provides access to live blockchain data including transactions, token movements, wallet activities, dex trades and PnL

Why Use Nansen MCP?

AI tools currently have no visibility into what's happening onchain. Even answering simple blockchain queries is extremely difficult without proper data access and context. Nansen MCP gives AI tools the ability to see and understand onchain activities, transforming them into powerful blockchain research assistants.

1. Real-Time Access to Nansen's Rich Data

• Access to Nansen's proprietary wallet labeling system with millions of identified addresses including smart money labels

• Institutional-grade data accuracy and reliability

• Real-time processing of onchain activities across multiple blockchains

2. AI-Native Integration

• One-click installation with Claude Desktop

• No need to struggle with complex APIs or documentation - everything works out of the box

• Build custom AI agents and LLMs with blockchain intelligence

3. Streamlined Research Workflows

• Saves time by wrapping complex workflows into simpler tasks

• Automate onchain research that would take hours manually

• Generate insights from multiple data sources simultaneously

What Can You Do with Nansen MCP?

Smart Money Tracking

Track DEX trades, token holdings, and portfolio changes of profitable traders and funds. Discover tokens gaining traction among smart money before broader market adoption.

Token Intelligence & Discovery

Screen thousands of tokens across multiple chains using advanced filters. Analyze real-time trading data, holder distributions, and exchange flows to identify opportunities.

Address & Entity Profiling

Deep dive into wallet activities, trading patterns, and PnL analysis. Map relationships between wallets and identify connected addresses across all supported blockchains.

Example Prompts

• "Show me all tokens that funds bought in the last 24 hours"

• "What DCA strategies are profitable traders using on Jupiter?"

• "Find new tokens with high smart money inflows and growing trading volume"

• "Show me trending tokens with liquidity above $100k"

• "Analyze the trading performance of this whale address"

• "Find wallets connected to this successful trader"

• "Track how this fund's portfolio allocation has changed over time"

• "Do a deep dive into this wallet to find whom does it belong to"

The Nansen MCP server provides AI assistants with access to comprehensive blockchain analytics through a secure API. This guide covers how to connect to Nansen MCP.

Prerequisites

Before connecting, you'll need:

1. Nansen API Key: Get yours at app.nansen.ai/account?tab=api

2. npx: Required for remote connections (npm install -g npx)

Connection Methods

1. Claude Desktop (One-Click Install; Claude Desktop Required)

The easiest way to get started with Nansen MCP. Double-click the downloaded .dxt file to configure automatically.

Quick Install Link

2. Claude Code (Terminal Integration)

Connect Nansen MCP through your terminal:

claude mcp add --transport http nansen <https://mcp.nansen.ai/ra/mcp/> --header "NANSEN-API-KEY: YOUR_API_KEY_HERE"

3. Other MCP Clients

Integration example for various other tools supporting MCPs

Server configuration:

• Server: https://mcp.nansen.ai/ra/mcp/

• Header: NANSEN-API-KEY: your_api_key

• Transport: mcp-remote --allow-http

{
  "mcpServers": {
    "nansen-mcp": {
      "env": {
        "NANSEN_API_KEY": "your_api_key"
      },
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<https://mcp.nansen.ai/ra/mcp/>",
        "--header",
        "NANSEN-API-KEY:${NANSEN_API_KEY}",
        "--allow-http"
      ]
    }
  }
}

NPX example:

npx -y mcp-remote <https://mcp.nansen.ai/ra/mcp/> \\
  --header "NANSEN-API-KEY:YOUR_API_KEY_HERE" \\
  --allow-http

Authentication

⚠️ Nansen MCP uses the same API as your regular API keys. Ensure you have sufficient credits for your usage.

All interactions with the Nansen API occur via HTTPS requests to specific endpoints. The general structure of an API call is:

HTTP Method + Base URL + Endpoint Path

• HTTP Method: Primarily POST for retrieving data.

• Base URL: The root URL for all API requests is:

  Copy

  https://api.nansen.ai/api/beta

• Endpoint Path: The specific path identifying the resource and desired data, appended directly to the Base URL (e.g., /smart-money/inflows). Endpoint paths for specific resources are detailed within their respective sections of this documentation.

• Request Body: Parameters are typically passed in JSON format within the request body for POST requests. For example:

  Copy

  {
    "parameters": {
      "smFilter": ["180D Smart Trader", "Fund", "Smart Trader"],
      "chains": ["ethereum", "solana"],
      "includeStablecoin": true,
      "includeNativeTokens": true,
      "excludeSmFilter": []
    }
  }
  

A curated list of the top 5 000 highest-performing wallets ranked by realised profit, winrate, and strong performance across market cycles. Available Smart Money labels:

• 30D Smart Trader

• 90D Smart Trader

• 180D Smart Trader

• Fund

• Smart Trader

Usage Tips

• To query smart money activity across all chains, simply use

  Copy

  "chains": []

• To query smart money activity across multiple chains, specify the chains in the array

  Copy

    "chains": [
              "solana",
              "base"
          ],

• You can also use filters to only query smart money data for tokens of interest by adding these filters:

  Copy

     "filters": {
          "symbol": [
              "FARTCOIN",
              "USELESS"
          ]
      },
  
  or 
  
      "filters": {
          "tokenAddress": [
              "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump"
          ]
      },

• You can also filter responses based on token age or sectors

  Copy

     "filters": {
          "tokenAgeDays": {
              "from": 0,
              "to": 30
          },
          "sectors": [
              "GameFi"
          ]
      },

To optimize queries on the /tgm/jup-dca endpoint and avoid timeouts, use targeted filters rather than broad searches. Apply these strategies:

1. Set ‎⁠sinceTimestamp⁠ and ‎⁠lastTimestamp⁠ to limit results to a specific period.

2. Filter by ‎⁠traderAddress⁠ to focus on individual users.

3. Use thresholds like ‎⁠depositUsdValue⁠to target significant orders.

4. Filter by ‎⁠status⁠ to separate active from closed orders.

Combining these filters reduces data volume, speeds up queries, and improves reliability.

How to use the Holders Endpoint

The Holders Endpoint returns holder data for a given token on a specific chain over a defined date range. You can use this to analyze who is holding a particular token—whether it’s Smart Money wallets, exchanges, or all holders.

Usecase 1: Get list of Smart Money Holders

1. Set "label" to "smart_money" in the parameters object.

2. Add "includeLabels" as an array with the specific Smart Money segments you want (e.g., "Fund", "30D Smart Trader").

3. Other parameters (like chain, tokenAddress, date range, etc.) stay the same.

Example Configuration:

"label": "smart_money",
"includeLabels": ["Fund", "30D Smart Trader"]
"isEntity": true, -- To aggregate by Entity

Usecase 2: List of Exchanges Holding a Token

1. Set "label" to "exchange" in the parameters object.

2. Add "includeLabels" with "Exchange"

3. Other parameters remain unchanged.

Example Configuration:

"label": "exchange",
"includeLabels": ["Exchange"]
"isEntity": true, -- To aggregate by Entity

Usage Tips

Querying Counterparties across all chains

You can also query balances across all chains using this

Querying Entity Counterparties

You can also pull counterparties for any labelled entity (eg. Binance, Alex Svanevik, Paradigm Fund) instead of raw addresses.

• Provide exactly one of:

  • walletAddresses – array of addresses or

  • entityId – string name of the entity

• Leave the other field empty / omitted.

• All other parameters behave the same.

Example request — entity lookup

Performance Tips

To ensure optimal performance when using the counterparties API:

• Limit the number of chains included in a single request. We recommend querying one chain at a time.

• Use a shorter `look-back` window, such as 1 month, for faster response times.

• Avoid querying very large timeframes.

The Nansen API uses API key-based authentication. All requests must include an API key provided in the request header for successful authentication.

Obtaining API Keys

You can access the API Keys from in account settings

Including Your API Key in Requests

Add the following header to all API requests:

Replace YOUR_API_KEY with your actual API key.

Example API Request

cURL Example:

To help you plan your usage, here’s a clear overview of how our API credit system works. We’ve designed our pricing to be simple and scale with your needs, ensuring you only pay for the value you receive.

Available API Plans

We offer two main API plans to fit your needs:

For more information on plan features, visit our pricing page.

Endpoint Credit Cost

Credit costs are structured to reflect the value of the data you’re accessing. Foundational data is inexpensive to encourage frequent use, while our proprietary, alpha-generating data costs more.

Free Endpoints (0 Credits per call)*

• profiler/address/balances

• profiler/address/historical-balances

• profiler/address/transactions

• tgm/transfers

• tgm/dcas

*Endpoints marked as free do not count towards your credit usage as part of the Professional Plan.

Standard Endpoints (1 Credit per call)

• profiler/address/related-wallets

• profiler/pnl-summary

• profiler/pnl

• tgm/flow-intel

• tgm/who-bought-sold

• tgm/dex-trades

• tgm/flows

Premium Endpoints (5 Credits per call)

• All Smart Money endpoints (/inflows, /holdings, /dex-trades, etc.)

• profiler/address/counterparties

• tgm/holders

• tgm/pnl-leaderboard

Label Endpoints (Coming Soon)

• Behavioural Labels: 25 credits per call

• Entity Labels: 500 credits per call

Managing Your Credits

What happens if I run out of credits?

You can purchase additional credit blocks at any time to ensure your service is not interrupted. Please reach out to our team incase you're interested.

Are there higher tiers or enterprise plans?

The Professional plan is designed to meet most needs. However, if you are a large-scale enterprise or have a unique integration that may require a significant volume of credits, please reach out to our sales team to discuss a custom solution.

How do I track my credit usage?

You can track your credit usage by visiting this link: https://app.nansen.ai/account?tab=api

Prerequisites for Using the Nansen API

Before integrating with the Nansen API, ensure the following requirements are met:

• Nansen API Access: You need an active subscription to either the Pioneer plan (which includes 1,000 one-time credits for testing) or the Professional plan with API access.

• API Key: Log in to your Nansen account to obtain your personal API key from the dashboard.

• HTTPS Client: Be familiar with making HTTPS requests using tools like curl, or libraries like requests in Python, or axios/fetch in Node.js.

• Development Environment: Set up a suitable environment for writing and executing code to interact with APIs.

Sample Request: Smart Money Inflows Endpoint

HTTPS Request

POST /api/beta/smart-money/inflows HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*

{
  "parameters": {
    "smFilter": [
      "180D Smart Trader",
      "Fund",
      "Smart Trader"
    ],
    "chains": [
      "ethereum",
      "solana"
    ],
    "includeStablecoin": true,
    "includeNativeTokens": true,
    "excludeSmFilter": []
  }
}

cURL Example

curl -L \
  --request POST \
  --url 'https://api.nansen.ai/api/beta/smart-money/inflows' \
  --header 'apiKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "parameters": {
      "smFilter": [
        "180D Smart Trader",
        "Fund",
        "Smart Trader"
      ],
      "chains": [
        "ethereum",
        "solana"
      ],
      "includeStablecoin": true,
      "includeNativeTokens": true,
      "excludeSmFilter": []
    }
  }'

Additional Notes

• Always refer to the official API documentation for parameter options and rate limit details.

• Ensure your API key remains confidential and is not shared in public repositories.

Authentication

Available Endpoints

API Rate Limits & Quotas

Data Coverage

Data Freshness and Performance

Developer Tools and Integration

API responses are delivered in JSON format. The client applications must parse this JSON to extract the required data. Equally important is handling the HTTP status code returned with each response to determine success or failure.

Common HTTP Status Codes:

Latency Expectations & Best Practices

As we continue to improve the performance of the Nansen API, here are some general guidelines to help you understand what to expect and how to get the best results:

What to Expect

• Most core endpoints (e.g. smart money, profiler) typically respond in under 2 seconds.

• Some heavier endpoints (especially under the TGM namespace) may take longer depending on the scope of the query.

• We’re actively working towards improving the performance of the API

Best Practices for Low Latency

To get faster and more reliable responses:

• Avoid overly broad queries. For example, don’t request balances for every address holding USDC across the entire chain.

• Use filters when available to narrow down time ranges, token lists, or entity types.

• Paginate where supported instead of trying to fetch large datasets in one go.

• Be mindful of rate limits, especially if calling multiple endpoints in parallel.

Below is the list of APIs currently available as part of the Nansen API. These endpoints closely mirror dashboards across Profiler, Smart Money, and Token God Mode, and have been grouped accordingly. To get a sense of what each endpoint delivers, you can review its documentation.

Because these endpoints are tightly coupled with live dashboards, they are subject to frequent updates. We refer to them as Fluid Endpoints. A more stable, static version of these APIs will be launched in the near future.

Smart Money

A curated list of the top 5 000 highest-performing wallets ranked by realised profit, winrate, and strong performance across market cycles.

Profiler

A toolkit for diving deep into address relationships and behaviour, letting you analyse any wallet or entity cluster to uncover flows, counterparties, and behavioural patterns.

Token God Mode

A comprehensive lens on a token’s on-chain activity, combining Smart Money movements, holder-base analysis, and exchange-flow tracking in one view.

Other Endpoints (Coming Soon)

Parameters & Filters Reference

The Token Screener API request body is composed of two key sections:

• parameters: Controls high-level configuration of the query — e.g., which chains to query, Smart Money toggles, date ranges, and label/scope filters. (Must Haves)

• filters: Defines numeric or categorical constraints for token-level metrics — e.g., liquidity, age, volume, holders, etc.

These work together to define your screening logic.

📌 Parameters

• All parameters in the API request are mandatory.

• If any parameter is missing or incorrectly formatted, the API will return an error and not process the request.

• You can leave parameters empty (e.g., use empty arrays), but you must still include them in the request payload.

🧮 Filters

Filters determine which tokens are returned based on their individual characteristics. You can apply multiple filters at once. All filters are optional. We support two types of filters:

• Categorical (Array of strings): To be used as ["0xab","0xbc"]

• Numeric (from, to): To be used as {"from": "2", "to": "5"}

Please note all filters must be placed in a separate filters section (see example below).

Sorting

This endpoint supports sorting. You can use it by adding the column name and order (desc/asc):

Example

Get the most liquid tokens under 7 days old on Ethereum and Base

Explore the suite of tools available through Nansen MCP. Each tool is purpose-built to deliver actionable blockchain insights, from tracking smart money movements to analyzing token flows and wallet activities.

At Nansen, our goal is to empower developers by providing access to the richest on-chain data. We encourage you to build on top of our API, and these guidelines will help you understand how to use and share Nansen's data in your products while protecting the unique value of our insights.

All use of the Nansen API is subject to these guidelines and our official Terms of Service.

Endpoint Redistribution Status

The table below outlines the redistribution status for our API endpoints. Please review the subsequent sections for a detailed explanation of what each status means and the rules you are required to follow.

Use cases designated as ⚠️ Restricted By-Default require additional approval process. Please contact our team in order to access them.

We require specific attribution for our Transactions, DEX Trades, and Transfers endpoints. This is because these endpoints provide more than just standard onchain data; they are enhanced with Nansen's unique labels and insights, which require proper acknowledgement.

Attribution Requirements

To use the Nansen API, attribution is required for all public or commercial applications. You can fulfill this by:

• Including a backlink to Nansen.ai

• Displaying "Powered by Nansen API" within your application

Attribution is not required for personal or private use cases.

This guide explains exactly what you must do to start building with the Nansen API inside Cursor. Follow the four steps below in order and you will have a working, AI‑powered development environment in minutes.

Simply copy this prompt and paste it in Cursor to start vibecoding with Nansen API:

https://docs.nansen.ai/guides/vibecoding-with-nansen-api.md 
Setup Nansen API in my project following the steps mentioned in this link

You need to:
1. Create a .env file
2. Generate cursorrules
3. Ingest API Docs

1 · Create your .env file

1. Generate an API key in the Nansen dashboard. Go to https://app.nansen.ai/account?tab=api, click Generate key, and copy the value.

2. Add the key and base URL to an .env file in the root of your project. Use the template below and replace your_api_key_here with the key you just copied.

# ---------- Nansen API ----------
apiKey=your_api_key_here
NANSEN_BASE_URL=https://api.nansen.ai/api/beta

# ---------- Optional : Rate‑limit + retry settings ----------
MAX_REQUESTS_PER_SECOND=20
MAX_REQUESTS_PER_MINUTE=500
RETRY_ATTEMPTS=3
TIMEOUT_MS=30000

2 · Tell Cursor what you are building

1. Create a file called .cursorrules in the project root.

2. Paste the short ruleset below. It contains the base URL, header format, and rate‑limit policy so Cursor can generate compliant code automatically.

# Nansen API Configuration for Cursor

## Core Settings
BASE_URL: https://api.nansen.ai/api/beta
AUTH_HEADER: apiKey
RATE_LIMIT: 20req/s, 500req/min

## Authentication & Security
API_KEY_SOURCE: The API key is ALWAYS stored in the .env file as 'apiKey'
- NEVER ask users for API keys
- ALWAYS fetch the API key from the .env file
- Use `apiKey` variable from .env for all API calls
- Read the key value from .env for runtime execution

## Rate Limiting & Performance
- Implement exponential backoff for rate limit errors
- Cache frequently requested data when appropriate
- Monitor and log API usage patterns

# Token Analysis Automation

## Address Discovery Rules
TOKEN_ADDRESS_SEARCH: When a token symbol is mentioned without an address, automatically search the internet for the token's contract address on the relevant blockchain.

### Search Triggers:
- User mentions token symbol without providing contract address
- User asks to "monitor [TOKEN]" or "analyze [TOKEN]" without address
- When implementing new token analysis features

### Search Patterns:
Use search queries like: "TOKEN_SYMBOL contract address blockchain_name" or "TOKEN_SYMBOL token address solscan etherscan"

### Search Sources Priority:
1. Solscan.io for Solana tokens
2. Etherscan.io for Ethereum tokens  
3. CoinGecko for multi-chain token information
4. DexScreener for DEX-traded tokens
5. Official project documentation/websites

## Default Parameters
DEFAULT_CHAINS: ethereum, solana
DEFAULT_TIMEFRAMES: 1d, 7d, 30d
DEFAULT_PAGINATION: 50 records per page
DEFAULT_SM_FILTERS: "180D Smart Trader", "Fund", "Smart Trader"

# API Interaction Standards

## Endpoint Compliance
ENDPOINT_RESTRICTION: ONLY use endpoints documented in the official Nansen API documentation
- Do NOT use undocumented endpoints
- Do NOT guess API paths or parameters
- Reference the official Nansen API documentation for all calls
- Validate endpoint availability before execution

## Parameter Validation Process
Before executing ANY API call:
1. Review API documentation to identify ALL required parameters
2. Cross-check user's request against documented required parameters
3. If ANY required parameter is missing, ask user to confirm/provide it
4. List all required parameters needing confirmation with descriptions
5. Do NOT make assumptions about missing required parameters
6. Do NOT provide default values for required parameters without user confirmation
7. Only execute after ALL required parameters are explicitly confirmed
8. Validate parameter types and formats against API documentation

## Error Handling
- API_ERROR_400: Validate all parameters and suggest corrections
- API_ERROR_429: Implement retry logic with backoff
- API_ERROR_500: Log error details and suggest alternative approaches
- INVALID_RESPONSE: Debug API call and suggest fixes
- Provide clear error messages with suggested solutions

## Response Formatting
- Present data in structured, readable formats
- Use tables for comparative data
- Highlight key metrics and insights
- Include data source timestamps
- Provide context for numerical values

# User Experience

## Command Execution Preferences
When users request API calls, intelligently choose between:
- **Simple cURL command**: For immediate, one-time execution
- **Python/JavaScript script**: For complex logic, reusable automation, or multi-step processes

### Decision Criteria:
- Single API call with simple parameters → cURL
- Multiple API calls or data processing → Script
- User explicitly requests specific format → Honor request
- Complex filtering/analysis required → Script

## Output Standards
- Always include execution instructions
- Include error handling guidance
- Show expected response formats
- Offer both technical and business interpretations

## Debugging Support
- Log API request/response details when errors occur
- Provide troubleshooting steps for common issues
- Include relevant documentation links
- Suggest parameter alternatives when validation fails

# Automation Intelligence

## Smart Actions
- NEW_TOKEN_ANALYSIS: Automatically look up token info and recent news
- MISSING_DATA: Suggest alternative data sources or timeframes
- PERFORMANCE_OPTIMIZATION: Recommend caching strategies for repeated queries
- TREND_ANALYSIS: Automatically identify and highlight significant patterns

## Quality Assurance
- Verify data consistency across multiple timeframes
- Cross-reference critical metrics with alternative sources
- Flag unusual patterns or potential data anomalies
- Provide confidence indicators for automated insights 

1. Save the file and reopen Cursor. The agent now has enough context to scaffold a working client when you ask for code.

3 · Ingest the Nansen docs with api-reference-md

1. Go to Cursor Settings -> Indexing & Docs

2. Click on Add Docs and use the URL below to index API Docs

https://docs.nansen.ai/nansen-api-reference.md

4 · Example prompts to give Cursor

Feel free to iterate: start with one prompt, review the generated code, and then ask Cursor to extend or refactor it. Because it already knows about your .env, .cursorrules, and API Docs, you can focus exclusively on describing what the tool should do next.

Not all endpoints are available across all chains. Below is the list of chains that are supported across different endpoints.

Please note we're always expanding the chain support at Nansen. If the chain you are interested in is missing, please reach out to us.

This document provides detailed technical specifications for all Nansen API endpoints, including request formats, response schemas, and usage examples.

Base Configuration

Base URL: https://api.nansen.ai/api/beta Authentication: API Key in header: apiKey: YOUR_API_KEY Rate Limits: 20 requests/second, 500 requests/minute Content-Type: application/json

Smart Money API Endpoints

Overview

The Smart Money API provides insights into trading activity from sophisticated traders and funds. These endpoints focus on addresses labeled as Smart Traders (30D, 90D, 180D, and all-time performers) and Funds, explicitly excluding whales, influencers, and other large holder categories.

Important Notes:

• TON and TRON have limited smart money support and may not work with these endpoints

• All endpoints focus on Smart Trader and Fund labels only

• Default filters: ["180D Smart Trader", "Fund", "Smart Trader"]

1. Smart Traders and Funds Token Balances (Aggregated)

Endpoint: POST /smart-money/holdings Credit Cost: 5 credits per call Description: Get aggregated smart trader and fund token balances with 24h change per chain

Request Parameters:

{
  "parameters": {
    "chains": ["ethereum", "solana"],
    "smFilter": ["180D Smart Trader", "Fund", "Smart Trader"],
    "includeStablecoin": true,
    "includeNativeTokens": true,
    "excludeSmFilter": []
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Args:

• chains: List of blockchains to query (defaults to all smart money chains when not specified)

• smFilter: Smart money filter (default: ["180D Smart Trader", "Fund", "Smart Trader"])

• includeStablecoin: Whether to include stablecoins (default: true)

• includeNativeTokens: Whether to include native tokens (default: true)

• excludeSmFilter: Smart money filters to exclude (default: [])

• page: Page number for pagination (default: 1)

• recordsPerPage: Number of results per page (default: 100)

Response Schema:

[
  {
    "chain": "ethereum",
    "tokenAddress": "0x...",
    "symbol": "USDC",
    "sectors": ["DeFi"],
    "balanceUsd": 12500000,
    "balancePctChange24H": 2.5,
    "nofHolders": "1250",
    "shareOfHoldings": 8.7,
    "tokenAgeDays": "1200",
    "marketCap": 32000000000
  }
]

2. Smart Traders and Funds DEX Trade Transactions

Endpoint: POST /smart-money/dex-trades Credit Cost: 5 credits per call Description: Get individual smart trader and fund DEX trade transactions in the last 24 hours

Request Parameters:

{
  "parameters": {
    "chains": ["ethereum", "solana"],
    "smFilter": ["180D Smart Trader", "Fund", "Smart Trader"],
    "excludeSmFilter": []
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Args:

• chains: List of blockchains to query (defaults to all smart money chains when not specified)

• smFilter: Smart money filter (default: ["180D Smart Trader", "Fund", "Smart Trader"])

• excludeSmFilter: Smart money filters to exclude (default: [])

• page: Page number for pagination (default: 1)

• recordsPerPage: Number of results per page (default: 100)

Response Schema:

[
  {
    "chain": "ethereum",
    "timestamp": "2024-01-15T14:30:00Z",
    "txHash": "0x...",
    "address": "0x...",
    "name": "Smart Trader #1234",
    "tokenBoughtAddress": "0x...",
    "tokenBoughtSymbol": "LINK",
    "tokenBoughtAmount": 1000.50,
    "tokenBoughtAgeDays": "2100",
    "tokenBoughtMarketCap": 8500000000,
    "tokenSoldAddress": "0x...",
    "tokenSoldSymbol": "USDC",
    "tokenSoldAmount": 1500.25,
    "tokenSoldAgeDays": "1200",
    "tokenSoldMarketCap": 32000000000,
    "valueInUsd": 15000.75
  }
]

3. Smart Traders and Funds Net Flows (Aggregated)

Endpoint: POST /smart-money/inflows Credit Cost: 5 credits per call Description: Get aggregated smart trader and fund net flows for the last 1, 7, and 30 days

Request Parameters:

{
  "parameters": {
    "chains": ["ethereum", "solana"],
    "smFilter": ["180D Smart Trader", "Fund", "Smart Trader"],
    "includeStablecoin": true,
    "includeNativeTokens": true,
    "excludeSmFilter": []
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Args:

• chains: List of blockchains to query (defaults to all smart money chains when not specified)

• smFilter: Smart money filter (default: ["180D Smart Trader", "Fund", "Smart Trader"])

• includeStablecoin: Whether to include stablecoins (default: true)

• includeNativeTokens: Whether to include native tokens (default: true)

• excludesmfilter: Smart money filters to exclude (default: [])

• page: Page number for pagination (default: 1)

• recordsperpage: Number of results per page (default: 100)

Response Schema:

[
  {
    "chain": "ethereum",
    "tokenAddress": "0x...",
    "symbol": "USDC",
    "sectors": ["DeFi"],
    "volume24hUSD": 1500000,
    "volume7dUSD": 8750000,
    "volume30dUSD": 35000000,
    "nofTraders": "245",
    "tokenAgeDays": "1200",
    "marketCap": 32000000000
  }
]

Note: Volume values represent net flows where:

• Positive values = net inflows (more buying than selling)

• Negative values = net outflows (more selling than buying)

4. Smart Traders and Funds DCAs (Solana)

Endpoint: POST /smart-money/dcas Credit Cost: 5 credits per call (PROHIBITED for redistribution) Description: Get Jupiter DCA orders created by Smart Trader and Fund addresses on Solana

Request Parameters:

{
  "parameters": {
    "chain": "solana",
    "smFilter": ["180D Smart Trader", "Fund", "Smart Trader"],
    "excludeSmFilter": [],
    "tokenAddress": "So11111111111111111111111111111111111111112"
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Args:

• chain: Blockchain to query (fixed as "solana")

• smfilter: Smart money filter (default: ["180D Smart Trader", "Fund", "Smart Trader"])

• excludesmfilter: Smart money filters to exclude (default: [])

• tokenaddress: Optional token address to filter by

• page: Page number for pagination (default: 1)

• recordsperpage: Number of results per page (default: 100)

Response Schema:

[
  {
    "sinceTimestamp": "2024-01-10T10:00:00Z",
    "lastTimestamp": "2024-01-15T14:30:00Z",
    "traderAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "traderLabel": "Smart Trader #567",
    "creationHash": "5xY3...",
    "dcaVaultAddress": "DCA1...",
    "inputMintAddress": "So11111111111111111111111111111111111111112",
    "outputMintAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "tokenInput": "SOL",
    "tokenOutput": "USDC",
    "depositUsdValue": 10000.00,
    "depositAmount": 100.5,
    "depositSpent": 75.25,
    "otherTokenRedeemed": 7525.50,
    "status": "active"
  }
]

Smart Money Labels

Available Smart Money filter options (only these labels are supported):

• "30D Smart Trader" - Top performers in last 30 days

• "90D Smart Trader" - Top performers in last 90 days

• "180D Smart Trader" - Top performers in last 180 days

• "Smart Trader" - All-time high-performing traders

• "Fund" - Institutional funds and investment entities

Excluded Categories: These endpoints do NOT include whales, influencers, large holders, or other non-smart-trader categories.

Chain Support for Smart Money

When chains parameter is not specified or set to ["all"], the following chains are queried:

Profiler API Endpoints

Overview

The Profiler API provides comprehensive wallet analysis tools for tracking balances, transactions, PnL, and relationships across multiple blockchains. All endpoints support the special chain: "all" parameter to query across all supported chains simultaneously (except where noted).

1. Address Balances

Endpoint: POST /profiler/address/balances Credit Cost: 0 credits (FREE) Description: Get current token balances for specified addresses

Request Parameters:

{
  "parameters": {
    "chain": "all",
    "walletAddresses": ["0x28c6c06298d514db089934071355e5743bf21d60"],
    "suspiciousFilter": "on"
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Args:

• walletAddresses: A single address to query (required, empty if you're adding entityId)

• entityId: Labeled entity name. Mutually exclusive with walletAddresses.

• chain: The blockchain to query (default: "all" - queries all chains)

• suspiciousFilter: "on" or "off" - whether to exclude suspicious tokens (default: None)

• page: Page number for pagination (default: 1)

• recordsPerPage: Number of results per page (default: 100)

Response Schema:

[
  {
    "chain": "ethereum",
    "tokenAddress": "0x...",
    "symbol": "USDC",
    "name": "USD Coin",
    "tokenAmount": 25000.50,
    "usdValue": 25000.50
  }
]

2. Address Historical Balances

Endpoint: POST /profiler/address/historical-balances Credit Cost: 0 credits (FREE) Description: Get historical token holdings over time

Request Parameters:

{
  "parameters": {
    "walletAddresses": ["0x28c6c06298d514db089934071355e5743bf21d60"],
    "chain": "all",
    "suspiciousFilter": "on",
    "timeFrame": 7
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Args:

• walletAddresses: A single address to query (required, empty if you're adding entityId)

• entityId: Labeled entity name. Mutually exclusive with walletAddresses.

• suspiciousFilter: "on" or "off" - whether to exclude suspicious tokens (default: "on")

• chain: The blockchain to query (default: "all" - queries all chains)

• timeFrame: Number of lookback days (1, 7, 30, 90, 120, 365) (default: 1)

• page: Page number for pagination (default: 1)

• recordsPerPage: Number of results per page (default: 100)

3. Address Transactions

Endpoint: POST /profiler/address/transactions Credit Cost: 0 credits (FREE, requires attribution) Description: Get complete transaction history with labels

Request Parameters:

{
  "parameters": {
    "chain": "all",
    "walletAddresses": ["0x28c6c06298d514db089934071355e5743bf21d60"],
    "hideSpamToken": true
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  },
  "filters": {
    "volumeUsd": {"from": 0.1},
    "blockTimestamp": {
      "from": "2025-05-13T00:00:00.000Z",
      "to": "2025-05-13T03:00:00.000Z"
    }
  }
}

Args:

• walletAddresses: A single address to query (required)

• chain: The blockchain to query (default: "all" - queries all chains)

• hideSpamToken: Removes suspicious tokens from transaction list (default: True)

• filters: Optional filters for the transaction query (default: None)

• page: Page number for pagination (default: 1)

• recordsPerPage: Number of results per page (default: 100)

Note: This endpoint requires a single address, not a list.

4. Address Counterparties

Endpoint: POST /profiler/address/counterparties Credit Cost: 5 credits per call (requires attribution) Description: Get addresses or entities with the most common interactions

Request Parameters:

{
  "parameters": {
    "walletAddresses": ["0x28c6c06298d514db089934071355e5743bf21d60"],
    "chain": "all",
    "sourceInput": "Combined",
    "groupBy": "wallet",
    "timeRange": {
      "from": "2025-05-01",
      "to": "2025-05-03"
    }
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Args:

• walletAddresses: A single address to query (required, empty if you're adding entityId)

• entityId: Labeled entity name. Mutually exclusive with walletAddresses.

• sourceInput: "Combined", "Tokens", or "ETH"

• groupBy: "wallet" or "entity"

• timeRange: Datetime in ISO format (requires {"from": "", "to":""})

• chain: The blockchain to query (default: "all" - queries all chains)

• page: Page number for pagination (default: 1)

• recordsPerPage: Number of results per page (default: 100)

Tips for Finding Related Wallets:

• Focus on direct value transfers to identify most likely related addresses

• Include CEX deposit addresses (NOT withdrawal addresses)

• Go one level deeper:

  • Find addresses that interacted with the most likely addresses

  • Find addresses that deposited to the same CEX deposit addresses

• Address structure/string patterns are not important - focus on the relationship

Response includes:

• Interacting addresses and labels

• USD volume in/out

• Number of transactions in/out

• Net flow (positive = inflow, negative = outflow)

5. Address Related Addresses

Endpoint: POST /profiler/address/related-wallets Credit Cost: 1 credit per call (requires attribution) Description: Get addresses with special connections (deployment, funding, multisig relationships)

Request Parameters:

{
  "parameters": {
    "chain": "ethereum",
    "walletAddresses": ["0x28c6c06298d514db089934071355e5743bf21d60"]
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Args:

• walletAddresses: List of addresses to query

• chain: The blockchain to query (default: "ethereum" - Note: "all" does NOT work here)

• page: Page number for pagination (default: 1)

• recordsPerPage: Number of results per page (default: 100)

Special Connections Include:

• First Funder

• Signer / Previous Signer

• Multisig Signer of / Previous Multisig Signer of

• Deployed via / Deployed by

• Deployed Contract / Created Contract / Created by

Note: For general related wallets, also check address counterparties.

6. Wallet PnL Summary

Endpoint: POST /profiler/address/pnl-summary Credit Cost: 1 credit per call Description: Get aggregate realized PnL statistics for a wallet

Request Parameters:

{
  "parameters": {
    "chain": "all",
    "walletAddress": "0x28c6c06298d514db089934071355e5743bf21d60",
    "date": {
      "from": "2025-05-01",
      "to": "2025-05-03"
    }
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Args:

• walletAddress: The wallet address to analyze

• date_from: Start datetime in ISO format (use as {"from": "", "to":""})

• date_to: End datetime in ISO format (use as {"from": "", "to":""})

• chain: The blockchain to query (default: "all" - queries all chains)

• page: Page number for pagination (default: 1)

• records_per_page: Number of results per page (default: 100)

7. Wallet PnL for Token

Endpoint: POST /profiler/address/pnl Credit Cost: 1 credit per call Description: Get detailed PnL statistics for a specific token traded by an address

Request Parameters:

{
  "parameters": {
    "chain": "ethereum",
    "date": {
      "from": "2025-05-01",
      "to": "2025-05-03"
    },
    "walletAddress": "0x28c6c06298d514db089934071355e5743bf21d60",
    "showRealized": true,
    "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Args:

• walletAddress: The wallet address to analyze

• tokenAddress: Token address to generate PnL stats for

• date_from: Start datetime in ISO format (use as {"from": "", "to":""})

• date_to: End datetime in ISO format (use as {"from": "", "to":""})

• showRealized: Include realized profit or not

• chain: The blockchain to query (default: "ethereum")

• page: Page number for pagination (default: 1)

• records_per_page: Number of results per page (default: 100)

Response includes:

• Token price and ROI (realized/unrealized)

• PnL in USD (realized/unrealized)

• Bought/sold amounts and USD values

• Cost basis and average sold price

• Current holdings

• Number of buy/sell transactions

• Maximum balance held

8. Address Transactions for Token

Endpoint: POST /profiler/address/wp4t-transactions Credit Cost: 0 credits (FREE) Description: Get token transfer details between a wallet and specific token

Request Parameters:

{
  "parameters": {
    "walletAddress": "0x28c6c06298d514db089934071355e5743bf21d60",
    "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "datetimeFrom": "2025-05-01T00:00:00.000Z",
    "datetimeTo": "2025-05-03T23:59:59.999Z",
    "timeRange": {
      "from": "2025-05-01",
      "to": "2025-05-03"
    },
    "chain": "ethereum"
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Args:

• walletAddress: The address to analyze

• tokenAddress: The token address to analyze

• datetimeFrom: Start datetime in ISO format

• datetimeTo: End datetime in ISO format

• chain: The blockchain to query (default: "ethereum")

• page: Page number for pagination (default: 1)

• records_per_page: Number of results per page (default: 100)

Chain Support Note

Most Profiler endpoints support chain: "all" to query across all supported chains simultaneously, which is the recommended default for comprehensive analysis. The only exception is the Related Addresses endpoint, which requires a specific chain to be specified.

Token God Mode API Endpoints

Overview

Token God Mode provides comprehensive token analytics and insights across multiple blockchain networks. These endpoints offer deep visibility into token metrics, trading activity, holder behavior, and smart money movements.

Performance Warning:

• Use ≤ 3 chains at a time to avoid timeouts

• Recommended chain triplets:

  1. ["ethereum", "solana", "bnb"]

  2. ["base", "arbitrum", "unichain"]

  3. ["hyperevm", "polygon", "avalanche"]

• Use shorter date ranges (1-3 days) for better performance

1. Token Screener

Endpoint: POST /token-screener Credit Cost: 5 credits per call Description: Comprehensive token discovery tool with advanced filtering capabilities

Request Structure:

{
  "parameters": {
    "chains": ["ethereum", "solana"],          // Required, max 3 chains
    "date": {                                  // Required ISO8601 format
      "from": "2025-05-01",
      "to": "2025-05-03"
    },
    "watchlistFilter": [],                     // Optional token addresses
    "sectorsFilter": [],                       // Optional sectors
    "smLabelFilter": [],                       // Optional smart money labels
    "onlySmartMoney": true                     // Required
  },
  "filters": {                                 // All optional
    "tokenAgeDays": {"from": 1, "to": 7},
    "liquidity": {"from": 100000, "to": 999999999},
    "priceChange": {"from": 0.05, "to": 1}
  },
  "order": {                                   // Optional
    "orderBy": "priceChange",
    "order": "desc"
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Available Filters:

• tokenAgeDays - Token age in days

• buyVolume - Total buy-side volume

• sellVolume - Total sell-side volume

• volume - Total trading volume

• liquidity - DEX liquidity (USD)

• marketCap - Market capitalization

• fdv - Fully Diluted Valuation

• netflow - Net inflow (buys - sells)

• holders - Number of token holders

• nofBuyers - Count of unique buyers

• nofSellers - Count of unique sellers

• nofTxs - Number of transactions

• nofTraders - Number of traders

• priceChange - Price change percentage

Example Use Cases:

// Find new tokens with smart trader activity
{
  "parameters": {
    "chains": ["ethereum", "solana", "bnb"],
    "date": {"from": "2025-01-01", "to": "2025-01-03"}, // Required ISO8601 format
    "onlySmartMoney": true
  },
  "filters": {
    "tokenAgeDays": {"from": 1, "to": 7}
  }
}

// Find pumping tokens (high price change)
{
  "parameters": {
    "chains": ["ethereum", "solana", "bnb"],
    "date": {"from": "2025-01-01", "to": "2025-01-03"}, // Required ISO8601 format
    "onlySmartMoney": false
  },
  "filters": {
    "liquidity": {"from": 100000, "to": 999999999},
    "priceChange": {"from": 0.05, "to": 1},
    "nofTraders": {"from": 1000, "to": 999999999}
  },
  "order": {
    "orderBy": "priceChange",
    "order": "desc"
  }
}

2. Token Holders

Endpoint: POST /tgm/holders Credit Cost: 5 credits per call (Restricted by default) Description: Analyze top holders with balance changes over time

Request Parameters:

{
  "parameters": {
    "chain": "ethereum",
    "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "date": {
      "from": "2025-05-01",          // Required ISO8601 format
      "to": "2025-05-03"            // Required ISO8601 format
    },
    "isEntity": false,
    "includeLabels": [],
    "label": "top_100_holders",
    "isStablecoin": false
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Holder Type Options:

• "top_100_holders" - General top holders (default)

• "smart_money" with includeLabels: ["Fund", "30D Smart Trader"]

• "exchange" with includeLabels: ["Exchange"]

Response includes:

• Current balance and USD value

• Ownership percentage

• 24h, 7d, 30d balance changes

• Total sent/received amounts

3. Token DEX Trades

Endpoint: POST /tgm/dex-trades Credit Cost: 1 credit per call (requires attribution) Description: Individual DEX trades with optional smart money filtering

Request Parameters:

{
  "parameters": {
    "chain": "ethereum",
    "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "onlySmartMoney": true,
    "date": {
      "from": "2025-05-01",       // Required ISO8601 format
      "to": "2025-05-03"          // Required ISO8601 format
    }
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Response includes:

• Trade timestamp and direction (BUY/SELL)

• Token amounts and symbols

• USD value and price

• Trader address and label

• Transaction hash

4. Token Transfers

Endpoint: POST /tgm/transfers Credit Cost: 0 credits (FREE) Description: All token transfers including DEX trades and CEX movements

Request Parameters:

{
  "parameters": {
    "chain": "ethereum",
    "tokenAddress": "0x5a98fcbea516cf06857215779fd812ca3bef1b32",
    "date": {
      "from": "2025-05-01",        // Required ISO8601 format
      "to": "2025-05-03"         // Required ISO8601 format
    },
    "dexIncluded": true,
    "cexIncluded": true,
    "onlySmartMoney": false
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

5. Token Flows

Endpoint: POST /tgm/flows Credit Cost: 1 credit per call (requires attribution) Description: Historical flow analysis by holder categories

Request Parameters:

{
  "parameters": {
    "chain": "ethereum",
    "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "date": {
      "from": "2025-05-01",      // Required ISO8601 format
      "to": "2025-05-03"         // Required ISO8601 format
    },
    "label": "top_100_holders"
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Response tracks:

• Daily price and total balance

• Number of holders

• Inflows and outflows

• USD value of holdings

6. Token Flow Intelligence

Endpoint: POST /tgm/flow-intelligence Credit Cost: 1 credit per call (requires attribution) Description: Categorized flow analysis across wallet types

Request Parameters:

{
  "parameters": {
    "chain": "ethereum",
    "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "timeframe": "1d"
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Categories analyzed:

• Public Figures (celebrities/influencers)

• Top PnL Traders (profitable addresses)

• Whales (high-balance wallets)

• Smart Traders (consistently profitable)

• Exchanges (CEX flows)

• Fresh Wallets (newly created)

Note: The API uses timeframe parameter, not date_range.

7. Who Bought/Sold

Endpoint: POST /tgm/who-bought-sold Credit Cost: 1 credit per call (requires attribution) Description: Aggregated buyer/seller analysis

Request Parameters:

{
  "parameters": {
    "chain": "ethereum",
    "buyOrSell": "BUY",
    "timeRange": {
      "from": "2025-05-01",    // Required ISO8601 format
      "to": "2025-05-02"       // Required ISO8601 format
    },
    "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Args:

• buy_or_sell: "BUY" for net buyers, "SELL" for net sellers

• Shows aggregated volumes in both tokens and USD

8. PnL Leaderboard

Endpoint: POST /tgm/pnl-leaderboard Credit Cost: 5 credits per call (Restricted by default) Description: Top traders ranked by profit/loss performance

Request Parameters:

{
  "parameters": {
    "chain": "ethereum",
    "date": {
      "from": "2025-05-01",     // Required ISO8601 format
      "to": "2025-05-03"        // Required ISO8601 format
    },
    "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Response includes:

• Realized and unrealized PnL

• Win rate percentage

• Total trades and average trade size

9. Jupiter DCA (Solana)

Endpoint: POST /tgm/jup-dca Credit Cost: 0 credits (FREE) Description: Dollar-cost averaging orders on Solana via Jupiter

Request Parameters:

{
  "parameters": {
    "chain": "solana",
    "tokenAddress": "So11111111111111111111111111111111111111112",
    "includeLabels": ["Smart Money"],
    "excludeLabels": []
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

Date Range Support

Most Token God Mode endpoints support flexible date ranges using ISO8601 format for example, "2000-10-31T01:30:00.000-05:00".

Performance Best Practices

1. Chain Limits: Query maximum 3 chains per request

2. Date Ranges: Use 1-3 day ranges for optimal performance

3. Filtering: Apply filters to reduce result set size

4. Pagination: Use smaller page sizes (50-100) for complex queries

5. Smart Money Filter: Enable when focusing on quality over quantity

Response Data Notes

• Positive net flows = more buying than selling

• Negative exchange flows = tokens leaving exchanges (bullish)

• FDV/MC Ratio > 1 = locked/vested supply exists

• Smart Money = addresses with profitable trading history

Supported Chains

Smart Money Labels

Available Smart Money filter options:

• "30D Smart Trader" - Top performers in last 30 days

• "90D Smart Trader" - Top performers in last 90 days

• "180D Smart Trader" - Top performers in last 180 days

• "Fund" - Institutional funds and investment entities

• "Smart Trader" - General high-performing traders

Error Handling

Common HTTP Status Codes:

• 200 OK - Successful response

• 400 Bad Request - Invalid parameters or request format

• 401 Unauthorized - Missing or invalid API key

• 403 Forbidden - Insufficient subscription tier

• 429 Too Many Requests - Rate limit exceeded

• 500 Internal Server Error - Server error

• 504 Gateway Timeout - Request timeout