The Nansen API implements rate limiting to ensure fair usage and system stability. Rate limits are applied per API key and vary by subscription tier.
Rate Limits:
The current rate limits are 20 requests per second and 300 requests per minute.
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.
Token God Mode
API Changelog
Common MCP clients
Below are some popular MCP clients for running remote Nansen MCP servers:
Claude
Cursor
VS Code
N8N
Complex Use cases
Explore advanced workflows you can create with the Nansen API. This section showcases complex use cases designed to help you unlock deeper insights and automate sophisticated tasks, empowering your team to get the most from Nansen’s API.
This section provides comprehensive use case templates for the Nansen API V1, organized by both difficulty level and specific use case. Templates are grouped into "Simple" and "Complex" categories to help developers quickly find relevant examples based on their experience and needs. Each template is designed to guide you through integrating with the API and building meaningful applications.
Welcome to the Nansen API. This guide will help you get up and running quickly.
Prerequisites
A Nansen account with API access
An API key from your or through
Quick Start
1. Set Up Authentication
All API requests require your API key in the apikey header:
2. Make Your First Request
3. Understand the Response
Next Steps
Authentication - Detailed auth setup
Rate Limits - Understand API limits
Credits System - How credits work
Perp Trades
Historical Holdings
Note: This is a beta endpoint. The data provided may be subject to changes, corrections, or improvements as we continue to refine our Smart Money analytics.
Who Bought/Sold
PnL Leaderboard
Update: A premium_labels parameter is being added to this endpoint. From April 1, the default changes from true to false .
Address Related Wallets
Address Transactions
Token Transfers
Search
Address Perp Positions
Jupiter DCAs
Agent
Entity Name Search
Use this endpoint to find correct entity name format to use in Supported Profiler Endpoints (Consumes 0 Credits)
Address PnL & Trade Performance
You can use this endpoint to find correct entity name format to use in this Profiler Endpoint: Click Here
Flow Intelligence
Jupiter DCAs
Token Screener
Data Retention Limits
This endpoint only supports recent data:
Minute Granularity: Last 130 minutes
Hourly Granularity: Last 50 hours
Daily Granularity: Last 50 days
Historical Analysis Not Supported:
to_date must be within 5 minutes of current time
Historical snapshots (e.g., "show me January 2024") are not available
Useful Links
Name
Link
Website Link
Plans and Pricing
Web-App
Token Perp Trades
Address Perp Trades
Hyperliquid Address Leaderboard
Price OHLCV
Address Labels
Retrieves all entity and behavioural labels associated with an address on a chain.
Token Perp Positions
Smart Money Perp Trades
DEX Trades
Perp Screener
Perp PnL Leaderboard
Update: A premium_labels parameter is being added to this endpoint. From April 1, the default changes from true to false .
DEX Trades
Perp Positions
Update: A premium_labels parameter is being added to this endpoint. From April 1, the default changes from true to false .
Token Information
Introduction
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:
Address Counterparties
Get counterparties and their interaction statistics for any address or entity.
Common Scenarios
You can use this endpoint to find correct entity name format to use in this Profiler Endpoint:
Address Historical Balances
Get historical token balance information for any blockchain address or entity
Common Scenarios
You can use this endpoint to find correct entity name format to use in this Profiler Endpoint:
Perp Screener
Common Scenarios
Usecase
Required Parameters
Optional Filters
Expected Output
Holdings
Aggregated token holdings data for smart traders and funds.
Common Scenarios
Usecase
Required Parameters
Filters
Sorting Logic
Expected Output
Flows
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.
Data Methodology & Technical Reference
This page provides detailed technical specifications about how data is calculated, returned, and timed across Nansen API endpoints. This information is essential for quantitative analysis, backtesting
Date Range Behaviour
All date range parameters across Nansen API endpoints use closed brackets on both sides [from, to], meaning both the from_date and to_date are inclusive. For example, requesting from=2024-11-04, to=2024-11-05 will return data for both November 4th and November 5th.
Hyperliquid Leaderboard
Common Scenarios
Usecase
Required Parameters
Optional Filters
Expected Output
Perp PnL Leaderboard
Common Scenarios
Usecase
Required Parameters
Optional Filters
Expected Output
Address Current Balances
Get real-time token balance information for any blockchain address or entity
Common Scenarios
You can use this endpoint to find correct entity name format to use in this Profiler Endpoint:
Netflows
Get aggregated token flow analysis for smart money wallets to see which tokens they're accumulating or distributing.
A new premium_labels parameter has been added to these endpoints to control wallet label tier.
Value
Behavior
Holders
Update: A premium_labels parameter is being added to this endpoint. From April 1, the default changes from true to false .
Address Perp Trades
Common Scenarios
Usecase
Required Parameters
Optional Filters
Expected Output
Address Perp Positions
Common Scenarios
Usecase
Required Parameters
Optional Filters
Expected Output
Historical Data Calculation Method (Smart Money Holdings)
The Smart Money Historical Holdings API returns pure historical snapshots using prices from the actual date requested, not recalculated values. This ensures there is no look-ahead bias, making the data suitable for backtesting and predictive models.
Field-Level Details
value_usd: Historical USD value using the median price from that day
market_cap_usd: Historical market cap snapshot for that date
balance_24h_percent_change: Historical percentage calculated using that day's balance and the previous day's balance (with each day using its respective price)
Snapshot Timing & Data Availability
Snapshot Time
Daily snapshots represent end-of-day UTC values.
Data Availability (Smart Money Historical Holdings)
Data processing begins at 05:00 AM UTC. Data is typically available by 07:00 AM UTC, though exact timing may vary. The current day's data is excluded from responses since it would be incomplete.
Historical Depth
The Smart Money Historical Holdings endpoint provides a 4-year rolling window of historical data. The earliest available date moves forward daily.
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.
Returns tokens with highest net outflow in DeFi sector
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
Set "label" to "smart_money" in the parameters object.
Add "includeLabels" as an array with the specific Smart Money segments you want (e.g., "Fund", "30D Smart Trader").
Other parameters (like chain, tokenAddress, date range, etc.) stay the same.
Example Configuration:
Usecase 2: List of Exchanges Holding a Token
Set "label" to "exchange" in the parameters object.
Add "includeLabels" with "Exchange"
Other parameters remain unchanged.
Example Configuration:
address ="0x45d26f28196d226497130c4bac709d808fed4029" date ={ "from": "2025-10-01", "to": "2025-10-10" }
(none needed for basic usage)
List of trades with timestamps, price, size, token, direction (Long/Short), action (Open/Close), and fees for the address
Analyze high-value trades with closed PnL details
address ="0x45d26f28196d226497130c4bac709d808fed4029" date ={ "from": "2025-10-01", "to": "2025-10-10" }
filters ={"value_usd": {"min": 1000}}
List of trades above $1,000 with closed PnL, fees paid, order IDs, and asset symbols
Track all short trades and compare performance by token
address ="0x45d26f28196d226497130c4bac709d808fed4029" date ={ "from": "2025-10-01", "to": "2025-10-10" }
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:
400
Bad Request: Malformed request, invalid parameters or format
Check your request syntax and parameters
401
Unauthorized: Authentication failed (missing, invalid, or expired token)
Make Your First API Call
Welcome! In the next 2 minutes, you’ll make your first API call and unlock real-time blockchain insights.
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"
Connecting to Nansen MCP
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:
Nansen API Key: Get yours at
npx: Required for remote connections (npm install -g npx)
Installation Guide
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.
2. Claude Code (Terminal Integration)
Connect Nansen MCP through your terminal:
3. Cursor IDE
One-click install via Cursor deep link:
Copy the deep link below (right-click > copy)
Paste into any Cursor text/chat field
Ctrl+Click (or Cmd+Click on Mac) inside Cursor to install
4. 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
NPX example:
Authentication
⚠️ Nansen MCP uses the same API as your regular API keys. Ensure you have sufficient credits for your usage.
Nansen CLI
Overview
The Nansen CLI (nansen-cli) is a command-line interface for the Nansen API. All output is structured JSON, making it ideal for AI agents, scripts, and automation pipelines.
Or run without installing:
Source code:
Authentication
Overview
The Nansen API uses API key authentication. All requests must include your API key in the apikey header.
Frequently Asked Questions
Authentication
How can developers obtain API keys and access Nansen’s API endpoints?
You can request an API key by signing up on Nansen. You can find the detailed steps
Use case 5: Monitoring CEX Health
1. Scenario
Monitor centralized exchange (CEX) health by tracking onchain asset balances and daily net flows.
Goal: Generate daily reports showing:
Name
Assets on Exchange
"label": "smart_money",
"includeLabels": ["Fund", "30D Smart Trader"]
"isEntity": true, -- To aggregate by Entity
"label": "exchange",
"includeLabels": ["Exchange"]
"isEntity": true, -- To aggregate by Entity
"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"
Obtain or refresh your API Key
402
x402: Payment Required
Please make the payment for API request and try again
403
Forbidden: Auth succeeded, but no permission for resource
Ensure your account has access rights
404
Not Found: Resource or endpoint does not exist
Verify the endpoint path and resource identifiers
422
Unprocessable Content
Please verify your parameters
429
Too Many Requests: Rate limit exceeded
Slow down requests; respect rate limits
500
Internal Server Error: Unexpected server issue
Try again later; contact support if persistent
504
Gateway Timeout: Backend server did not respond in time
What types of data are available through Nansen’s API (e.g., wallet balances, token prices, labeled transactions)?
The API provides access to wallet balances, transaction data, exchange flows, smart money tracking and other on-chain analytics across multiple chains. You can find the full list of endpoints here.
API Rate Limits & Quotas
What are the usage limits for Nansen’s API?
Nansen API comes with a flexi-credit plan. You purchase as many credits you need.
Data Coverage
Can I access labeled transaction data across multiple chains via the API?
Yes, you can use /transactions to access transaction data and /labels endpoint to fetch labels across multiple chains.
What on-chain metrics are available via Nansen’s API?
Metrics include wallet balances, token flows, smart money movements, portfolio distributions, and other derived analytics from raw blockchain data. You can find the full list of endpoints here.
Does the API provide access to smart money wallet activities and behaviors?
Yes, API allows users to monitor smart money inflows, portfolio holdings and DEX Trades. You can find the full list of Smart Money endpoints here.
How does Nansen handle and provide data for non-EVM chains such as Solana or Sui?
Nansen processes data from non-EVM chains by building native integrations that extract and structure on-chain information similar to EVM-based chains, while adjusting for each chain’s unique architecture. You can find the full list of supported chains here.
Data Freshness and Performance
How frequently is the data updated in the API?
Data is refreshed at varying intervals, with many endpoints updating in real-time depending on the data type.
What is the typical latency for data delivery through Nansen’s API?
Typical data latency is low, often within seconds, depending on the chain being queried
Developer Tools and Integration
Does Nansen support AI Integration Capabilities?
Nansen offers MCP support that allows you to connect your AI tools to Nansen's Onchain Data. You can read more and follow steps for access here.
Does Nansen offer SDKs, libraries, or tools for integrating analytics into third-party applications like DEXs or wallets?
No
Can I programmatically perform bulk analysis on wallet data using Nansen’s tools?
Yes, Nansen’s API endpoints are designed for scalable, programmatic analysis across large datasets of wallets and transactions.
The CLI uses the same API key as the REST API. Two options, in priority order:
Environment variable (recommended for agents and CI):
Interactive login (persistent):
Verify it works:
schema is free and requires no API key -- if you get JSON back, the CLI is installed correctly.
Quick Start
Schema Discovery
The CLI is fully self-documenting via nansen schema. This requires no API key and returns a machine-readable JSON reference of all commands, options, return fields, and supported chains.
Example: query supported chains:
Agents should use nansen schema as the source of truth for available commands and options.
Output Format
All responses use a consistent JSON envelope:
Errors include a machine-readable code:
Key error codes: UNAUTHORIZED, CREDITS_EXHAUSTED, RATE_LIMITED, INVALID_ADDRESS, UNSUPPORTED_FILTER. See Error Handling for the full list.
Tips for AI Agents
Use schema for self-discovery. Agents should call nansen schema at the start of a session to learn available commands, options, and supported chains -- it costs zero credits.
Use --fields to reduce response size. Large JSON responses waste agent context tokens.
Use --stream for large result sets. Processes results line-by-line instead of buffering the entire response.
Budget credits carefully. Most calls cost 1 credit. schema and help are free. If you get CREDITS_EXHAUSTED, stop all calls immediately.
Nansen's Hyperliquid API endpoints provide comprehensive access to perp trading data on Hyperliquid. Track positions, analyze trades, screen tokens, and follow smart money activity across the fastest-growing perps platform.
What can you do?
With Hyperliquid endpoints, you can:
Track wallet positions: Monitor real-time perpetual positions, PnL, and account health
Analyze trading activity: View detailed trade history and execution data of any address
Screen perp trading activity: Find high-volume tokens and smart money flows on Hyperliquid
Find top performers: Discover the most profitable traders on specific tokens.
Which endpoints can I use?
I want to...
Use this endpoint
Best for
Key Differences: Hyperliquid vs. Other Chains
Token Identification
Important: Hyperliquid perp endpoints use token symbols instead of token addresses in Token God Mode Inputs
Other Chains
Hyperliquid
Example:
Positive and Negative Positions
Some endpoints (Eg. Token Perp Positions) have negative Position value. This usually represents a short and a positive value represents a long.
Quick Start Checklist
Get your API key from Nansen
Choose your use case:
Wallet monitoring → Use /perp-positions + /perp-trades
Portfolio
DeFi Holdings API tracks active positions across DeFi protocols.
Output Field Meanings
Top-Level Fields
Position Types within holdingsByProtocol
Position Detail Structure
Supported Protocols
You can find the list of supported protocols on each supported chain by .
Usage Guide: Creating Complete Portfolio Overview
Use the following steps to create a complete Portfolio Overview:
Step 1: Fetch DeFi Positions
Get active protocol positions, staking rewards, and lending activities. This shows how assets are being used in DeFi.
Step 2: Fetch Wallet Balances
Retrieve all token holdings across chains, including idle tokens not actively deployed in protocols.
Step 3: Combine & Analyze
Total Portfolio Value = DeFi positions + wallet balances
Strategy Analysis: Compare liquid vs. staked vs. lending positions
Complex positions like LP tokens, derivatives, or structured products
Use case 3: Identifying Related Wallets at Scale
Scenario
An address clustering workflow that uses the Nansen API to systematically identify related wallet addresses and analyze their relationships. This enables researchers to uncover wallet connections through funding patterns, shared interactions, and behavioral analysis across multiple blockchains.
Core Components
Labels: Find labels of the initial address
Related Wallets: Detection of special connections (funding, signing, contract deployment)
Counterparties Analysis: Identification of high-interaction addresses and shared patterns
This integration enables systematic discovery of wallet clusters through multiple relationship types and confidence levels.
Workflow Implementation
Step 1: Tarket Address Label Lookup
Query labels of the target address
Step 2: Initial Relationship Discovery
Query Related Wallets endpoint with target address
Identify direct relationships: relation: "First Funder", "Signer", "Deployed via"
Build initial cluster with high-confidence connections
Step 3: Counterparty Analysis
Analyze counterparties with group_by: "entity" for entity-level grouping
Filter for volume_in_usd > 50000 to find significant addresses
Identify shared CEX deposit addresses across potential cluster members
Step 4: Pattern Recognition
Compare transaction timing using block_timestamp fields
Look for addresses with similar method: "0x" patterns
Check for coordinated movements with matching transaction_type
Step 5: Multi-Level Clustering
For each high-confidence related address, repeat steps 1-3
Cross-reference addresses that deposit to same CEX addresses
Build network graph of relationships with confidence scores
Step 6: Confidence Assessment
High confidence (>90%): First funder, shared signers, same CEX deposits
Medium confidence (60-90%): High interaction volume, coordinated timing
Filter out false positives from common protocol interactions
Code Examples
1. Find Target Address Labels
Identify all the labels associated with the target address
2. Find Related Wallets (Direct Relationships)
Identify wallets with special connections to a target address:
This reveals first funder relationships, signer connections, multisig relationships, and contract deployment patterns.
3. Analyze Address Counterparties
Find addresses with the highest interaction volume:
This identifies CEX deposit addresses and high-frequency interaction patterns crucial for clustering.
4. Track Historical Balance Patterns
Analyze coordinated balance movements across potential cluster members:
Coordinated balance changes across addresses indicate potential cluster membership.
5. Examine Transaction Patterns
Review transaction history for behavioral similarities:
Similar transaction timing and patterns across addresses suggest coordinated activity.
Use case 1: Automated Token Tracking & Smart Money Analysis
Scenario
A DeFi trading team automated their token discovery and smart money analysis using Nansen's API. They built custom tools that combine multiple data sources to identify promising trading opportunities in real-time.
Start by selecting the chains you want to analyze (e.g., Ethereum, Solana). Apply filters to narrow down your search:
Set market cap range (min and max) to target tokens with desired liquidity.
Specify minimum liquidity and number of traders to focus on active, tradable tokens.
Limit token age to capture new and trending assets.
Step 2: Analyze Smart Money Netflow
Use the Smart Money Netflow endpoint to track institutional and expert activity:
Select your chains.
Include smart money labels such as “Fund”, “Smart Trader”, and “30D Smart Trader” for targeted analysis.
Set a minimum market cap and trader count to filter out low-activity tokens.
Step 3: Validate Trader Credibility with TGM PnL Leaderboard
For any token of interest, use the TGM PnL Leaderboard:
Specify the chain and token address.
Set your date range for analysis.
Filter for holders with significant USD value and realized profit.
Code Blocks
Token Screener API Call
Smart Money Netflow API Call
TGM PnL Leaderboard API Call
Use Case 2: Find & Copytrade Wallets on Hyperliquid
Use Nansen API To Find and Copytrade Profitable Wallets on Hyperliquid
1. Scenario
Identify and replicate trades from successful perpetual traders on Hyperliquid by monitoring their positions and trade activity in real-time.
Goal: Build an automated copytrading system that:
Discovers profitable traders using the Hyperliquid leaderboard
Monitors their perpetual positions and recent trades
Replicates their trading activity in your own account
2. Solution
Use three Nansen API endpoints:
Perp Leaderboard - Discover top performing traders by PnL and ROI
Perp Positions - Monitor current open positions for selected wallets
Perp Trades - Track all trades executed by profitable wallets
Optional: Filter the leaderboard to smart money wallets only for higher quality signals.
Example workflow:
Discover top Smart Money traders from Step 1
Every 30 minutes to an hour:
Fetch recent trades (last 1 hour) for all traders
3. Step-by-Step Guide
Step 1: Find Profitable Traders on Hyperliquid
Use the Perp Leaderboard endpoint to discover the most profitable perpetual traders over a specific timeframe.
Call the perp leaderboard endpoint:
Process the response:
Extract trader_address from top performers
Note their total_pnl, roi, and account_value for ranking
Example response:
Step 2: Monitor Current Positions
For each profitable trader identified, check their current open positions to understand what they're actively trading.
Call the perp positions endpoint:
Process the response:
Identify active positions by token_symbol (e.g., BTC, ETH, SOL)
Note position direction from size (positive = long, negative = short)
Review unrealized_pnl_usd
Key fields to monitor:
token_symbol: The perpetual contract being traded
size: Position size (negative for short, positive for long)
position_value_usd: Total position value
Step 3: Track Trading Activity
Monitor recent trades to identify entry and exit signals you can replicate.
Call the perp trades endpoint:
Process the response:
Identify new positions from trades where action = "Open"
Detect position increases where action = "Add"
Track exits where action = "Close" or "Reduce"
Key fields for copytrading:
timestamp: When the trade occurred
token_symbol: What contract was traded (e.g., BTC, ETH)
side: Position direction (Long or Short)
Points
Developer reference for the Permissionless Rewards API service.
Permissionless Rewards: Concepts
Before integrating the Nansen Points Leaderboard endpoint, it helps to understand Permissionless Rewards at a high level—see Nansen Academy: On Permissionless Rewards for full details.
What they are: An open registry that maps Nansen Points balances to onchain wallets (EVM and Solana), without requiring an API key or explicit permission from Nansen.
Why it matters: Protocols can seamlessly discover eligible wallets and distribute tokens, NFTs, or other perks—fully public and opt-in.
User control: Holders can add or remove their wallet mapping at any time, revoking future distributions.
A. Points Leaderboard (Paginated)
GET
Query the full leaderboard with pagination. No authentication required.
Query Parameters
Name
Type
Required
Default
Description
Example Request
Response Structure
Results are ordered by rank. Ties share the same rank.
B. Individual Lookup
GET
Fetch the tier for a single wallet address. No API key or authentication required.
Query Parameters
Name
Type
Required
Description
Example Request
Response Structure
References
Response Codes
Code
Description
Fields Response:
Field
Type
Description
Usage Notes
Minimum Qualification: Wallets with fewer than 1,000 points return {"tier":"none"}
Public & Permissionless: No authentication required.
Data Refresh: Tier data refreshes daily at 11am UTC. Implement local caching to reduce redundant calls.
Tools supported by Nansen MCP
Tools supported by Nansen MCP
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.
Most tools wrap arguments in {"request": {...}} but general_search and transaction_lookup take flat args
Date ranges use object format: {"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}
Simple Use cases
Use the sample requests and responses to accelerate development and gain actionable insights from blockchain data.
1. Viewing DeFi Positions
Description: Get comprehensive information about a wallet's DeFi positions including balances, values, and token details.
Use Case: Analyze DeFi portfolio performance, track position changes, and understand asset allocation.
Endpoint Documentation:
cURL Command (Replace your API Key and run this in your terminal):
Key Benefits:
Complete portfolio overview across multiple chains
Real-time balance and value calculations
Common Use Cases:
Portfolio tracking applications
DeFi protocol analytics
Risk management systems
2. Viewing Smart Money Holdings
Description: Discover which tokens top traders and funds are holding.
Use Case: Follow smart money movements, identify trending tokens, and make informed investment decisions.
Endpoint Documentation:
cURL Command (Replace your API Key and run this in your terminal):
Key Benefits:
Identify institutional investment trends
Track smart money portfolio changes
Filter by smart money categories
Common Use Cases:
Investment research and analysis
Token discovery and trending analysis
Market sentiment analysis
3. Finding Top Holders of a Token
Description: Discover the largest holders of a specific token, including their balances and wallet types.
Use Case: Analyze token distribution, identify major stakeholders, and understand market concentration.
Endpoint Documentation:
cURL Command (Replace your API Key and run this in your terminal):
Key Benefits:
Identify major token holders and their types
Includes individual addresses and aggregated by entity views
Track balance changes over time
Common Use Cases:
Token governance analysis
Market concentration studies
Risk assessment for token holders
4. Using Token Screener to Find New Tokens
Description: Discover new and trending tokens based on various metrics like market cap, token age, volume, and smart money activity.
Use Case: Find emerging opportunities, track new token launches, and identify trending assets.
Endpoint Documentation:
cURL Command:
Key Benefits:
Discover new token opportunities
Filter by market cap, volume, sectors and age
Track trending metrics and holder growth
Common Use Cases:
Token discovery using different metrics
Next Steps
Once you're comfortable with these easy-level use cases, explore:
Medium Level: Advanced filtering, historical data analysis, and multi-chain operations
Hard Level: Complex analytics, data aggregation, and real-time monitoring systems
For more information, refer to the complete API documentation and examples in the repository.
Smart Money
Overview
Smart Money endpoints provide insights into the trading and holding activity of sophisticated market participants, including institutional funds and historically profitable traders.
Endpoints
// Other chains
{"token_address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"}
// Hyperliquid
{"token_symbol": "BTC"} // For leaderboard endpoint
Tier name determined by points thresholds.
Valid tier values are: "none," "green," "ice," "north," or "star." Addresses not on the leaderboard return "none."
rank
number
Leaderboard rank. Users with the same points share the same rank.
Welcome to our updated API pricing and credit system. We’ve made it easier to get started, scale up, and pay only for what you need.
Available API Plans
We offer two main API plans to fit your needs:
Plan
Credits Included
Top Ups
Intended Use
For more information on plan features, visit .
Pro Plan Details
Subscription: $49/month (annual) or $69/month (monthly)
Starter Credits: Get 1,000 credits to start building before making your first purchase
Flexi-Credits: Purchase as many credits as you want. (Here's a )
Free Plan Details
100 one-time credits to try the API
Ability to purchase credits
API credits are consumed much faster than Pro plan
List of Available Endpoints in Free Tier
Free plan users have access to the following endpoints:
/v1/profiler/address/transactions
What Your Budget Gets You?
You can also use to easily plan your API budget.
Quickly compare what each credit package unlocks across our main API features.
Budget
Credits
What it gets you
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.
Endpoint
Credit Cost per Call (Pro)
Credit Cost per Call (Free)
FAQs
What happens if I run out of credits?
You can purchase additional credit blocks at any time to ensure your service is not interrupted.
Are there higher tiers or enterprise plans?
No, the Pro plan is designed to meet most needs. However, if you are making a bulk credit purchase over $10,000, 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:
x402 Payments
Overview
x402 enables pay-per-call access to the Nansen API using cryptocurrency. No subscription or API key required. Send a request, pay with USDC on EVM (Base) or Solana, and get data back.
How It Works
x402 is an open HTTP payment protocol. When you make a request to a supported endpoint without an API key, the server returns a 402 Payment Required response with payment instructions. Your client pays the specified amount in USDC, then retries the request with a payment receipt.
Request Flow
Example
With an x402-compatible client, payment and retry happen automatically:
Pricing
All Pro-tier endpoints are available via x402 (except labels endpoint). Pricing is based on endpoint tier.
Tier
Price Per Call
Endpoints
Basic Endpoints — $0.01/call
Endpoint
Path
Premium Endpoints — $0.05/call
Endpoint
Path
Smart Money Endpoints — $0.05/call
Endpoint
Path
Excluded Endpoints
/api/v1/labels/*; these require a Pro subscription due to the proprietary nature of Nansen's entity classification data.
/api/v1/portfolio/defi-holdings
Payment Details
Parameter
Value
Rate Limits
x402 requests have separate rate limits from API key authenticated requests.
Limit
Value
If you exceed rate limits, you'll receive a 429 Too Many Requests response. Payments are not charged for rate-limited requests.
FAQ
Q: Do I need a Nansen account? No. x402 is fully permissionless. You only need a wallet with USDC on Base or Solana.
Q: What happens if payment fails? You'll receive a 402 Payment Required response again. No data is returned until payment succeeds.
Q: Can I use x402 and an API key together? If you include a valid API key, it takes precedence and no x402 payment is required.
Q: Which networks are supported for payment? Currently Base and Solana. More networks may be added in the future.
Q: Is there a minimum balance required? No minimum. You just need enough USDC to cover the call price plus gas fees (typically < $0.01).
Use case 4: Copytrading Top Performing Wallets
Scenario
A copy trading workflow that uses the Nansen API to deliver structured, real-time onchain token insights. This enables traders to understand token flows, track smart money activity, and evaluate token performance across multiple chains.
Core Components
Flow Intelligence (): Real-time tracking of wallet inflows and outflows for each token
PnL Leaderboard (): Identification of top-performing wallets by token
Select your target blockchain (chain: "ethereum") and token address (token_address: "0x6982508145454ce325ddbe47a25d4ec3d2311933").
Call the Flow Intelligence endpoint with timeframe: "7d" to monitor weekly inflows and outflows.
Step 2: Find Top-Performing Wallets For a Token
Use the PnL Leaderboard endpoint with chain: "ethereum" and your token address.
Set date range with date: { "from": "2024-10-01", "to": "2025-01-21" } for 3-month analysis.
Apply filter pnl_usd_realised: { "min": 1000 }
Step 3: Assess Cross-Chain Wallet Performance
For any wallet, use PnL Summary with address: "0x39d52da6beec991f075eebe577474fd105c5caec" and chain: "ethereum".
Set date: { "from": "2024-07-01", "to": "2025-01-21" } for 6-month performance history.
Step 4: Monitor Smart Money DEX Trades
Call Smart Money DEX Trades with chains: ["ethereum", "base", "arbitrum"] for multi-chain coverage.
Apply filters: token_bought_address: "0x6982508145454ce325ddbe47a25d4ec3d2311933" and trade_value_usd: { "min": 10000 }.
Step 5: Analyze Token Holder Distribution
Access Token Holders endpoint with chain: "ethereum" and your token address.
Set label_type: "smart_money" and filter with include_smart_money_labels: ["Smart Trader", "Fund", "30D Smart Trader"].
Step 6: Implement and Refine Copy Trading
Select wallets with roi_percent_realised > 50 and win_rate > 0.6 from your PnL analysis.
Set up monitoring with pagination: { "page": 1, "per_page": 20 } to track the top 20 performers.
Code Examples
1. Get Token Flow Intelligence
Track real-time capital flows to identify accumulation or distribution patterns:
This endpoint reveals net flows across different wallet segments (smart traders, whales, public figures) helping identify whether sophisticated players are accumulating or distributing.
2. Get PnL Leaderboard (Find Highest Performing Wallets)
Identify the most profitable traders for any token:
This leaderboard shows which wallets have the highest realized profits, enabling copy traders to identify successful trading patterns.
3. Get Wallet PnL Summary (Cross-Chain Performance)
Analyze a trader's overall performance and success rate:
This provides win-rate, realized PnL, and top profitable tokens for any wallet, helping assess trader quality before copying their strategies.
4. Track Smart Money DEX Trades
Monitor real-time trading activity from sophisticated traders:
Real-time smart money trades provide copy trading signals by showing what experienced traders are buying or selling right now.
5. Analyze Token Holder Distribution
Understand token concentration and holder quality:
This shows smart money concentration in any token, helping traders assess whether sophisticated investors are holding or have exited.
Endpoints Overview
Overview
The Nansen API provides endpoints organized into 4 categories. All endpoints use POST requests with JSON bodies.
TGM Holders (Link Here): Identify top holders of any token
Review net flows by wallet type - check smart_trader_net_flow_usd, whale_net_flow_usd, and public_figure_net_flow_usd fields to spot accumulation (positive values) or distribution (negative values) trends.
to find wallets with over $1,000 realized profits.
Review the roi_percent_realised and nof_trades fields to identify consistent performers.
Check win_rate (target > 0.5), realized_pnl_usd, and top5_tokens array to judge trader reliability.
Include include_smart_money_labels: ["Smart Trader", "Fund"] to focus on sophisticated traders.
Monitor token_bought_amount and estimated_swap_price_usd for entry points.
1. Client sends request (no API key)
2. Server returns 402 with payment details
3. Client pays USDC on Base or Solana
4. Client retries with payment receipt in header
5. Server verifies payment and returns data
A curated list of the top 5 000 highest-performing wallets ranked by realised profit, winrate, and strong performance across market cycles.
Endpoint
Credit
Description
5
Provides net flow of tokens bought/sold by Smart Money addresses
5
Holdings of tokens by Smart Money addresses.
Agent
Endpoint
Credit
Description
200
Ask Nansen Agent any question in fast mode
750
Ask Nansen Agent any question in expert mode
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.
Endpoint
Credit
Description
1
Current Token balances of an address
1
Historical holdings of a wallet address
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.
Endpoint
Credits
Description
1
A token screening endpoint that provides real-time analytics and insights across multiple blockchain networks.
1
Discover and screen tokens on Hyperliquid with the highest volume and smart money activity.
Portfolio API
Endpoint
Credits
Description
1
Track DeFi positions of all addresses
Filter Types
Overview
Filters allow you to narrow down API results to specific criteria. Each endpoint supports different filters based on the data it returns.
Filter Types
NumericRangeFilter
Filter numeric values (floats) with optional min/max bounds.
Schema:
Fields:
Field
Type
Description
Examples:
Common Uses:
value_usd - Filter by USD value
price_usd - Filter by price
market_cap_usd - Filter by market cap
IntegerRangeFilter
Filter integer values with optional min/max bounds.
Schema:
Fields:
Field
Type
Description
Examples:
Common Uses:
holder_count - Filter by number of holders
token_age_days - Filter by token age
trade_count - Filter by number of trades
DateRangeFilter
Filter by date/time ranges.
Schema:
Fields:
Field
Type
Description
Formats:
Examples:
TokenAddressFilter
Filter by one or more token addresses.
Schema:
Examples:
TraderAddressFilter
Filter by one or more trader/wallet addresses.
Schema:
Examples:
LabelFilter
Filter by smart money or entity labels.
Schema:
Smart Money Labels:
Extended Labels:
Examples:
SectorsFilter
Filter by token sector/category.
Schema:
Common Sectors:
Examples:
BooleanFilter
Simple true/false filter.
Schema:
Examples:
Filter Validation Rules
Range Filters
max must be greater than min if both provided
Some fields require positive values only
Date Filters
to must be after from
Maximum range is typically 1 year
Address Filters
Must match chain address format
Cannot be burn/zero addresses for some endpoints
Using Filters in Requests
Basic Filter Usage
Combining Multiple Filters
Endpoint-Specific Filters
Different endpoints support different filters. Check each endpoint's documentation for available filters.
29-08-2025: Major API Restructuring
This changelog highlights the key architectural and structural differences between the beta endpoints and v1 endpoints, focusing on breaking changes that developers need to be aware of when migrating.
🔄 Version Update
From: Beta endpoints (/api/beta/*
Sorting
Overview
Most Nansen API endpoints support sorting results using the order_by parameter. This allows you to control the order of returned data.
Impact: Significant impact - all fields are changed to snake_case
3. Response Structure Standardization
Before (Beta): camelCase Response Fields
After (v1): snake_case Response Fields
Note: Not all v1 endpoints return pagination fields - some return data only while others include pagination metadata. When pagination is present, it now includes an is_last_page boolean for easier pagination handling.
Impact: All client code must be updated to handle snake_case field names in responses.
Many endpoints have sensible default sorts. Check the endpoint documentation for defaults.
Error Handling
Invalid Sort Field
Invalid Direction
Python Helper
MCP Data Redistribution Guidelines
Purpose
These guidelines help developers understand how to legally and responsibly redistribute data obtained from Nansen API and MCP tools, while protecting Nansen's proprietary insights and competitive advantage.
You may freely redistribute this data in your products, services, or applications according to Nansen's Terms of Service. No additional permissions needed.
Example use cases:
Displaying wallet balances in your portfolio tracker
✅ Allowed (with attribution)
You may redistribute this data, but you must provide clear attribution to Nansen.
Attribution requirements:
Display "Powered by Nansen API" visibly in your product interface, OR
Provide a clickable link to Nansen.ai near the data display
Note: Attribution is NOT required for personal or internal-only use.
Example use cases:
Token screening dashboards that display real-time token metrics and volume data
Trading analytics platforms showing DEX trade flows and whale activity
Demonstrate significant data transformation (see requirements below)
Provide clear attribution to Nansen
This data cannot be redistributed without meeting these requirements.
🚫 Prohibited
Redistribution is NOT allowed under any circumstances. These endpoints contain Nansen's most sensitive proprietary data and competitive advantages.
Do not:
Display this data in any public or customer-facing interface
Use this data to build competing products
Redistribute this data through APIs, exports, or any other means
Internal use only: You may use this data for your own internal analysis, but not share it externally.
What is "Significant Modification"?
To redistribute smart money data, you must transform it substantially so that:
Not Directly Traceable: The output cannot be reverse-engineered to reveal Nansen's underlying smart money classifications, wallet lists, or raw activity data
Meaningfully Combined: The data must be integrated with at least one other substantial, independent data source (not just cosmetic additions)
Novel Insights: Your final output must provide unique analysis or value-add beyond what Nansen already offers
✅ ALLOWED Use Cases (with approval)
1. AI Agent Background Analysis
Using smart money data as one input among multiple sources to generate unique analytical responses.
✓ Good Example:
Your AI agent analyzes: Nansen smart money flows (30%) + on-chain volume metrics (30%) + social sentiment analysis (20%) + technical indicators (20%) → generates custom investment thesis that synthesizes all sources
✗ Bad Example:
Your AI agent says: "Smart money wallets bought 5M tokens in the last 24 hours according to Nansen data"
2. Custom Composite Indicators
Building proprietary trading signals that incorporate smart money data alongside other metrics.
✓ Good Example:
A "Token Momentum Score" (0-100) that combines:
Smart money net flow (25%)
DEX liquidity depth (25%)
Price action volatility (25%)
✗ Bad Example:
A "Smart Money Activity Index" that's just a reformatted version of Nansen's smart money inflow data
3. Research Reports & Analysis
Periodic research that synthesizes smart money trends with broader market context.
Check latest guidelines before launching products, changing data usage, or entering new markets
3. API & MCP Coverage
Rules apply to API responses, MCP tools, and derived data
4. Volume & Rate Limits
Redistribution doesn't exempt you from rate limits
5. Data Accuracy
Don't misrepresent data
Include appropriate disclaimers
Don't make unwarranted guarantees
6. Competitive Use
Don't build competing products
Don't use Nansen data as foundation for competitor services
Don't repackage data to commoditize Nansen's insights
Data Redistribution Guidelines
Updated as of 18/11/2025
Purpose
These guidelines help developers understand how to legally and responsibly redistribute data obtained from Nansen API and MCP tools, while protecting Nansen's proprietary insights and competitive advantage.
Quick Reference: Can You Redistribute?
Endpoint
Status
Requirements
Understanding Redistribution Statuses
✅ Allowed
You may freely redistribute this data in your products, services, or applications according to Nansen's Terms of Service. No additional permissions needed.
Example use cases:
Displaying wallet balances in your portfolio tracker
✅ Allowed (with attribution)
You may redistribute this data, but you must provide clear attribution to Nansen.
Attribution requirements:
Display "Powered by Nansen API" visibly in your product interface, OR
Provide a clickable link to near the data display
Note: Attribution is NOT required for personal or internal-only use.
Example use cases:
Token screening dashboards that display real-time token metrics and volume data
Trading analytics platforms showing DEX trade flows and whale activity
These endpoints contain Nansen's proprietary smart money insights and require both approval AND significant data modification.
You must:
Submit a request for approval via
Demonstrate significant data transformation (see requirements below)
Provide clear attribution to Nansen
This data cannot be redistributed without meeting these requirements.
🚫 Prohibited
Redistribution is NOT allowed under any circumstances. These endpoints contain Nansen's most sensitive proprietary data and competitive advantages.
Do not:
Display this data in any public or customer-facing interface
Use this data to build competing products
Redistribute this data through APIs, exports, or any other means
Internal use only: You may use this data for your own internal analysis, but not share it externally.
What is "Significant Modification"?
To redistribute smart money data, you must transform it substantially so that:
Not Directly Traceable: The output cannot be reverse-engineered to reveal Nansen's underlying smart money classifications, wallet lists, or raw activity data
Meaningfully Combined: The data must be integrated with at least one other substantial, independent data source (not just cosmetic additions)
Novel Insights: Your final output must provide unique analysis or value-add beyond what Nansen already offers
✅ ALLOWED Use Cases (with approval)
1. AI Agent Background Analysis
Using smart money data as one input among multiple sources to generate unique analytical responses.
✓ Good Example:
🚫 PROHIBITED Use Cases
1. Direct Display Dashboards
Any interface where Nansen's smart money data is shown without substantial transformation.
Examples of what NOT to do:
Requesting Approval for Restricted Endpoints
Step 1: Submit Your Request
Complete the approval form:
Step 2: Provide Required Information
Describe your product, how you'll use the data, and your target audience
Explain modifications, other data sources, and provide mockups
Show unique insights and differentiation from Nansen's products
Attribution Guidelines
When Attribution is Required
Required for endpoints marked "✅ Allowed (with attribution)" or "⚠️ Restricted".
How to Attribute
Choose one:
Text: "Powered by Nansen API" or similar, displayed near the data
Logo: Nansen logo with link to
Footer: "Blockchain analytics powered by "
When Attribution is NOT Required
Personal or internal use only
Endpoints marked "✅ Allowed" (no attribution noted)
General Rules & Compliance
1. Terms of Service
Must comply with Nansen's
2. Stay Updated
Check latest guidelines before launching products, changing data usage, or entering new markets
3. API & MCP Coverage
Rules apply to API responses, MCP tools, and derived data
4. Volume & Rate Limits
Redistribution doesn't exempt you from rate limits
5. Data Accuracy
Don't misrepresent data
Include appropriate disclaimers
Don't make unwarranted guarantees
6. Competitive Use
Don't build competing products
Don't use Nansen data as foundation for competitor services
Don't repackage data to commoditize Nansen's insights
Developer activity (25%)
Smart money wallet comparison tools
Automated smart money trade copying services
wallet_pnl_for_token
✅ Allowed
None
wallet_pnl_summary
✅ Allowed
None
address_transactions
✅ Allowed
Attribution required
address_related_addresses
✅ Allowed
Attribution required
address_counterparties
✅ Allowed
Attribution required
address_transactions_for_token
✅ Allowed
Attribution required
token_transfers
✅ Allowed
Attribution required
token_who_bought_sold
✅ Allowed
Attribution required
token_flows
✅ Allowed
Attribution required
token_recent_flows_summary
✅ Allowed
Attribution required
token_jup_dca
✅ Allowed
Attribution required
token_exchange_transactions
✅ Allowed
Attribution required
token_discovery_screener
✅ Allowed
Attribution required
token_current_top_holders
⚠️ Restricted
Approval + Significant Modification
token_pnl_leaderboard
🚫 Prohibited
Not permitted
✅ Allowed
None
profiler/address/pnl & pnl-summary
✅ Allowed
None
profiler/address/historical-balances
✅ Allowed
None
tgm/transfers
✅ Allowed
Attribution required
profiler/address/transactions
✅ Allowed
Attribution required
profiler/address/counterparty
✅ Allowed
Attribution required
profiler/address/related-wallets
✅ Allowed
Attribution required
tgm/token-screener
✅ Allowed
Attribution required
tgm/perp-screener
✅ Allowed
Attribution required
tgm/dex-trades
✅ Allowed
Attribution required
tgm/perp-trades
✅ Allowed
Attribution required
tgm/who-bought-sold
✅ Allowed
Attribution required
tgm/flow-intelligence
✅ Allowed
Attribution required
tgm/flows
✅ Allowed
Attribution required
tgm/holders (with smart money filter)
⚠️ Restricted
Approval + Significant Modification
tgm/perp-positions (with smart money filter)
⚠️ Restricted
Approval + Significant Modification
smart-money/inflows
⚠️ Restricted
Approval + Significant Modification
Prohibited Endpoints
address/labels
🚫 Prohibited
Not permitted
smart-money/holdings
🚫 Prohibited
Not permitted
tgm/pnl-leaderboard
🚫 Prohibited
Not permitted
perp-leaderboard
🚫 Prohibited
Not permitted
smart-money/dex-trades
🚫 Prohibited
Not permitted
smart-money/dcas
🚫 Prohibited
Not permitted
smart-money/perp-trades
🚫 Prohibited
Not permitted
Research reports examining flow intelligence patterns across tokens
Your AI agent analyzes: Nansen smart money flows (30%) + on-chain volume metrics (30%) + social sentiment analysis (20%) + technical indicators (20%) → generates custom investment thesis that synthesizes all sources
✗ Bad Example:
Your AI agent says: "Smart money wallets bought 5M tokens in the last 24 hours according to Nansen data"
2. Custom Composite Indicators
Building proprietary trading signals that incorporate smart money data alongside other metrics.
✓ Good Example:
A "Token Momentum Score" (0-100) that combines:
Smart money net flow (25%)
DEX liquidity depth (25%)
Price action volatility (25%)
Developer activity (25%)
✗ Bad Example:
A "Smart Money Activity Index" that's just a reformatted version of Nansen's smart money inflow data
3. Research Reports & Analysis
Periodic research that synthesizes smart money trends with broader market context.
The Nansen API supports 37 blockchain networks across EVM and non-EVM ecosystems. Chain support varies by endpoint.
EVM Chains
EVM-compatible chains use the standard Ethereum address format (0x + 40 hex characters).
Chain
Value
Description
Non-EVM Chains
Non-EVM chains have unique address formats. See Address Formats for details.
Chain
Value
Description
Using the "all" Chain
Some endpoints support "all" to query across all supported chains:
This expands to all chains supported by that specific endpoint.
Chain Support by Endpoint
Not all chains are available on all endpoints. Here's the support matrix:
Smart Money Endpoints
Chain
Netflow
DEX Trades
Holdings
Historical
Token God Mode Endpoints
Chain
Flows
Transfers
Holders
PnL
Profiler Endpoints
Chain
Balance
Transactions
PnL
Related
Examples
Single Chain Query
Multi-Chain Query
All Chains Query
Chain-Specific Considerations
Solana
Uses base58 addresses
Transaction lookup not supported
Full support for Smart Money and TGM
Bitcoin
Limited endpoint support (Profiler only)
Supports P2PKH, P2SH, and Bech32 addresses
No Smart Money or TGM support
TON
Uses EQ.../UQ... address format
Addresses are automatically normalized
No PnL endpoints
Hyperliquid
Perpetuals platform only
Used for perp-specific endpoints
No standard token endpoints
avalanche
Avalanche C-Chain
Base
base
Coinbase L2
Bitlayer
bitlayer
Bitcoin L2
BNB Chain
bnb
BNB Smart Chain
Celo
celo
Celo network
Chiliz
chiliz
Chiliz Chain
Gravity
gravity
Gravity network
HyperEVM
hyperevm
Hyperliquid EVM
IOTA EVM
iotaevm
IOTA EVM
Linea
linea
Linea L2
Mantle
mantle
Mantle L2
Monad
monad
Monad network
Optimism
optimism
Optimism L2
Plasma
plasma
Plasma network
Polygon
polygon
Polygon PoS
Ronin
ronin
Ronin sidechain
Scroll
scroll
Scroll L2
Sei
sei
Sei EVM
Sonic
sonic
Sonic network
Unichain
unichain
Uniswap L2
Viction
viction
Viction (TomoChain)
zkSync
zksync
zkSync Era
bitcoin
Bitcoin network
Hyperliquid
hyperliquid
Hyperliquid DEX (perpetuals only)
NEAR
near
NEAR Protocol
Solana
solana
Solana network
Stacks
stacks
Stacks (Bitcoin L2)
Starknet
starknet
Starknet L2
Stellar
stellar
Stellar network
SUI
sui
SUI network
TON
ton
The Open Network
Tron
tron
Tron network
Yes
Yes
Yes
Yes
base
Yes
Yes
Yes
Yes
bnb
Yes
Yes
Yes
Yes
arbitrum
Yes
Yes
Yes
No
polygon
Yes
Yes
Yes
No
avalanche
Yes
Yes
Yes
No
optimism
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
base
Yes
Yes
Yes
Yes
bnb
Yes
Yes
Yes
Yes
arbitrum
Yes
Yes
Yes
Yes
ton
Yes
Yes
Yes
No
tron
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
bitcoin
Yes
Yes
No
No
ton
Yes
Yes
No
Yes
tron
Yes
Yes
No
Yes
Ethereum
ethereum
Main Ethereum network
Arbitrum
arbitrum
Arbitrum One L2
Algorand
algorand
Algorand network
Aptos
aptos
Aptos network
ethereum
Yes
Yes
Yes
Yes
ethereum
Yes
Yes
Yes
Yes
ethereum
Yes
Yes
Yes
Yes
Avalanche
Bitcoin
solana
solana
solana
{
"chains": ["all"]
}
{
"chains": ["ethereum"]
}
{
"chains": ["ethereum", "solana", "base"]
}
{
"chains": ["all"]
}
Get TGM Perp Trades Data
post
Retrieve perpetual trade data for a specific token on Hyperliquid. Shows individual trades with detailed information including trader address, trade side (Long/Short), action type (Add/Reduce/Open/Close), order type (Market/Limit), and trade metrics.
Key Features:
Hyperliquid perpetual contracts only
Smart money filtering capabilities
Detailed trade breakdown with parsed action fields
Request Parameters:
token_symbol: Token symbol to fetch trades for (e.g., "BTC", "ETH")
date: Date range for the trades
filters: Additional filters for side, action, order_type, etc.
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/tgm/perp-trades
Get Smart Money Perpetual Trades Data
post
Access real-time perpetual trading activity from smart traders and funds on Hyperliquid. This endpoint provides granular transaction-level data showing exactly what sophisticated traders are trading on perpetual contracts.
Key Features:
Hyperliquid perpetual contracts only (no chain field needed)
Real-time trading data from smart money wallets
Detailed trade information including coin, amount, price, action, and type
Smart money filtering capabilities
Type filtering (Market/Limit)
Only new positions filter to show only position opening trades (defaults to false - shows all trades)
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/smart-money/perp-trades
Get Smart Money Historical Holdings Data
post
Retrieve historical snapshots of aggregated token balances held by smart traders and funds. This endpoint provides time-series data for trend analysis, backtesting, and performance attribution.
Key Features:
Daily snapshots of smart money holdings
Date range filtering (max 4 years lookback)
Point-in-time pricing and market cap data
Balance change tracking between snapshots
Same filtering options as current holdings endpoint
Use Cases:
Trend Analysis: Track how smart money rotates between assets over time
Performance Attribution: Combine with price data to estimate ROI
Backtesting: Validate trading strategies based on historical smart money behavior
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/smart-money/historical-holdings
Get TGM Who Bought/Sold Data
post
This endpoint provides an aggregated summary of trade volumes in USD for addresses. It can be used to identify addresses that are net buyers or sellers of a token within a time period.
Authorizations
apiKeystringRequired
API key for authentication
Body
Responses
200
TGM who bought/sold data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
The aggregate bought volume in USD for the address
Example: 25000
numberOptional
sold_volume_usdany ofOptional
The aggregate sold volume in USD for the address
Example: 12500
numberOptional
trade_volume_usdany ofOptional
The net trade volume in USD for the address
Example: 12500
numberOptional
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/tgm/who-bought-sold
Get TGM PnL Leaderboard Data
post
Rank traders by their profit/loss performance for a specific token. Shows both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages and trading patterns. This endpoint can be used to analyze the realized and unrealized profit for each trader who traded the input token.
Label Tier Control (premium_labels): The premium_labels parameter is now available to all users. When omitted, it defaults to true (premium labels). In a future release, the default will change to false. Pass premium_labels=true explicitly to preserve premium label behavior.
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/tgm/pnl-leaderboard
Get Address Related Wallets Data
post
Get wallets that are related to the input address through various types of blockchain interactions and relationships. Returns detailed information about each related wallet including the relationship type, transaction details, and timing information.
Custom sort order to override the endpoint's default ordering
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
Responses
200
Address related wallets data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
addressstringRequired
Hexadecimal representation of the related address
address_labelany ofOptional
The label of the address
stringOptional
relationstringRequired
The type of relation between the address and the input address
transaction_hashstringRequired
Hexadecimal representation of the transaction hash
block_timestampstringRequired
The timestamp of the transaction
orderintegerRequired
The order of the relation
chainstringRequired
The chain of the relation
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/profiler/address/related-wallets
Get Address Transactions Data
post
Retrieve recent blockchain transactions for an address including token transfers, native currency movements, and contract interactions.
Authorizations
apiKeystringRequired
API key for authentication
Body
Responses
200
Address transaction data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
chainstringRequired
Blockchain chain
methodstringRequired
Transaction method (sent/received)
tokens_sentany ofOptional
Tokens sent in the transaction
token_symbolstringRequired
Token symbol
token_amountnumberRequired
Token amount
price_usdany ofOptional
Token price in USD
numberOptional
value_usdany ofOptional
Token value in USD
numberOptional
token_addressstringRequired
Token contract address
chainstringRequired
Blockchain chain
from_addressstringRequired
Source address
to_addressstringRequired
Destination address
from_address_labelany ofOptional
Source address label
stringOptional
to_address_labelany ofOptional
Destination address label
stringOptional
tokens_receivedany ofOptional
Tokens received in the transaction
token_symbolstringRequired
Token symbol
token_amountnumberRequired
Token amount
price_usdany ofOptional
Token price in USD
numberOptional
value_usdany ofOptional
Token value in USD
numberOptional
token_addressstringRequired
Token contract address
chainstringRequired
Blockchain chain
from_addressstringRequired
Source address
to_addressstringRequired
Destination address
from_address_labelany ofOptional
Source address label
stringOptional
to_address_labelany ofOptional
Destination address label
stringOptional
volume_usdany ofOptional
Transaction volume in USD
numberOptional
block_timestampstringRequired
Block timestamp in ISO format
transaction_hashstringRequired
Transaction hash in hex format
source_typestringRequired
Transaction source type
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/profiler/address/transactions
Get Transaction with Token Transfer Lookup Data
post
Get comprehensive transaction information including token transfers and NFT transfers. This endpoint provides detailed information about a specific transaction including native cryptocurrency movements, token transfers, and NFT transfers with USD values.
Transaction lookup data with token and NFT transfer information
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
chainstringRequired
The blockchain network of the transaction
transaction_hashstringRequired
The unique identifier of the transaction
from_addressstringRequired
The hexadecimal address of the sender
from_address_labelany ofRequired
The name or label associated with the sender's address
stringOptional
to_addressstringRequired
The hexadecimal address of the recipient
to_address_labelany ofRequired
The name or label associated with the recipient's address
stringOptional
native_valueany ofRequired
The amount of native cryptocurrency transferred
numberOptional
dated_native_priceany ofRequired
The price of the native cryptocurrency at the time of the transaction
numberOptional
dated_native_value_usdany ofRequired
The USD value of the native cryptocurrency transferred at the time of the transaction
numberOptional
current_native_priceany ofRequired
The current price of the native cryptocurrency
numberOptional
current_native_value_usdany ofRequired
The current USD value of the native cryptocurrency transferred
numberOptional
receipt_statusany ofRequired
The status of the transaction receipt (1 for success, 0 for failure)
integerOptional
block_timestampstringRequired
The timestamp of the block in which the transaction was included
token_transfer_arrayany ofRequired
Information about any token transfers associated with this transaction
from_addressstringRequired
From address
from_address_labelstringRequired
From address label
to_addressstringRequired
To address
to_address_labelstringRequired
To address label
token_addressstringRequired
Token contract address
token_symbolstringRequired
Token symbol
token_amountnumberRequired
Token amount transferred
dated_price_usdany ofRequired
Price of the token in USD at the time of the transaction
numberOptional
dated_value_usdany ofRequired
USD value of the token transferred at the time of the transaction
numberOptional
current_price_usdany ofRequired
Current price of the token in USD
numberOptional
current_value_usdany ofRequired
Current USD value of the token transferred
numberOptional
transfer_idstringRequired
Transfer ID
nft_transfer_arrayany ofRequired
Information about any NFT transfers associated with this transaction
from_addressstringRequired
From address
from_address_labelstringRequired
From address label
to_addressstringRequired
To address
to_address_labelstringRequired
To address label
project_idstringRequired
Project ID
collection_namestringRequired
Collection name
nft_idstringRequired
NFT ID
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/transaction-with-token-transfer-lookup
Get TGM Transfers Data
post
Track all token transfer activity including direct transfers, DEX trades, and CEX movements. This endpoint is particularly useful for monitoring exchange flows - both centralized (CEX) and decentralized (DEX) - to identify accumulation or distribution patterns.
Authorizations
apiKeystringRequired
API key for authentication
Body
Responses
200
TGM transfers data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Type filter - 'token' for tokens only, 'entity' for entities only, 'any' for both.
Default: anyPossible values:
chainany ofOptional
Optional chain filter to narrow down token results (e.g., 'ethereum', 'solana', 'base').
Example: ethereum
stringOptional
limitinteger · min: 1 · max: 50Optional
Maximum number of results to return (default: 25, max: 50).
Default: 25
post
/api/v1/search/general
Get Perpetual Positions Data
post
Get perpetual positions data for a user by calling the Hyperliquid API directly. This endpoint provides real-time position information including entry price, mark price, PnL, leverage, and other position details.
What it helps to answer:
What are the current perpetual positions for a specific user address?
What is the unrealized PnL and performance of each position?
What are the leverage levels and margin requirements for each position?
What are the liquidation prices and risk levels for each position?
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/profiler/perp-positions
Get Smart Money DCAs Data
post
Monitor DCA strategies employed by smart money on Solana through Jupiter DCA. This endpoint reveals systematic accumulation strategies used by smart money.
Authorizations
apiKeystringRequired
API key for authentication
Body
Responses
200
Smart money DCAs data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
dca_created_atstringRequired
The timestamp of the earliest transaction
dca_updated_atstringRequired
The timestamp of the latest transaction
trader_addressstringRequired
The address of the trader
transaction_hashstringRequired
The transaction hash at the time of creation
trader_address_labelstringRequired
Label associated with the address
dca_vault_addressstringRequired
The address of the DCA vault
input_token_addressstringRequired
Address of token
output_token_addressstringRequired
Address of token
deposit_token_amountany ofOptional
The amount deposited into the DCA vault
numberOptional
token_spent_amountany ofOptional
The amount spent from the deposit
numberOptional
output_token_redeemed_amountany ofOptional
The amount of other tokens redeemed
numberOptional
dca_statusstringRequired
Indicates if the account was closed or active
input_token_symbolstringRequired
The symbol of the input token
output_token_symbolstringRequired
The symbol of the output token
deposit_value_usdany ofOptional
The USD value of the deposit
numberOptional
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/smart-money/dcas
Fast Research Agent
post
Ask the Nansen AI agent a research question and receive a streamed answer backed by on-chain data. The fast variant uses a lighter model optimised for low-latency responses.
What it helps to answer:
Which tokens are smart money accumulating right now?
What is the current narrative driving activity in DeFi?
Which wallets are connected to a specific address?
What is the on-chain story behind a recent price move?
SSE event types:
The response is a text/event-stream with the following JSON event types:
type
payload
description
The stream terminates with a data: [DONE] sentinel.
Fast vs Expert: Use /agent/fast for quick factual lookups and simple questions. Use /agent/expert when you need deeper multi-step analysis or synthesis across multiple data sources.
Authorizations
apiKeystringRequired
API key for authentication
Body
Request model for Agent Research endpoints (fast and expert).
textstring · min: 1Required
Research query or question for the Nansen AI agent.
Example: Which tokens are whales accumulating on Ethereum this week?
conversation_idany ofOptional
Optional conversation ID for multi-turn interactions. Returned in the finish event of a previous response. Omit to start a new conversation.
Example: conv_abc123
stringOptional
Responses
200
Server-Sent Events stream. Each event is a data: {json} line. See endpoint description for event schema.
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
Responseany
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/agent/fast
Expert Research Agent
post
Ask the Nansen AI agent a research question and receive a streamed answer backed by on-chain data. The expert variant uses a more capable model for deeper, multi-step analysis.
What it helps to answer:
Which tokens are smart money accumulating right now?
What is the current narrative driving activity in DeFi?
Which wallets are connected to a specific address?
What is the on-chain story behind a recent price move?
SSE event types:
The response is a text/event-stream with the following JSON event types:
type
payload
description
The stream terminates with a data: [DONE] sentinel.
Fast vs Expert: Use /agent/fast for quick factual lookups and simple questions. Use /agent/expert when you need deeper multi-step analysis or synthesis across multiple data sources.
Authorizations
apiKeystringRequired
API key for authentication
Body
Request model for Agent Research endpoints (fast and expert).
textstring · min: 1Required
Research query or question for the Nansen AI agent.
Example: Which tokens are whales accumulating on Ethereum this week?
conversation_idany ofOptional
Optional conversation ID for multi-turn interactions. Returned in the finish event of a previous response. Omit to start a new conversation.
Example: conv_abc123
stringOptional
Responses
200
Server-Sent Events stream. Each event is a data: {json} line. See endpoint description for event schema.
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
Responseany
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/agent/expert
Search for Entity Names
post
Search for entity names to use in other v1 endpoints that support entity_name parameters.
This endpoint helps users find the correct entity name format when they want to query by entity instead of address. Many endpoints accept either address or entity_name as parameters, but entity names must match exactly. This search endpoint makes it easy to find the right entity name.
Key Features:
Case-insensitive search that matches anywhere in the entity name
Returns up to 100 results ordered alphabetically
Minimum 2 character search query required
Use Cases:
Find entity names for profiler endpoints: Search "vitalik" to find "Vitalik Buterin" for use in address balance or transaction queries
Discover exchange entities: Search "binance" to find all Binance-related entities
Locate fund entities: Search "jump" to find "Jump Trading" and related entities
Example Usage:
Response:
Note: This endpoint does not support pagination as results are capped at 100 items.
Authorizations
apiKeystringRequired
API key for authentication
Body
Request model for entity name search endpoint.
This endpoint helps users find the correct entity_name to use in other
v1 endpoints that accept entity_name as a parameter.
search_querystring · min: 2Required
Search query for entity names (minimum 2 characters). Search is case-insensitive and matches anywhere in the entity name.
Example: vitalik
Responses
200
List of matching entity names
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
entity_namestringRequired
Entity name that can be used in other v1 endpoints
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/search/entity-name
Get Address PnL Summary Data
post
Get aggregate PnL statistics and top profitable tokens for a specific wallet address. This endpoint provides comprehensive profit and loss analysis including realized PnL, win rate, and top performing tokens.
Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)
Example: 2025-01-01T00:00:00Z
stringOptional
toany ofOptional
End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)
Example: 2025-01-31T23:59:59Z
stringOptional
Responses
200
Address PnL summary data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
realized_pnlany ofRequired
Realized profit and loss in USD
numberOptional
realized_roiany ofRequired
Realized return on investment as percentage
numberOptional
token_addressstringRequired
Token contract address
token_symbolstringRequired
Token symbol
chainstringRequired
Blockchain chain
traded_token_countintegerRequired
Total number of different tokens that have been bought or sold
traded_timesintegerRequired
Total number of sales (outflow or dex sell)
realized_pnl_usdnumberRequired
Total realized profit and loss in USD
realized_pnl_percentnumberRequired
Realized profit and loss as a percentage (not multiplied by 100)
win_ratenumberRequired
Number of sales where price of the token was higher than cost basis
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/profiler/address/pnl-summary
Get Address PnL Data
post
Calculate profit and loss metrics for a specific address and token. Provides detailed trading performance including realized gains from sales and unrealized gains from current holdings.
What it helps to answer:
Realized profits or losses from completed token sales
Unrealized gains or losses on current token holdings
Average purchase and sale prices for the token
Total return on investment
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/profiler/address/pnl
Get TGM Flow Intelligence Data
post
This endpoint provides comprehensive flow intelligence analytics, including inflows, outflows, and net flows for a specific token, broken down by various holder segments (Exchanges, Smart Money, Public Figures, Whales) with time-based statistics and trends. It can be used for identifying accumulation/distribution patterns across different holder segments.
Authorizations
apiKeystringRequired
API key for authentication
Body
Responses
200
TGM flow intelligence data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
public_figure_net_flow_usdany ofOptional
Net flow (USD) for addresses labeled as Public Figure
Example: 1000000.5
numberOptional
public_figure_avg_flow_usdany ofOptional
Geometric mean of absolute flow for Public Figure addresses
Example: 50000.25
numberOptional
public_figure_wallet_countany ofOptional
Unique wallet count for Public Figure addresses
Example: 10
integerOptional
top_pnl_net_flow_usdany ofOptional
Net flow (USD) for addresses labeled as Top PnL
Example: 2000000.75
numberOptional
top_pnl_avg_flow_usdany ofOptional
Geometric mean of absolute flow for Top PnL addresses
Example: 100000.5
numberOptional
top_pnl_wallet_countany ofOptional
Unique wallet count for Top PnL addresses
Example: 15
integerOptional
whale_net_flow_usdany ofOptional
Net flow (USD) for addresses labeled as Whale
Example: 5000000.25
numberOptional
whale_avg_flow_usdany ofOptional
Geometric mean of absolute flow for Whale addresses
Example: 250000.75
numberOptional
whale_wallet_countany ofOptional
Unique wallet count for Whale addresses
Example: 25
integerOptional
smart_trader_net_flow_usdany ofOptional
Net flow (USD) for addresses labeled as Smart Trader
Example: 1500000.5
numberOptional
smart_trader_avg_flow_usdany ofOptional
Geometric mean of absolute flow for Smart Trader addresses
Example: 75000.25
numberOptional
smart_trader_wallet_countany ofOptional
Unique wallet count for Smart Trader addresses
Example: 20
integerOptional
exchange_net_flow_usdany ofOptional
Net flow (USD) for addresses labeled as Exchange
Example: 3000000.75
numberOptional
exchange_avg_flow_usdany ofOptional
Geometric mean of absolute flow for Exchange addresses
Example: 150000.5
numberOptional
exchange_wallet_countany ofOptional
Unique wallet count for Exchange addresses
Example: 5
integerOptional
fresh_wallets_net_flow_usdany ofOptional
Net flow (USD) for fresh wallets. Only available for 1d and 7d timeframes.
Example: 500000.25
numberOptional
fresh_wallets_avg_flow_usdany ofOptional
Average absolute flow (USD) for fresh wallets. Only available for 1d and 7d timeframes.
Example: 25000.75
numberOptional
fresh_wallets_wallet_countany ofOptional
Fresh wallets wallet count. Only available for 1d and 7d timeframes.
Example: 100
integerOptional
warningsany ofOptional
Optional warnings about the query results. For example, if fresh_wallets fields are null due to timeframe constraints.
string[]Optional
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/tgm/flow-intelligence
Get TGM Jupiter DCA Data
post
This endpoint provides Jupiter DCA orders with stats per vault for a specific token. Jupiter DCA (Dollar Cost Averaging) is only available on Solana and allows users to automate token purchases over time. Returns comprehensive data about DCA vaults including deposit amounts, redemption status, and trader information.
Authorizations
apiKeystringRequired
API key for authentication
Body
Responses
200
TGM Jupiter DCA data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/tgm/jup-dca
Get TGM Perp Trades Data
post
Retrieve perpetual trade data for a specific token on Hyperliquid. Shows individual trades with detailed information including trader address, trade side (Long/Short), action type (Add/Reduce/Open/Close), order type (Market/Limit), and trade metrics.
Key Features:
Hyperliquid perpetual contracts only
Smart money filtering capabilities
Detailed trade breakdown with parsed action fields
Support for both Long and Short position trading
Market and Limit order types
Request Parameters:
token_symbol: Token symbol to fetch trades for (e.g., "BTC", "ETH")
date: Date range for the trades
filters: Additional filters for side, action, order_type, etc.
Authorizations
apiKeystringRequired
API key for authentication
Body
Request model for TGM perp trades endpoint.
This endpoint provides perp trades data for a specific token.
token_symbolstringRequired
Token symbol
Example: BTC
fromany ofOptional
Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)
Example: 2025-01-01T00:00:00Z
stringOptional
toany ofOptional
End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)
Get perpetual trade data for a user. This endpoint provides trade information including trade price, size, side, fees, and other trade details.
What it helps to answer:
What are the perpetual trades for a specific user address within a date range?
What are the trade prices, sizes, and directions for each trade?
What are the trading fees and closed PnL for each trade?
What are the order IDs and transaction hashes for trade tracking?
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/profiler/perp-trades
Get Perpetual Trading Leaderboard Data
post
Get perpetual trading leaderboard data showing the most profitable traders within a given date range. This endpoint provides trader performance metrics including total PnL, ROI, and account values.
What it helps to answer:
Who are the most profitable perpetual traders in a given timeframe?
What are the ROI percentages for top performing traders?
What are the account values of successful perpetual traders?
How do trader addresses and labels correlate with performance?
Key Features:
Trader address and label information
Total PnL tracking in USD
ROI calculations as percentages
Account value tracking
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/perp-leaderboard
Get Token OHLCV Data
post
Get unified OHLCV (Open, High, Low, Close, Volume) data for tokens across supported chains.
This endpoint unifies the legacy TGM prices endpoints (/tgm/prices/low-timeframe and /tgm/prices/high-timeframe) into a single endpoint with support for multiple timeframes:
Volume data: trading volume in token units and USD
Market cap data: market capitalization at each time point
Date range defaults to the last 30 days if not specified.
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/tgm/token-ohlcv
Get Address Labels
post
Get labels for a wallet address. Returns non-premium labels only.
Labels include ENS domains, behavioral labels, DeFi labels, CEX labels, and more. Premium labels (smart money, alpha trader) are excluded from this endpoint.
Use /api/v1/profiler/address/premium-labels to get all labels including premium ones.
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/profiler/address/premium-labels
Get TGM Perp Positions Data
post
Retrieve current perpetual positions for a specific token on Hyperliquid. Shows active positions with detailed metrics including entry price, mark price, leverage, PnL, and liquidation price.
Key Features:
Hyperliquid perpetual contracts only (no chain field needed)
Real-time position tracking with live PnL calculations
Leverage and margin information
Smart money filtering capabilities
Support for both Long and Short positions
What it helps to answer:
What are the current perp positions for a specific token?
Which addresses have the largest positions by value?
What are the unrealized gains/losses on current positions?
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/tgm/perp-positions
Get Smart Money Perpetual Trades Data
post
Access real-time perpetual trading activity from smart traders and funds on Hyperliquid. This endpoint provides granular transaction-level data showing exactly what sophisticated traders are trading on perpetual contracts.
Key Features:
Hyperliquid perpetual contracts only (no chain field needed)
Real-time trading data from smart money wallets
Detailed trade information including coin, amount, price, action, and type
Smart money filtering capabilities
Type filtering (Market/Limit)
Only new positions filter to show only position opening trades (defaults to false - shows all trades)
Authorizations
apiKeystringRequired
API key for authentication
Body
filtersany ofOptional
Additional filters to apply. Only filters for columns that are being selected will be applied.
Action filter - combined buy/sell with position action (e.g., 'Buy - Add Long', 'Sell - Open Short')
Example: Buy - Add Long
string · enumOptional
Shared enum for perpetual trade action types (combined buy/sell with position actions).
Possible values:
or
itemsstring · enumOptional
Shared enum for perpetual trade action types (combined buy/sell with position actions).
Possible values:
or
nullOptional
premium_labelsany ofOptional
Controls label tier in the response. When null/omitted (default), returns labels as per subscription plan (existing behavior). When false, returns free-tier labels for all users. When true, returns premium labels (20 credits, currently available to internal users only).
booleanOptional
only_new_positionsany ofOptional
When True, includes 'Open' position actions (Open Long, Open Short). Can be combined with other action filters using OR logic (union). When False (default), returns all trades.
Default: falseExample: true
booleanOptional
pageinteger · min: 1Optional
Page number (1-based)
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page (max 1000)
Default: 10
order_byany ofOptional
Custom sort order to override the endpoint's default ordering.
Examples:
[{"field": "value_usd", "direction": "DESC"}] - Sort by trade value descending
[{"field": "block_timestamp", "direction": "ASC"}] - Sort by timestamp ascending
[{"field": "token_amount", "direction": "DESC"}, {"field": "block_timestamp", "direction": "ASC"}] - Sort by token amount descending, then timestamp ascending
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
post
/api/v1/smart-money/perp-trades
Get TGM DEX Trades Data
post
Access individual DEX trading transactions for a specific token. Shows detailed trade-by-trade data including trader labels, amounts, and prices.
Authorizations
apiKeystringRequired
API key for authentication
Body
Responses
200
TGM DEX trades data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
The name of the token traded for the specified token
Example: DAI
traded_token_amountany ofRequired
The amount of the token traded for the specified token
Example: 500
numberOptional
estimated_swap_price_usdany ofRequired
Estimated swap price in USD, derived from the counterpart token's USD value. Falls back to the daily median token price if the counterpart price is unavailable.
Example: 1
numberOptional
estimated_value_usdany ofRequired
The estimated value of the trade in USD
Example: 1500.5
numberOptional
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/tgm/dex-trades
Get Perpetual Contract Screening Data
post
Discover and screen perpetual contracts on Hyperliquid with advanced filtering capabilities. This endpoint helps identify trending perpetual contracts, trading activity, funding rates, and smart money movements by combining metrics like volume, open interest, funding rates, and position data.
What it helps to answer:
Which perpetual contracts are experiencing significant trading volume and activity?
How do funding rates correlate with trading patterns and smart money positions?
What perpetual contracts show strong fundamentals in terms of open interest and trading patterns?
Which perpetual contracts are attracting smart money participation with long/short positions?
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/perp-screener
Get TGM Perp PnL Leaderboard Data
post
Rank traders by their profit/loss performance for a specific perpetual contract on Hyperliquid. Shows both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages and trading patterns. This endpoint can be used to analyze the realized and unrealized profit for each trader who traded the input perpetual contract.
Key Features:
Hyperliquid perpetual contracts only (no chain field needed)
Realized and unrealized PnL tracking
ROI calculations and trading patterns
Position size and balance tracking
Request Format:
token_symbol: Perpetual contract symbol (e.g., "BTC", "ETH", "SOL")
date: Date range for analysis
filters: Optional filters for trader addresses, PnL ranges, etc.
Label Tier Control (premium_labels): The premium_labels parameter is now available to all users. When omitted, it defaults to true (premium labels). In a future release, the default will change to false. Pass premium_labels=true explicitly to preserve premium label behavior.
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/tgm/perp-pnl-leaderboard
Get Smart Money DEX Trades Data
post
Access real-time DEX trading activity from smart traders and funds over the last 24 hours. This endpoint provides granular transaction-level data showing exactly what sophisticated traders are buying and selling on decentralized exchanges.
Authorizations
apiKeystringRequired
API key for authentication
Body
Responses
200
Smart money DEX trades data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
chainstringRequired
Blockchain chain
block_timestampstringRequired
Block timestamp of the trade
transaction_hashstringRequired
Transaction hash
trader_addressstringRequired
Hexadecimal representation of the trader's address, i.e. the signer of the transaction
trader_address_labelstringRequired
Name of the trader, based on nansen_label
token_bought_addressstringRequired
Hexadecimal representation of the bought token's address
token_sold_addressstringRequired
Hexadecimal representation of the sold token's address
token_bought_amountany ofOptional
Amount of token bought in decimal amount
numberOptional
token_sold_amountany ofOptional
Amount of token sold in decimal amount
numberOptional
token_bought_symbolstringRequired
Symbol of the bought token
token_sold_symbolstringRequired
Symbol of the sold token
token_bought_age_daysintegerRequired
Age of bought token's address in days
token_sold_age_daysintegerRequired
Age of sold token's address in days
token_bought_market_capany ofOptional
Circulating market cap of bought token in USD. Returns NULL when circulating supply data is unavailable.
numberOptional
token_sold_market_capany ofOptional
Circulating market cap of sold token in USD. Returns NULL when circulating supply data is unavailable.
numberOptional
token_bought_fdvany ofOptional
Fully Diluted Valuation of bought token in USD (total_supply x price). May be very large for tokens with no circulating supply data.
numberOptional
token_sold_fdvany ofOptional
Fully Diluted Valuation of sold token in USD (total_supply x price). May be very large for tokens with no circulating supply data.
numberOptional
trade_value_usdany ofOptional
Either token_bought_in_usd or token_sold_in_usd, if token_bought_in_usd is 0
numberOptional
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/smart-money/dex-trades
Get TGM Perp Positions Data
post
Retrieve current perpetual positions for a specific token on Hyperliquid. Shows active positions with detailed metrics including entry price, mark price, leverage, PnL, and liquidation price.
Key Features:
Hyperliquid perpetual contracts only (no chain field needed)
Real-time position tracking with live PnL calculations
Leverage and margin information
Smart money filtering capabilities
Support for both Long and Short positions
What it helps to answer:
What are the current perp positions for a specific token?
Which addresses have the largest positions by value?
What are the unrealized gains/losses on current positions?
Authorizations
apiKeystringRequired
API key for authentication
Body
Request model for TGM perp positions endpoint.
This endpoint provides perp positions data for a specific token.
Custom sort order to override the endpoint's default ordering.
Examples:
[{"field": "position_value_usd", "direction": "DESC"}] - Sort by position value USD descending
[{"field": "upnl_usd", "direction": "ASC"}] - Sort by unrealized PnL ascending
[{"field": "leverage", "direction": "DESC"}] - Sort by leverage descending
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
post
/api/v1/tgm/perp-positions
Get TGM Token Information Data
post
Get comprehensive token information including basic details (name, symbol, contract address, logo), token details (deployment date, social links, market metrics like market cap and FDV), and spot trading metrics (volume, buys/sells, unique traders, liquidity, holders).
This endpoint provides a complete overview of a token's metadata, market position, and trading activity for a specific date range.
Authorizations
apiKeystringRequired
API key for authentication
Body
Request model for TGM token information endpoint.
This endpoint provides comprehensive token information including basic details,
token details (deployment, social links, market metrics), and spot trading metrics.
Token details including deployment, social links, and market metrics
token_deployment_dateany ofOptional
Token deployment date in ISO format
Example: 2020-11-05T00:00:00Z
stringOptional
websiteany ofOptional
Token website URL
Example: https://aave.com
stringOptional
xany ofOptional
X (Twitter) profile URL
Example: https://x.com/aave
stringOptional
telegramany ofOptional
Telegram channel URL
Example: https://t.me/Aavesome
stringOptional
market_cap_usdany ofOptional
Market capitalization in USD
Example: 4690000000
numberOptional
fdv_usdany ofOptional
Fully diluted valuation in USD
Example: 4930000000
numberOptional
circulating_supplyany ofOptional
Circulating supply of the token
Example: 15230000
numberOptional
total_supplyany ofOptional
Total supply of the token
Example: 16000000
numberOptional
spot_metricsany ofOptional
Spot trading metrics for the token
volume_total_usdany ofOptional
Total trading volume in USD
Example: 8850000
numberOptional
buy_volume_usdany ofOptional
Total buy volume in USD
Example: 4520000
numberOptional
sell_volume_usdany ofOptional
Total sell volume in USD
Example: 4330000
numberOptional
total_buysany ofOptional
Total number of buy transactions
Example: 666
integerOptional
total_sellsany ofOptional
Total number of sell transactions
Example: 499
integerOptional
unique_buyersany ofOptional
Number of unique buyers
Example: 106
integerOptional
unique_sellersany ofOptional
Number of unique sellers
Example: 132
integerOptional
liquidity_usdany ofOptional
Liquidity in USD
Example: 153420000
numberOptional
total_holdersany ofOptional
Total number of token holders
Example: 165299
integerOptional
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/tgm/token-information
Get Token Screening Data
post
Discover and screen tokens across multiple blockchains with advanced filtering capabilities. This endpoint helps identify trending tokens, new launches, and smart money movements by combining metrics like volume, liquidity, market cap, and trading activity.
What it helps to answer:
Which tokens are experiencing significant smart money activity across different chains?
How do market metrics (price, volume, liquidity) correlate with holder behavior and smart money movements?
What tokens show strong fundamentals in terms of holder distribution and trading patterns?
Which emerging tokens are attracting fresh wallet inflows while maintaining healthy smart money participation?
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/token-screener
Get TGM Flows Data
post
Analyze aggregated token flows by holder category over time. Shows hourly snapshots of balances, inflows, and outflows for specific holder groups: smart money, public figures, whales, and exchanges.
Authorizations
apiKeystringRequired
API key for authentication
Body
Responses
200
TGM flows data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
datestringRequired
Block date of the flow data point
price_usdany ofOptional
Daily median token price in USD. For the current day, uses the latest spot price.
numberOptional
token_amountany ofOptional
Total token amount
numberOptional
value_usdany ofOptional
Total token value in USD
numberOptional
holders_countany ofOptional
Number of token holders
integerOptional
total_inflows_countany ofOptional
Total inflows
numberOptional
total_outflows_countany ofOptional
Total outflows
numberOptional
total_inflows_dexany ofOptional
Total DEX inflows (token amount). Only populated when label=exchange, null otherwise.
numberOptional
total_outflows_dexany ofOptional
Total DEX outflows (token amount). Only populated when label=exchange, null otherwise.
numberOptional
total_inflows_cexany ofOptional
Total CEX inflows (token amount). Only populated when label=exchange, null otherwise.
numberOptional
total_outflows_cexany ofOptional
Total CEX outflows (token amount). Only populated when label=exchange, null otherwise.
numberOptional
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
post
/api/v1/tgm/flows
Get TGM Holders Data
post
Retrieve the top token holders with their current balances, historical activity, and recent balance changes. Provides insights into token distribution, smart money and fund holdings.
Performance Optimization for Native Tokens: When querying native tokens with label_type: "all_holders", this endpoint uses an optimized model to prevent timeouts. This optimization has the following limitations:
Ordering: Only token_amount field is supported
Filters: Limited to: token_amount, total_outflow, total_inflow, address, include_smart_money_labels
To use advanced filters and ordering on native tokens, specify a label_type other than "all_holders" (e.g., "smart_money", "whale", "exchange").
Label Tier Control (premium_labels): The premium_labels parameter is now available to all users. When omitted, it defaults to true (premium labels). In a future release, the default will change to false. Pass premium_labels=true explicitly to preserve premium label behavior.
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/tgm/holders
Get Address Counterparties Data
post
Get top counterparties that wallet addresses have interacted with, supporting different grouping options (wallet or entity) and source filtering (Combined, Tokens, ETH). Returns interaction statistics including volume, frequency, and timing data.
What it helps to answer:
Most frequent transaction partners by count and volume
Net value flows between addresses (inflows vs outflows)
Exchange and protocol interaction patterns
DeFi protocol usage and DEX trading counterparties
High-value transfer relationships and funding sources
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/profiler/address/counterparties
Get Address Historical Balances Data
post
Track token and native coin balance changes over time for addresses or entities. Provides snapshots at configurable intervals to analyze holding patterns, transaction activity, and portfolio evolution across multiple blockchains.
What it helps to answer:
Portfolio value changes across different time periods
Token accumulation and distribution patterns over selected timeframes
New positions entered and exited during specific periods
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/profiler/address/historical-balances
Get Perpetual Contract Screening Data
post
Discover and screen perpetual contracts on Hyperliquid with advanced filtering capabilities. This endpoint helps identify trending perpetual contracts, trading activity, funding rates, and smart money movements by combining metrics like volume, open interest, funding rates, and position data.
What it helps to answer:
Which perpetual contracts are experiencing significant trading volume and activity?
How do funding rates correlate with trading patterns and smart money positions?
What perpetual contracts show strong fundamentals in terms of open interest and trading patterns?
Which perpetual contracts are attracting smart money participation with long/short positions?
Authorizations
apiKeystringRequired
API key for authentication
Body
Request model for Perp Screener endpoint.
fromany ofOptional
Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)
Example: 2025-01-01T00:00:00Z
stringOptional
toany ofOptional
End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)
Sort fields available for default perp screener data (only_smart_money=False).
Possible values:
or
string · enumOptional
Sort fields available for smart money perp screener data (only_smart_money=True).
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
post
/api/v1/perp-screener
Get Smart Money Holdings Data
post
Retrieve aggregated token balances held by smart traders and funds across multiple blockchains. This endpoint provides insights into what tokens are being accumulated by sophisticated market participants, excluding whales, large holders, and influencers to focus specifically on trading expertise.
Key Features:
Aggregated balances (not per-wallet breakdowns)
24-hour balance change tracking updated in realtime
Sector categorization for tokens
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/smart-money/holdings
Get Perpetual Trading Leaderboard Data
post
Get perpetual trading leaderboard data showing the most profitable traders within a given date range. This endpoint provides trader performance metrics including total PnL, ROI, and account values.
What it helps to answer:
Who are the most profitable perpetual traders in a given timeframe?
What are the ROI percentages for top performing traders?
What are the account values of successful perpetual traders?
How do trader addresses and labels correlate with performance?
Key Features:
Trader address and label information
Total PnL tracking in USD
ROI calculations as percentages
Account value tracking
Authorizations
apiKeystringRequired
API key for authentication
Body
Request model for Perp Leaderboard endpoint.
This endpoint provides a perpetual trading leaderboard showing the most profitable
traders within a given date range.
Filter by wallet display name. Use LIKE patterns (%) for partial matching. Note: This filters by the wallet's display name, not by label category. To filter by smart money labels, use include_smart_money_labels instead.
Example: %Smart HL Perps Trader%
stringOptional
or
string[]Optional
or
nullOptional
total_pnlany ofOptional
Total PnL range filter in USD
Example: {"min":1000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
roiany ofOptional
ROI range filter as percentage
Example: {"max":100,"min":10}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
account_valueany ofOptional
Account value range filter in USD. Note: Only the top 500K traders have account value data available.
Example: {"min":10000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
include_smart_money_labelsany ofOptional
Filter to include only traders with these smart money labels. For Hyperliquid, use 'Smart HL Perps Trader'. See SmartMoneyFilterType enum for valid values.
Example: ["Smart HL Perps Trader"]
itemsstring · enumOptional
Enum for smart money filter options.
Possible values:
exclude_smart_money_labelsany ofOptional
Exclude smart money labels
Example: ["30D Smart Trader"]
itemsstring · enumOptional
Enum for smart money filter options.
Possible values:
premium_labelsany ofOptional
Controls label tier in the response. When null/omitted (default), returns labels as per subscription plan (existing behavior). When false, returns free-tier labels for all users. When true, returns premium labels. Note: In a future release, the default will change from true to false — pass premium_labels=true explicitly to preserve premium label behavior.
booleanOptional
order_byany ofOptional
Custom sort order to override the endpoint's default ordering
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
post
/api/v1/perp-leaderboard
Get TGM Perp PnL Leaderboard Data
post
Rank traders by their profit/loss performance for a specific perpetual contract on Hyperliquid. Shows both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages and trading patterns. This endpoint can be used to analyze the realized and unrealized profit for each trader who traded the input perpetual contract.
Key Features:
Hyperliquid perpetual contracts only (no chain field needed)
Realized and unrealized PnL tracking
ROI calculations and trading patterns
Position size and balance tracking
Request Format:
token_symbol: Perpetual contract symbol (e.g., "BTC", "ETH", "SOL")
date: Date range for analysis
filters: Optional filters for trader addresses, PnL ranges, etc.
Label Tier Control (premium_labels): The premium_labels parameter is now available to all users. When omitted, it defaults to true (premium labels). In a future release, the default will change to false. Pass premium_labels=true explicitly to preserve premium label behavior.
Authorizations
apiKeystringRequired
API key for authentication
Body
Request model for TGM Perp PnL leaderboard endpoint.
Simplified version that only supports Hyperliquid perpetual contracts.
token_symbolstringRequired
Perpetual contract symbol (e.g., BTC, ETH, SOL)
Example: BTC
fromany ofOptional
Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)
Example: 2025-01-01T00:00:00Z
stringOptional
toany ofOptional
End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)
Position value range filter in USD (+ve = Long position, -ve = Short position, 0 = Flat)
Example: {"min":1000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
max_balance_heldany ofOptional
Maximum balance held range filter
Example: {"min":100}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
max_balance_held_usdany ofOptional
Maximum balance held range filter in USD
Example: {"min":1000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
still_holding_balance_ratioany ofOptional
Still holding balance ratio range filter
Example: {"max":1,"min":0.1}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
nof_tradesany ofOptional
Number of trades range filter
Example: {"max":100,"min":10}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
include_smart_money_labelsany ofOptional
Include smart money labels
Example: ["Fund","Smart Trader"]
itemsstring · enumOptional
Enum for smart money filter options.
Possible values:
exclude_smart_money_labelsany ofOptional
Exclude smart money labels
Example: ["30D Smart Trader"]
itemsstring · enumOptional
Enum for smart money filter options.
Possible values:
premium_labelsany ofOptional
Controls label tier in the response. When null/omitted (default), returns labels as per subscription plan (existing behavior). When false, returns free-tier labels for all users. When true, returns premium labels. Note: In a future release, the default will change from true to false — pass premium_labels=true explicitly to preserve premium label behavior.
booleanOptional
order_byany ofOptional
Custom sort order to override the endpoint's default ordering
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
post
/api/v1/tgm/perp-pnl-leaderboard
Get Address Current Balance Data
post
Retrieve current token holdings for addresses or entities. Returns detailed balance information across specified chains.
What it helps to answer:
Current token holdings with quantities and USD valuations
Asset distribution across different blockchain networks
Native token versus token balances
Stablecoin holdings and percentages
Cross-chain portfolio composition
Note: The address field in the response will be empty if entity_name is provided.
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/profiler/address/current-balance
Get Smart Money Netflow Data
post
Analyze net capital flows (inflows vs outflows) from smart traders and funds across different time periods. This endpoint helps identify which tokens are experiencing net accumulation or distribution by smart money.
What are Net Flows? Net flows represent the difference between smart money inflows and outflows for a token. This includes:
DEX Trading Activity: Tokens bought vs sold on decentralized exchanges
CEX Transfers: Tokens sent to or received from centralized exchanges
Positive Net Flow: Smart money is accumulating (buying more than selling, or withdrawing from CEXs)
Negative Net Flow: Smart money is distributing (selling more than buying, or depositing to CEXs)
Key Features:
Aggregated net flow calculations across all smart money activity
Multiple time period analysis (1h, 24h, 7d, 30d)
Sortable results by volume metrics
Authorizations
apiKeystringRequired
API key for authentication
Body
post
/api/v1/smart-money/netflow
Get Perpetual Trade Data
post
Get perpetual trade data for a user. This endpoint provides trade information including trade price, size, side, fees, and other trade details.
What it helps to answer:
What are the perpetual trades for a specific user address within a date range?
What are the trade prices, sizes, and directions for each trade?
What are the trading fees and closed PnL for each trade?
What are the order IDs and transaction hashes for trade tracking?
Authorizations
apiKeystringRequired
API key for authentication
Body
Request model for Perp Trades endpoint.
addressstring · min: 42 · max: 42Required
User's Hyperliquid address in 42-character hexadecimal format
Get perpetual positions data for a user by calling the Hyperliquid API directly. This endpoint provides real-time position information including entry price, mark price, PnL, leverage, and other position details.
What it helps to answer:
What are the current perpetual positions for a specific user address?
What is the unrealized PnL and performance of each position?
What are the leverage levels and margin requirements for each position?
What are the liquidation prices and risk levels for each position?
Authorizations
apiKeystringRequired
API key for authentication
Body
Request model for Perp Positions endpoint.
addressstring · min: 42 · max: 42Required
User's Hyperliquid address in 42-character hexadecimal format
Discover and screen tokens across multiple blockchains with advanced filtering capabilities. This endpoint helps identify trending tokens, new launches, and smart money movements by combining metrics like volume, liquidity, market cap, and trading activity.
What it helps to answer:
Which tokens are experiencing significant smart money activity across different chains?
How do market metrics (price, volume, liquidity) correlate with holder behavior and smart money movements?
What tokens show strong fundamentals in terms of holder distribution and trading patterns?
Which emerging tokens are attracting fresh wallet inflows while maintaining healthy smart money participation?
Authorizations
apiKeystringRequired
API key for authentication
Body
Request model for Token Screener endpoint.
Either 'timeframe' (recommended) or 'date' (deprecated) must be provided.
itemsstring · enumOptional
Chains supported for Token Screener endpoint.
Possible values:
timeframeany ofOptional
Required (unless using deprecated 'date' parameter).
Time window for token screening data.
Available timeframes and their data characteristics:
5m: Last 5 minutes (minute-level granularity, 2-hour retention)
10m: Last 10 minutes (minute-level granularity, 2-hour retention)
1h: Last 1 hour (minute-level granularity, 2-hour retention)
6h: Last 6 hours (hourly granularity, 2-day retention)
24h: Last 24 hours (hourly granularity, 2-day retention)
7d: Last 7 days (daily granularity, 2-month retention)
30d: Last 30 days (daily granularity, 2-month retention)
Cannot be used together with 'date'.
Example: 24h
string · enumOptional
Token screener timeframe options.
Defines the time window for token screening data.
Each timeframe corresponds to different data granularity and retention periods.
Matches the timeframe options in the Superapp token-screener widget.
Possible values:
dateany ofOptionalDeprecated
DEPRECATED: Use 'timeframe' instead for better reliability and performance.
Required only if 'timeframe' is not provided.
Custom date range for the token screener. The granularity is automatically determined from the date range:
≤ 1 hour: minute-level data (limited to last 2 hours)
1 hour to 1 day: hourly data (limited to last 2 days)
Deprecated: use trader_type instead. Whether to only include smart money tokens
Example: true
booleanOptional
trader_typeany ofOptional
Filter by trader type. Overrides only_smart_money when provided.
Example: sm
string · enumOptional
Trader type filter for token screener.
Possible values:
sectorsany ofOptional
Token sectors to include
Example: ["DeFi","Gaming"]
string[]Optional
token_age_daysany ofOptional
Token age range filter in days
Example: {"max":365,"min":1}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
market_cap_usdany ofOptional
Market cap range filter
Example: {"max":100000000,"min":1000000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
liquidityany ofOptional
Liquidity range filter
Example: {"min":100000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
price_usdany ofOptional
Current price range filter in USD
Example: {"max":1000,"min":0.01}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
price_changeany ofOptional
Price change percentage range filter
Example: {"max":100,"min":-50}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
fdvany ofOptional
Fully Diluted Valuation range filter
Example: {"min":1000000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
fdv_mc_ratioany ofOptional
FDV to Market Cap ratio range filter
Example: {"max":10,"min":1}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
nof_buyersany ofOptional
Number of unique buyers range filter
Example: {"min":10}
minany ofOptional
Minimum value (inclusive)
Example: 10
integerOptional
maxany ofOptional
Maximum value (inclusive)
Example: 100
integerOptional
nof_tradersany ofOptional
Number of unique traders range filter
Example: {"min":50}
minany ofOptional
Minimum value (inclusive)
Example: 10
integerOptional
maxany ofOptional
Maximum value (inclusive)
Example: 100
integerOptional
nof_sellersany ofOptional
Number of unique sellers range filter
Example: {"min":10}
minany ofOptional
Minimum value (inclusive)
Example: 10
integerOptional
maxany ofOptional
Maximum value (inclusive)
Example: 100
integerOptional
nof_buysany ofOptional
Number of buy transactions range filter
Example: {"min":20}
minany ofOptional
Minimum value (inclusive)
Example: 10
integerOptional
maxany ofOptional
Maximum value (inclusive)
Example: 100
integerOptional
nof_sellsany ofOptional
Number of sell transactions range filter
Example: {"min":20}
minany ofOptional
Minimum value (inclusive)
Example: 10
integerOptional
maxany ofOptional
Maximum value (inclusive)
Example: 100
integerOptional
buy_volumeany ofOptional
Buy volume range filter in USD
Example: {"min":10000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
sell_volumeany ofOptional
Sell volume range filter in USD
Example: {"min":10000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
volumeany ofOptional
Total trading volume range filter in USD
Example: {"min":50000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
netflowany ofOptional
Net flow range filter in USD
Example: {"max":100000,"min":-100000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
inflow_fdv_ratioany ofOptional
Inflow to FDV ratio range filter
Example: {"min":0.001}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
outflow_fdv_ratioany ofOptional
Outflow to FDV ratio range filter
Example: {"min":0.001}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
include_stablecoinsbooleanOptional
Whether to include stablecoins in token screener results. Default true preserves current behavior. Set to false to exclude USDC, USDT, DAI, and other major stablecoins.
Default: true
include_smart_money_labelsany ofOptional
Include smart money labels
Example: ["Public Figure","Exchange"]
itemsstring · enumOptional
Enum for smart money filter options.
Possible values:
exclude_smart_money_labelsany ofOptional
Exclude smart money labels
Example: ["Fund"]
itemsstring · enumOptional
Enum for smart money filter options.
Possible values:
order_byany ofOptional
Custom sort order to override the endpoint's default ordering.
Examples:
[{"field": "buy_volume", "direction": "DESC"}] - Sort by buy volume descending
[{"field": "price_change", "direction": "DESC"}] - Sort by price change descending
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
post
/api/v1/token-screener
Get Portfolio DeFi Holdings Data
post
Get simplified DeFi holdings for a wallet address with aggregated tokens and protocol summaries in a user-friendly format.
Authorizations
apiKeystringRequired
API key for authentication
Body
Request model for portfolio DeFi holdings endpoint.
The action taken by the trader (Add, Reduce, Open, Close)
Example: Add
token_amountany ofOptional
The amount of the specified token traded
Example: 1.5
numberOptional
price_usdany ofOptional
Average fill price in USD across all fills in the trade, from exchange data.
Example: 60000
numberOptional
value_usdany ofOptional
The value in USD
Example: 90000
numberOptional
typestring · enumRequired
The order type (MARKET or LIMIT)
Example: MARKETPossible values:
block_timestampstringRequired
The block timestamp for the transaction
Example: 2025-10-01T12:40:00Z
transaction_hashstringRequired
A representative transaction hash for this trade. Note: A single row may aggregate multiple fills that occurred at the same timestamp. If the trader had fills across multiple transactions at the exact same millisecond, only one transaction_hash is shown. The token_amount and value_usd reflect the total across all fills.
Action filter - combined buy/sell with position action (e.g., 'Buy - Add Long', 'Sell - Open Short')
Example: Buy - Add Long
string · enumOptional
Shared enum for perpetual trade action types (combined buy/sell with position actions).
Possible values:
or
itemsstring · enumOptional
Shared enum for perpetual trade action types (combined buy/sell with position actions).
Possible values:
or
nullOptional
premium_labelsany ofOptional
Controls label tier in the response. When null/omitted (default), returns labels as per subscription plan (existing behavior). When false, returns free-tier labels for all users. When true, returns premium labels (20 credits, currently available to internal users only).
booleanOptional
only_new_positionsany ofOptional
When True, includes 'Open' position actions (Open Long, Open Short). Can be combined with other action filters using OR logic (union). When False (default), returns all trades.
Default: falseExample: true
booleanOptional
pageinteger · min: 1Optional
Page number (1-based)
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page (max 1000)
Default: 10
order_byany ofOptional
Custom sort order to override the endpoint's default ordering.
Examples:
[{"field": "value_usd", "direction": "DESC"}] - Sort by trade value descending
[{"field": "block_timestamp", "direction": "ASC"}] - Sort by timestamp ascending
[{"field": "token_amount", "direction": "DESC"}, {"field": "block_timestamp", "direction": "ASC"}] - Sort by token amount descending, then timestamp ascending
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
Responses
200
Smart money perpetual trades data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
trader_address_labelstringRequired
Name of the trader, based on Nansen labels
trader_addressstringRequired
Hexadecimal representation of the trader's address, i.e. the signer of the transaction
token_symbolstringRequired
The token symbol
sideany ofOptional
The side of the position (Long or Short)
Example: Long
string · enumOptional
Shared enum for position side direction.
Possible values:
actionstringRequired
The action taken by the trader (Add, Reduce, Open, Close)
Example: Add
token_amountany ofOptional
Trade size in contract units
numberOptional
price_usdany ofOptional
Trade price in USD
numberOptional
value_usdany ofOptional
Notional trade value in USD
numberOptional
typestring · enumRequired
The trade type (Market or Limit)
Possible values:
block_timestampstringRequired
The timestamp of the block
transaction_hashstringRequired
Hexadecimal representation of the transaction hash
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
Request model for smart money historical holdings endpoint.
fromany ofOptional
Start date in YYYY-MM-DD format
Example: 2025-01-01
stringOptional
toany ofOptional
End date in YYYY-MM-DD format
Example: 2025-01-31
stringOptional
itemsstring · enumOptional
Chains supported for smart money historical holdings endpoint.
Controls label tier in the response. When null/omitted (default), returns labels as per subscription plan (existing behavior). When false, returns free-tier labels for all users. When true, returns premium labels (20 credits, currently available to internal users only).
booleanOptional
pageinteger · min: 1Optional
Page number (1-based)
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page (max 1000)
Default: 10
order_byany ofOptional
Custom sort order. Defaults to sorting by date DESC, value_usd DESC, token_address ASC, chain ASC for stable pagination.
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
Responses
200
Smart money historical holdings data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
datestringRequired
Snapshot date (YYYY-MM-DD)
chainstring · enumRequired
Chain name
Possible values:
token_addressstringRequired
Address of token
token_symbolstringRequired
Token symbol
token_sectorsstring[]Required
Token sectors
smart_money_labelsstring[]Required
Array of unique smart money labels present in the aggregated holdings for this token
balanceany ofOptional
Token balance in human-readable units (accounting for decimals)
numberOptional
value_usdany ofOptional
Value of token held by Smart Money at snapshot date
numberOptional
balance_24h_percent_changeany ofOptional
Balance change of Smart Money for token during the 24 hours prior to snapshot
numberOptional
holders_countintegerRequired
Number of Smart Money holders of token at snapshot date
share_of_holdings_percentany ofOptional
Share of Smart Money total USD balance at snapshot date
numberOptional
token_age_daysintegerRequired
Number of days since token was deployed, relative to snapshot date
market_cap_usdany ofOptional
Market cap of token at snapshot date
numberOptional
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
Request model for TGM PnL leaderboard endpoint.
This endpoint provides a token PnL leaderboard showing the most profitable
traders for a specific token within a given date range.
Controls label tier in the response. When null/omitted, defaults to true (premium labels filtered by subscription plan). When false, returns free-tier labels for all users. When true, returns premium labels (filtered by subscription plan). Note: In a future release, the default will change from true to false — pass premium_labels=true explicitly to preserve premium label behavior.
booleanOptional
order_byany ofOptional
Custom sort order to override the endpoint's default ordering
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
Responses
200
TGM PnL leaderboard data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
trader_addressstringRequired
Hexadecimal representation of the trader's address.
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
Flexible filtering and sorting options
Request model for Perp Leaderboard endpoint.
This endpoint provides a perpetual trading leaderboard showing the most profitable
traders within a given date range.
Filter by wallet display name. Use LIKE patterns (%) for partial matching. Note: This filters by the wallet's display name, not by label category. To filter by smart money labels, use include_smart_money_labels instead.
Example: %Smart HL Perps Trader%
stringOptional
or
string[]Optional
or
nullOptional
total_pnlany ofOptional
Total PnL range filter in USD
Example: {"min":1000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
roiany ofOptional
ROI range filter as percentage
Example: {"max":100,"min":10}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
account_valueany ofOptional
Account value range filter in USD. Note: Only the top 500K traders have account value data available.
Example: {"min":10000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
include_smart_money_labelsany ofOptional
Filter to include only traders with these smart money labels. For Hyperliquid, use 'Smart HL Perps Trader'. See SmartMoneyFilterType enum for valid values.
Example: ["Smart HL Perps Trader"]
itemsstring · enumOptional
Enum for smart money filter options.
Possible values:
exclude_smart_money_labelsany ofOptional
Exclude smart money labels
Example: ["30D Smart Trader"]
itemsstring · enumOptional
Enum for smart money filter options.
Possible values:
premium_labelsany ofOptional
Controls label tier in the response. When null/omitted (default), returns labels as per subscription plan (existing behavior). When false, returns free-tier labels for all users. When true, returns premium labels. Note: In a future release, the default will change from true to false — pass premium_labels=true explicitly to preserve premium label behavior.
booleanOptional
order_byany ofOptional
Custom sort order to override the endpoint's default ordering
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
Responses
200
Perpetual trading leaderboard data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
The name associated with the address, derived using Nansen's multichain label function for Ethereum.
Example: 🏦 Binance 14 [0x28c6c0]
stringOptional
total_pnlany ofOptional
Profit and loss for the selected timeframe in USD.
Example: 1250.5
numberOptional
roiany ofOptional
Return on investment for the selected timeframe as percentage.
Example: 15.5
numberOptional
account_valueany ofOptional
Current total account value in USD. Note: Account value data is only available for the top 500K traders due to upstream data limitations. Traders outside the top 500K may show 0 or null values.
Example: 10000
numberOptional
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
Request model for Token OHLCV endpoint.
This endpoint provides unified OHLCV (Open, High, Low, Close, Volume) data
for tokens across supported chains with different time resolutions.
Position value range filter in USD (+ve = Long position, -ve = Short position, 0 = Flat)
Example: {"min":1000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
max_balance_heldany ofOptional
Maximum balance held range filter
Example: {"min":100}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
max_balance_held_usdany ofOptional
Maximum balance held range filter in USD
Example: {"min":1000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
still_holding_balance_ratioany ofOptional
Still holding balance ratio range filter
Example: {"max":1,"min":0.1}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
nof_tradesany ofOptional
Number of trades range filter
Example: {"max":100,"min":10}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
include_smart_money_labelsany ofOptional
Include smart money labels
Example: ["Fund","Smart Trader"]
itemsstring · enumOptional
Enum for smart money filter options.
Possible values:
exclude_smart_money_labelsany ofOptional
Exclude smart money labels
Example: ["30D Smart Trader"]
itemsstring · enumOptional
Enum for smart money filter options.
Possible values:
premium_labelsany ofOptional
Controls label tier in the response. When null/omitted (default), returns labels as per subscription plan (existing behavior). When false, returns free-tier labels for all users. When true, returns premium labels. Note: In a future release, the default will change from true to false — pass premium_labels=true explicitly to preserve premium label behavior.
booleanOptional
order_byany ofOptional
Custom sort order to override the endpoint's default ordering
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
Responses
200
TGM Perp PnL leaderboard data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
trader_addressstringRequired
Hexadecimal representation of the trader's address.
Token price in USD at date_to. Uses latest spot price if date_to is today or later, otherwise the daily median price for that date.
Example: 1.23
numberOptional
pnl_usd_realisedany ofOptional
Realised profit and loss in USD.
Example: 1250.5
numberOptional
pnl_usd_unrealisedany ofOptional
Unrealised profit and loss in USD.
Example: 100.25
numberOptional
holding_amountany ofOptional
Current token balance
Example: 5000
numberOptional
position_value_usdany ofOptional
Position value in USD (+ve = Long position, -ve = Short position, 0 = Flat)
Example: 6000
numberOptional
max_balance_heldany ofOptional
Maximum amount of tokens held at some point in time.
Example: 10000
numberOptional
max_balance_held_usdany ofOptional
Maximum amount of tokens in current USD value, held at some point in time.
Example: 12000
numberOptional
still_holding_balance_ratioany ofOptional
The ratio of current holdings to max balance held.
Example: 0.5
numberOptional
netflow_amount_usdany ofOptional
Netflow amount in USD.
Example: 2500.75
numberOptional
netflow_amountany ofOptional
Netflow amount.
Example: 1500
numberOptional
roi_percent_totalany ofOptional
Total ROI.
Example: 15.5
numberOptional
roi_percent_realisedany ofOptional
Realised ROI.
Example: 12.3
numberOptional
roi_percent_unrealisedany ofOptional
Unrealised ROI.
Example: 3.2
numberOptional
pnl_usd_totalany ofOptional
Total PNL in USD.
Example: 1350.75
numberOptional
nof_tradesany ofOptional
Number of trades.
Example: 25
integerOptional
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
Request model for Token Screener endpoint.
Either 'timeframe' (recommended) or 'date' (deprecated) must be provided.
itemsstring · enumOptional
Chains supported for Token Screener endpoint.
Possible values:
timeframeany ofOptional
Required (unless using deprecated 'date' parameter).
Time window for token screening data.
Available timeframes and their data characteristics:
5m: Last 5 minutes (minute-level granularity, 2-hour retention)
10m: Last 10 minutes (minute-level granularity, 2-hour retention)
1h: Last 1 hour (minute-level granularity, 2-hour retention)
6h: Last 6 hours (hourly granularity, 2-day retention)
24h: Last 24 hours (hourly granularity, 2-day retention)
7d: Last 7 days (daily granularity, 2-month retention)
30d: Last 30 days (daily granularity, 2-month retention)
Cannot be used together with 'date'.
Example: 24h
string · enumOptional
Token screener timeframe options.
Defines the time window for token screening data.
Each timeframe corresponds to different data granularity and retention periods.
Matches the timeframe options in the Superapp token-screener widget.
Possible values:
dateany ofOptionalDeprecated
DEPRECATED: Use 'timeframe' instead for better reliability and performance.
Required only if 'timeframe' is not provided.
Custom date range for the token screener. The granularity is automatically determined from the date range:
≤ 1 hour: minute-level data (limited to last 2 hours)
1 hour to 1 day: hourly data (limited to last 2 days)
Deprecated: use trader_type instead. Whether to only include smart money tokens
Example: true
booleanOptional
trader_typeany ofOptional
Filter by trader type. Overrides only_smart_money when provided.
Example: sm
string · enumOptional
Trader type filter for token screener.
Possible values:
sectorsany ofOptional
Token sectors to include
Example: ["DeFi","Gaming"]
string[]Optional
token_age_daysany ofOptional
Token age range filter in days
Example: {"max":365,"min":1}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
market_cap_usdany ofOptional
Market cap range filter
Example: {"max":100000000,"min":1000000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
liquidityany ofOptional
Liquidity range filter
Example: {"min":100000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
price_usdany ofOptional
Current price range filter in USD
Example: {"max":1000,"min":0.01}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
price_changeany ofOptional
Price change percentage range filter
Example: {"max":100,"min":-50}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
fdvany ofOptional
Fully Diluted Valuation range filter
Example: {"min":1000000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
fdv_mc_ratioany ofOptional
FDV to Market Cap ratio range filter
Example: {"max":10,"min":1}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
nof_buyersany ofOptional
Number of unique buyers range filter
Example: {"min":10}
minany ofOptional
Minimum value (inclusive)
Example: 10
integerOptional
maxany ofOptional
Maximum value (inclusive)
Example: 100
integerOptional
nof_tradersany ofOptional
Number of unique traders range filter
Example: {"min":50}
minany ofOptional
Minimum value (inclusive)
Example: 10
integerOptional
maxany ofOptional
Maximum value (inclusive)
Example: 100
integerOptional
nof_sellersany ofOptional
Number of unique sellers range filter
Example: {"min":10}
minany ofOptional
Minimum value (inclusive)
Example: 10
integerOptional
maxany ofOptional
Maximum value (inclusive)
Example: 100
integerOptional
nof_buysany ofOptional
Number of buy transactions range filter
Example: {"min":20}
minany ofOptional
Minimum value (inclusive)
Example: 10
integerOptional
maxany ofOptional
Maximum value (inclusive)
Example: 100
integerOptional
nof_sellsany ofOptional
Number of sell transactions range filter
Example: {"min":20}
minany ofOptional
Minimum value (inclusive)
Example: 10
integerOptional
maxany ofOptional
Maximum value (inclusive)
Example: 100
integerOptional
buy_volumeany ofOptional
Buy volume range filter in USD
Example: {"min":10000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
sell_volumeany ofOptional
Sell volume range filter in USD
Example: {"min":10000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
volumeany ofOptional
Total trading volume range filter in USD
Example: {"min":50000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
netflowany ofOptional
Net flow range filter in USD
Example: {"max":100000,"min":-100000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
inflow_fdv_ratioany ofOptional
Inflow to FDV ratio range filter
Example: {"min":0.001}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
outflow_fdv_ratioany ofOptional
Outflow to FDV ratio range filter
Example: {"min":0.001}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
include_stablecoinsbooleanOptional
Whether to include stablecoins in token screener results. Default true preserves current behavior. Set to false to exclude USDC, USDT, DAI, and other major stablecoins.
Default: true
include_smart_money_labelsany ofOptional
Include smart money labels
Example: ["Public Figure","Exchange"]
itemsstring · enumOptional
Enum for smart money filter options.
Possible values:
exclude_smart_money_labelsany ofOptional
Exclude smart money labels
Example: ["Fund"]
itemsstring · enumOptional
Enum for smart money filter options.
Possible values:
order_byany ofOptional
Custom sort order to override the endpoint's default ordering.
Examples:
[{"field": "buy_volume", "direction": "DESC"}] - Sort by buy volume descending
[{"field": "price_change", "direction": "DESC"}] - Sort by price change descending
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
Responses
200
Token screening data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
chainstringRequired
The blockchain network on which the token is deployed.
token_addressstringRequired
Address of token
token_symbolstringRequired
The symbol of the token.
token_age_daysany ofOptional
Number of days since token deployment.
numberOptional
market_cap_usdany ofOptional
Market capitalization in USD.
numberOptional
liquidityany ofOptional
Total on-chain liquidity in USD.
numberOptional
price_usdany ofOptional
Price of the token
numberOptional
price_changeany ofOptional
Price change percentage from the previous period.
numberOptional
fdvany ofOptional
Fully Diluted Valuation in USD.
numberOptional
fdv_mc_ratioany ofOptional
Ratio of Fully Diluted Valuation to Market Cap.
numberOptional
buy_volumeany ofOptional
Total buy volume in USD.
numberOptional
inflow_fdv_ratioany ofOptional
Ratio of inflow to Fully Diluted Valuation.
numberOptional
outflow_fdv_ratioany ofOptional
Ratio of outflow to Fully Diluted Valuation.
numberOptional
sell_volumeany ofOptional
Total sell volume in USD.
numberOptional
volumeany ofOptional
Total trading volume in USD.
numberOptional
netflowany ofOptional
Net flow (buy_volume - sell_volume) in USD.
numberOptional
or
chainstringRequired
The blockchain network on which the token is deployed.
token_addressstringRequired
Address of token
token_symbolstringRequired
The symbol of the token.
token_age_daysany ofOptional
Number of days since token deployment.
numberOptional
market_cap_usdany ofOptional
Market capitalization in USD.
numberOptional
liquidityany ofOptional
Total on-chain liquidity in USD.
numberOptional
price_usdany ofOptional
Price of the token
numberOptional
price_changeany ofOptional
Price change percentage from the previous period.
numberOptional
fdvany ofOptional
Fully Diluted Valuation in USD.
numberOptional
fdv_mc_ratioany ofOptional
Ratio of Fully Diluted Valuation to Market Cap.
numberOptional
nof_tradersany ofOptional
Total number of unique traders.
integerOptional
buy_volumeany ofOptional
Total buy volume in USD.
numberOptional
inflow_fdv_ratioany ofOptional
Ratio of inflow to Fully Diluted Valuation.
numberOptional
outflow_fdv_ratioany ofOptional
Ratio of outflow to Fully Diluted Valuation.
numberOptional
sell_volumeany ofOptional
Total sell volume in USD.
numberOptional
volumeany ofOptional
Total trading volume in USD.
numberOptional
netflowany ofOptional
Net flow (buy_volume - sell_volume) in USD.
numberOptional
or
chainstringRequired
The blockchain network on which the token is deployed.
token_addressstringRequired
Address of token
token_symbolstringRequired
The symbol of the token.
token_age_daysany ofOptional
Number of days since token deployment.
numberOptional
market_cap_usdany ofOptional
Market capitalization in USD.
numberOptional
liquidityany ofOptional
Total on-chain liquidity in USD.
numberOptional
price_usdany ofOptional
Price of the token
numberOptional
price_changeany ofOptional
Price change percentage from the previous period.
numberOptional
fdvany ofOptional
Fully Diluted Valuation in USD.
numberOptional
fdv_mc_ratioany ofOptional
Ratio of Fully Diluted Valuation to Market Cap.
numberOptional
nof_buyersany ofOptional
Number of unique buyers.
integerOptional
nof_tradersany ofOptional
Total number of unique traders.
integerOptional
nof_sellersany ofOptional
Number of unique sellers.
integerOptional
nof_buysany ofOptional
Total number of buy transactions.
integerOptional
nof_sellsany ofOptional
Total number of sell transactions.
integerOptional
buy_volumeany ofOptional
Total buy volume in USD.
numberOptional
inflow_fdv_ratioany ofOptional
Ratio of inflow to Fully Diluted Valuation.
numberOptional
outflow_fdv_ratioany ofOptional
Ratio of outflow to Fully Diluted Valuation.
numberOptional
sell_volumeany ofOptional
Total sell volume in USD.
numberOptional
volumeany ofOptional
Total trading volume in USD.
numberOptional
netflowany ofOptional
Net flow (buy_volume - sell_volume) in USD.
numberOptional
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
,
exclude_smart_money_labels
Request model for TGM holders endpoint.
This endpoint provides comprehensive data on token holders and their balances.
Retrieve holders by various criteria including smart money, exchanges, public figures,
whales, and top holders with detailed balance information and filtering options.
Label type. You must also include the labels filter to match the label type. For example, for label type 'smart_money', you must include '30D Smart Trader', '90D Smart Trader', '180D Smart Trader', 'Fund' or 'Smart Trader' in the filters.labels.include parameter.
Balance range filter in USD. Defaults to min: 1.0 to exclude dust holders. Set explicitly to override (e.g., {"min": 0} to include all holders). Note: This default does not apply to native tokens with 'all_holders' label.
Example: {"min":10000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
premium_labelsany ofOptional
Controls label tier in the response. When null/omitted, defaults to true (premium labels filtered by subscription plan). When false, returns free-tier labels for all users. When true, returns premium labels (filtered by subscription plan). Note: In a future release, the default will change from true to false — pass premium_labels=true explicitly to preserve premium label behavior.
booleanOptional
order_byany ofOptional
Custom sort order to override the endpoint's default ordering.
Examples:
[{"field": "value_usd", "direction": "DESC"}] - Sort by value USD descending
[{"field": "token_amount", "direction": "ASC"}] - Sort by token amount ascending
[{"field": "ownership_percentage", "direction": "DESC"}] - Sort by ownership percentage descending
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
Responses
200
TGM holders data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Percentage of total token supply owned by this address
Example: 2.5
numberOptional
value_usdany ofOptional
Current token balance value in USD
Example: 50000
numberOptional
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
warningsany ofOptional
Optional warnings about the query results. For example, if a token has no USD price data, a warning will indicate that the default value_usd filter may be excluding results.
string[]Optional
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
Controls label tier in the response. When null/omitted (default), returns labels as per subscription plan (existing behavior). When false, returns free-tier labels for all users. When true, returns premium labels (20 credits, currently available to internal users only).
booleanOptional
pageinteger · min: 1Optional
Page number (1-based)
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page (max 1000)
Default: 10
order_byany ofOptional
Custom sort order to override the endpoint's default ordering.
Examples:
[{"field": "total_volume_usd", "direction": "DESC"}] - Sort by total volume descending
[{"field": "interaction_count", "direction": "ASC"}] - Sort by interaction count ascending
[{"field": "last_interaction_date", "direction": "DESC"}] - Sort by last interaction date descending
[{"field": "volume_in_usd", "direction": "DESC"}] - Sort by incoming volume descending
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
Responses
200
Address counterparties data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
counterparty_addressstringRequired
Counterparty address in hex format
counterparty_address_labelany ofOptional
List of labels associated with this counterparty
string[]Optional
interaction_countintegerRequired
Total number of interactions with this counterparty
total_volume_usdany ofOptional
Total transaction volume in USD
numberOptional
volume_in_usdany ofOptional
Incoming transaction volume in USD
numberOptional
volume_out_usdany ofOptional
Outgoing transaction volume in USD
numberOptional
tokens_infoany ofOptional
Information about tokens transferred with this counterparty
token_addressstringRequired
Token contract address
token_symbolstringRequired
Token symbol
token_namestringRequired
Token name
num_transferstringRequired
Number of transfers
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
Controls label tier in the response. When null/omitted (default), returns labels as per subscription plan (existing behavior). When false, returns free-tier labels for all users. When true, returns premium labels (20 credits, currently available to internal users only).
booleanOptional
pageinteger · min: 1Optional
Page number (1-based)
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page (max 1000)
Default: 10
order_byany ofOptional
Custom sort order to override the endpoint's default ordering.
Examples:
[{"field": "value_usd", "direction": "DESC"}] - Sort by value USD descending
[{"field": "holders_count", "direction": "ASC"}] - Sort by number of holders ascending
[{"field": "value_usd", "direction": "DESC"}, {"field": "holders_count", "direction": "ASC"}] - Sort by value USD descending, then number of holders ascending
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
Responses
200
Smart money holdings data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
chainstring · enumRequired
Chain name
Possible values:
token_addressstringRequired
Address of token
token_symbolstringRequired
Token symbol
token_sectorsstring[]Required
Token sectors
value_usdany ofOptional
Value of token held by Smart Money.
numberOptional
balance_24h_percent_changeany ofOptional
Balance change of Smart Money for token during the last 24 hours
numberOptional
holders_countintegerRequired
Number of Smart Money holders of token.
share_of_holdings_percentany ofOptional
Share of Smart Money total USD balance.
numberOptional
token_age_daysintegerRequired
Number of days since token was deployed.
market_cap_usdany ofOptional
Market cap of token.
numberOptional
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
Whether to include native tokens (e.g., ETH, SOL) in the results
Default: false
booleanOptional
token_sectorany ofOptional
Token sector filter
Example: ["DeFi","NFT","Gaming"]
string[]Optional
trader_countany ofOptional
Trader count range filter
Example: {"max":100,"min":1}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
token_age_daysany ofOptional
Token age range filter in days
Example: {"max":365,"min":1}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
market_cap_usdany ofOptional
Market cap range filter in USD
Example: {"max":1000000000,"min":1000000}
minany ofOptional
Minimum value (inclusive)
Example: 1000
numberOptional
maxany ofOptional
Maximum value (inclusive)
Example: 50000
numberOptional
premium_labelsany ofOptional
Controls label tier in the response. When null/omitted (default), returns labels as per subscription plan (existing behavior). When false, returns free-tier labels for all users. When true, returns premium labels (20 credits, currently available to internal users only).
booleanOptional
pageinteger · min: 1Optional
Page number (1-based)
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page (max 1000)
Default: 10
order_byany ofOptional
Custom sort order to override the endpoint's default ordering.
Examples:
[{"field": "market_cap_usd", "direction": "DESC"}] - Sort by market cap descending
[{"field": "net_flow_24h_usd", "direction": "ASC"}] - Sort by 24h flow ascending
[{"field": "market_cap_usd", "direction": "DESC"}, {"field": "net_flow_24h_usd", "direction": "ASC"}] - Sort by market cap descending, then 24h flow ascending
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
token_addressstringRequired
Token contract address
token_symbolstringRequired
Token symbol
net_flow_1h_usdnumberRequired
Net flow bought/sold of token by Smart Money in the past 1 hour.
net_flow_24h_usdnumberRequired
Net flow bought/sold of token by Smart Money in the past 24 hours.
net_flow_7d_usdnumberRequired
Net flow bought/sold of token by Smart Money in the past 7 days.
net_flow_30d_usdnumberRequired
Net flow bought/sold of token by Smart Money in the past 30 days.
chainstringRequired
Blockchain chain
token_sectorsstring[]Required
Token sectors
trader_countintegerRequired
Number of Smart Money traders of token in the past 30 days.
token_age_daysintegerRequired
Number of days since token was deployed.
market_cap_usdany ofOptional
Market cap of token.
numberOptional
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
Request model for TGM who bought/sold endpoint.
This endpoint provides an aggregated summary of trade volumes in USD for addresses
involved in DEX (Decentralized Exchange) trades for a specific token.
Number of records per page (max 100 for performance)
Default: 20
order_byany ofOptional
Custom sort order to override the endpoint's default ordering
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
Request model for TGM transfers endpoint.
This endpoint provides top token transfers for a specific token, with support for ERC-20 tokens. The model selection is dynamic based
on the token address.
Controls label tier in the response. When null/omitted (default), returns labels as per subscription plan (existing behavior). When false, returns free-tier labels for all users. When true, returns premium labels (20 credits, currently available to internal users only).
booleanOptional
pageinteger · min: 1Optional
Page number (1-based)
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page (max 1000)
Default: 10
order_byany ofOptional
Custom sort order to override the endpoint's default ordering.
Examples:
[{"field": "dca_created_at", "direction": "DESC"}] - Sort by DCA created timestamp descending
Custom sort order to override the endpoint's default ordering (default: pnl_usd_realised DESC).
If the parameter show_realized is false, the default sort order is pnl_usd_unrealised DESC.
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
Responses
200
Address PnL data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
token_addressstringRequired
Hexadecimal representation of the token's address
token_symbolstringRequired
Symbol of the token
token_priceany ofOptional
Price of the token on date_to
numberOptional
roi_percent_realisedany ofOptional
Realised return on investment for only realised gains (not multiplied by 100)
numberOptional
pnl_usd_realisedany ofOptional
Realised profit and loss in USD
numberOptional
pnl_usd_unrealisedany ofOptional
Unrealised profit and loss in USD
numberOptional
roi_percent_unrealisedany ofOptional
Unrealised return on investment for only unrealised gains (not multiplied by 100)
numberOptional
bought_amountany ofOptional
Amount of tokens bought from date_from to date_to
numberOptional
bought_usdany ofOptional
USD value of bought tokens
numberOptional
cost_basis_usdany ofOptional
Cost basis of tokens in USD as of date_to
numberOptional
sold_amountany ofOptional
Amount of tokens sold from date_from to date_to
numberOptional
sold_usdany ofOptional
USD value of sold tokens
numberOptional
avg_sold_price_usdany ofOptional
Average sale price of tokens sold in USD
numberOptional
holding_amountany ofOptional
Current token balance
numberOptional
holding_usdany ofOptional
USD value of token balance
numberOptional
nof_buysstringRequired
Number of buys (either inflow or dex buy)
nof_sellsstringRequired
Number of sells (either outflow or dex sell)
max_balance_heldany ofOptional
Maximum amount of tokens held at some point in time
numberOptional
max_balance_held_usdany ofOptional
Maximum amount of tokens in current USD value, held at some point in time
numberOptional
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
Request model for TGM flow-intelligence endpoint.
This endpoint provides detailed token flow intelligence for analyzing token movements
across different chains. It helps track and categorize token transfers, identifying
patterns such as exchange deposits, withdrawals, and transfers between different
types of wallets.
The action taken by the trader (Add, Reduce, Open, Close)
Example: Add
token_amountany ofOptional
The amount of the specified token traded
Example: 1.5
numberOptional
price_usdany ofOptional
Average fill price in USD across all fills in the trade, from exchange data.
Example: 60000
numberOptional
value_usdany ofOptional
The value in USD
Example: 90000
numberOptional
typestring · enumRequired
The order type (MARKET or LIMIT)
Example: MARKETPossible values:
block_timestampstringRequired
The block timestamp for the transaction
Example: 2025-10-01T12:40:00Z
transaction_hashstringRequired
A representative transaction hash for this trade. Note: A single row may aggregate multiple fills that occurred at the same timestamp. If the trader had fills across multiple transactions at the exact same millisecond, only one transaction_hash is shown. The token_amount and value_usd reflect the total across all fills.
Controls label tier in the response. When null/omitted (default), returns labels as per subscription plan (existing behavior). When false, returns free-tier labels for all users. When true, returns premium labels (20 credits, currently available to internal users only).
booleanOptional
pageinteger · min: 1Optional
Page number (1-based)
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page (max 1000)
Default: 10
order_byany ofOptional
Custom sort order to override the endpoint's default ordering.
Examples:
[{"field": "trade_value_in_usd", "direction": "DESC"}] - Sort by trade value descending
[{"field": "block_timestamp", "direction": "ASC"}] - Sort by timestamp ascending
[{"field": "token_bought_amount", "direction": "DESC"}, {"field": "block_timestamp", "direction": "ASC"}] - Sort by bought amount descending, then timestamp ascending
fieldstring · enumRequired
Field to sort by
Possible values:
directionstring · enumRequired
Sort direction (ASC or DESC)
Possible values:
What leverage levels are traders using?
Which smart money wallets are holding positions?
Responses
200
TGM perp positions data
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
The type of leverage used, e.g., cross or isolated.
Example: cross
stringOptional
entry_priceany ofOptional
Average price where the position was opened.
Example: 50000
numberOptional
mark_priceany ofOptional
The current mark price of the asset.
Example: 50500
numberOptional
liquidation_priceany ofOptional
The price at which the position would be liquidated.
Example: 45000
numberOptional
funding_usdany ofOptional
Net funding paid (-) or received (+) since entry.
Example: 10.5
numberOptional
upnl_usdany ofOptional
Unrealized profit/loss including funding.
Example: 500
numberOptional
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
Request model for TGM flows endpoint.
This endpoint provides comprehensive token flow analytics showing inflow and outflow patterns
from various holder segments including Exchanges, Smart Money addresses, Public Figures, and Whales
with time-based statistics and trends.
The name associated with the address, derived using Nansen's multichain label function for Ethereum.
Example: 🏦 Binance 14 [0x28c6c0]
stringOptional
total_pnlany ofOptional
Profit and loss for the selected timeframe in USD.
Example: 1250.5
numberOptional
roiany ofOptional
Return on investment for the selected timeframe as percentage.
Example: 15.5
numberOptional
account_valueany ofOptional
Current total account value in USD. Note: Account value data is only available for the top 500K traders due to upstream data limitations. Traders outside the top 500K may show 0 or null values.
Example: 10000
numberOptional
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
400
Bad Request
application/json
401
Unauthorized
application/json
detailstringOptionalExample: No API key found in request
402
Payment Required
application/json
403
Forbidden
application/json
404
Not Found
application/json
422
Unprocessable Content
application/json
locstring[]Optional
msgstringOptional
typestringOptional
429
Too Many Requests
application/json
500
Internal Server Error
application/json
Responses
200
Perpetual trade data for the user
application/json
X-Nansen-Credits-UsedstringOptional
Number of credits consumed by this API request
Example: 5
X-Nansen-Credits-RemainingstringOptional
Total credits remaining in the user's account after this request
Example: 9995
RateLimit-LimitstringOptional
Combined rate limit across all configured time windows
Example: 20
RateLimit-RemainingstringOptional
Number of requests remaining in the current limiting window
Example: 15
RateLimit-ResetstringOptional
Time in seconds until the rate limit window resets
Example: 30
X-RateLimit-Limit-SecondstringOptional
Maximum requests allowed per second
Example: 20
X-RateLimit-Remaining-SecondstringOptional
Requests remaining in the current second
Example: 19
X-RateLimit-Limit-MinutestringOptional
Maximum requests allowed per minute
Example: 300
X-RateLimit-Remaining-MinutestringOptional
Requests remaining in the current minute
Example: 295
pageinteger · min: 1Optional
Current page number
Default: 1
per_pageinteger · min: 1 · max: 1000Optional
Number of records per page
Default: 10
is_last_pagebooleanOptional
Whether this is the last page
Default: true
timestampstringRequired
Timestamp of the trade
Example: 2025-10-08T18:46:11.452000
sideany ofRequired
Position side (Long or Short)
Example: Long
string · enumOptional
Enum for perp trade position types.
Possible values:
actionstringRequired
Action taken (Open, Add, Close, Reduce, etc.)
Example: Add
block_numberintegerRequired
Block number of the trade
Example: 756553592
token_symbolstringRequired
Symbol of the token
Example: DOGE
priceany ofRequired
Average price of the trade (averaged across fills)
