nansen-api-reference
This document provides detailed technical specifications for all Nansen API endpoints, including request formats, response schemas, and usage examples.
Base Configuration
Base URL: https://api.nansen.ai/api/beta
Authentication: API Key in header: apiKey: YOUR_API_KEY
Rate Limits: 20 requests/second, 500 requests/minute Content-Type: application/json
Smart Money API Endpoints
1. Smart Money Inflows
Endpoint: POST /smart-money/inflows
Credit Cost: 5 credits per call Description: Net flow of tokens bought/sold by Smart Money addresses
Request Parameters:
{
"parameters": {
"smFilter": ["180D Smart Trader", "Fund", "Smart Trader"],
"chains": ["ethereum", "solana"],
"includeStablecoin": true,
"includeNativeTokens": true,
"excludeSmFilter": []
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
chains: List of blockchains to query (default: ["ethereum"])
sm_filter: Smart money filter (default: ["180D Smart Trader", "Fund", "Smart Trader"])
include_stablecoin: Whether to include stablecoins (default: True)
include_native_tokens: Whether to include native tokens (default: True)
exclude_sm_filter: Smart money filters to exclude (default: [])
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
Response Schema:
[
{
"chain": "ethereum",
"tokenAddress": "0x...",
"symbol": "USDC",
"sectors": ["DeFi"],
"volume24hUSD": 1500000,
"volume7dUSD": 8750000,
"volume30dUSD": 35000000,
"nofTraders": "245",
"tokenAgeDays": "1200",
"marketCap": 32000000000
}
]
2. Smart Money Holdings
Endpoint: POST /smart-money/holdings
Credit Cost: 5 credits per call Description: Get smart money holdings for specific blockchain(s).
Request Parameters:
{
"parameters": {
"smFilter": ["180D Smart Trader", "Fund", "Smart Trader"],
"chains": ["ethereum", "solana"],
"includeStablecoin": true,
"includeNativeTokens": true,
"excludeSmFilter": []
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
chains: List of blockchains to query (default: ["ethereum"]) sm_filter: Smart money filter (default: ["180D Smart Trader", "Fund", "Smart Trader"]) include_stablecoin: Whether to include stablecoins (default: True) include_native_tokens: Whether to include native tokens (default: True) exclude_sm_filter: Smart money filters to exclude (default: []) page: Page number for pagination (default: 1) records_per_page: Number of results per page (default: 100)
Response Schema:
[
{
"chain": "ethereum",
"tokenAddress": "0x...",
"symbol": "ETH",
"sectors": ["Layer 1"],
"balanceUsd": 12500000,
"balancePctChange24H": 2.5,
"nofHolders": "1250",
"shareOfHoldings": 8.7,
"tokenAgeDays": "3000",
"marketCap": 400000000000
}
]
3. Smart Money DEX Trades
Endpoint: POST /smart-money/dex-trades
Credit Cost: 5 credits per call Description: Get smart money DEX trades in the last 24 hours.
Request Parameters:
{
"parameters": {
"chains": ["ethereum", "solana"],
"smFilter": ["180D Smart Trader", "Fund", "Smart Trader"],
"excludeSmFilter": []
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
chains: List of blockchains to query (default: ["ethereum"])
sm_filter: Smart money filter (default: ["180D Smart Trader", "Fund", "Smart Trader"])
exclude_sm_filter: Smart money filters to exclude (default: [])
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
Response Schema:
[
{
"chain": "ethereum",
"timestamp": "2024-01-15T14:30:00Z",
"txHash": "0x...",
"address": "0x...",
"name": "Smart Trader #1234",
"tokenBoughtAddress": "0x...",
"tokenSoldAddress": "0x...",
"tokenBoughtAmount": 1000.50,
"tokenSoldAmount": 1500.25,
"tokenBoughtSymbol": "LINK",
"tokenSoldSymbol": "USDC",
"tokenBoughtAgeDays": "2100",
"tokenSoldAgeDays": "1200",
"tokenBoughtMarketCap": 8500000000,
"tokenSoldMarketCap": 32000000000,
"valueInUsd": 15000.75
}
]
4. Smart Money DCAs
Endpoint: POST /smart-money/dcas
Credit Cost: 5 credits per call (PROHIBITED for redistribution) Description: Jupiter DCA orders created by Smart Money addresses on Solana
Request Parameters:
{
"parameters": {
"chain": "solana",
"smFilter": ["180D Smart Trader", "Fund", "Smart Trader"],
"excludeSmFilter": [],
"tokenAddress": "So11111111111111111111111111111111111111112"
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
chain: Blockchain to query (default: "solana")
sm_filter: Smart money filter (default: ["180D Smart Trader", "Fund", "Smart Trader"])
exclude_sm_filter: Smart money filters to exclude (default: [])
token_address: Optional token address to filter by
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
Profiler API Endpoints
1. Address Balances
Endpoint: POST /profiler/address/balances
Credit Cost: 0 credits (FREE) Description: Current token balances for specified addresses
Request Parameters:
{
"parameters": {
"chain": "ethereum",
"walletAddresses": ["0x28c6c06298d514db089934071355e5743bf21d60"],
"suspiciousFilter": "on"
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
wallet_addresses: List of wallet addresses to query
chain: The blockchain to query (default: "ethereum")
suspicious_filter: "on" or "off" - whether to exclude suspicious tokens (default: None)
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
Response Schema:
[
{
"chain": "ethereum",
"tokenAddress": "0x...",
"symbol": "USDC",
"name": "USD Coin",
"tokenAmount": 25000.50,
"priceUsd": 1.00,
"usdValue": 25000.50
}
]
2. Historical Balances
Endpoint: POST /profiler/address/historical-balances
Credit Cost: 0 credits (FREE) Description: Historical token holdings over time
Request Parameters:
{
"parameters": {
"walletAddresses": ["0x28c6c06298d514db089934071355e5743bf21d60"],
"chain": "ethereum",
"suspiciousFilter": "on",
"timeFrame": 1
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
wallet_addresses: List of wallet addresses to query
suspicious_filter: "on" or "off" - whether to exclude suspicious tokens
chain: The blockchain to query (default: "ethereum")
time_frame: Number of days (1, 7, 30, 90, 120, 365) (default: None)
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
3. Address Transactions
Endpoint: POST /profiler/address/transactions
Credit Cost: 0 credits (FREE, requires attribution) Description: Complete transaction history with labels
Request Parameters:
{
"parameters": {
"chain": "ethereum",
"walletAddresses": ["0x28c6c06298d514db089934071355e5743bf21d60"],
"hideSpamToken": true
},
"pagination": {
"page": 1,
"recordsPerPage": 100
},
"filters": {
"volumeUsd": {"from": 0.1},
"blockTimestamp": {
"from": "2025-05-13T00:00:00.000Z",
"to": "2025-05-13T03:00:00.000Z"
}
}
}
Args:
wallet_addresses: List of wallet addresses to query (default: None)
chain: The blockchain to query (default: "ethereum")
hide_spam_token: Removes suspicious tokens from transaction list (default: True)
filters: Optional filters for the transaction query (default: None)
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
4. Address Counterparties
Endpoint: POST /profiler/address/counterparties
Credit Cost: 5 credits per call (requires attribution) Description: Most frequent interaction addresses with volume analysis
Request Parameters:
{
"parameters": {
"walletAddresses": ["0x28c6c06298d514db089934071355e5743bf21d60"],
"chain": "ethereum",
"sourceInput": "Combined",
"groupBy": "wallet",
"timeRange": {
"from": "2025-05-01",
"to": "2025-05-03"
}
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
wallet_addresses: List of wallet addresses to query
source_input: "Combined", "Tokens", or "ETH"
group_by: "wallet" or "entity"
time_range: Time range dictionary with 'from' and 'to' keys
chain: The blockchain to query (default: "ethereum")
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
5. Related Wallets
Endpoint: POST /profiler/address/related-wallets
Credit Cost: 1 credit per call (requires attribution) Description: Connected addresses through various relationships
Request Parameters:
{
"parameters": {
"chain": "ethereum",
"walletAddresses": ["0x28c6c06298d514db089934071355e5743bf21d60"]
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
wallet_addresses: List of wallet addresses to query
chain: The blockchain to query (default: "ethereum")
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
Response Schema:
[
{
"addressHex": "0x...",
"addressName": "Related Wallet #1",
"relation": "First Funder",
"transactionHash": "0x..."
}
]
6. PnL Summary
Endpoint: POST /profiler/address/pnl-summary
Credit Cost: 1 credit per call Description: Aggregate trading performance with top 5 tokens
Request Parameters:
{
"parameters": {
"chain": "ethereum",
"walletAddress": "0x28c6c06298d514db089934071355e5743bf21d60",
"date": {
"from": "2025-05-01",
"to": "2025-05-03"
}
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
wallet_address: The wallet address to analyze
date: Date range dictionary with 'from' and 'to' keys
chain: The blockchain to query (default: "ethereum")
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
7. Detailed PnL
Endpoint: POST /profiler/address/pnl
Credit Cost: 1 credit per call Description: Per-token trading performance analysis
Request Parameters:
{
"parameters": {
"chain": "ethereum",
"date": {
"from": "2025-05-01",
"to": "2025-05-03"
},
"walletAddress": "0x28c6c06298d514db089934071355e5743bf21d60",
"showRealized": true,
"tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
wallet_address: The wallet address to analyze
token_address: Token address to generate PnL stats for
date: Date range dictionary with 'from' and 'to' keys
show_realized: Include realized profit or not
chain: The blockchain to query (default: "ethereum")
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
Token God Mode API Endpoints
1. Token Screener
A comprehensive token screening interface that provides real-time analytics and insights across multiple blockchain networks.
Request Parameters:
{
"parameters": {
"chains": [ //Required-cannot be empty
"ethereum",
"solana"
],
"date": { //Required-cannot be empty
"from": "2025-05-01",
"to": "2025-05-03"
},
"watchlistFilter": [ //Required-can be empty
"0x28c6c06298d514db089934071355e5743bf21d60"
],
"sectorsFilter": [ //Required-can be empty
"Artificial Intelligence",
"AI Agents"
],
"smLabelFilter": [ //Required-can be empty
"Smart Money"
],
"onlySmartMoney": true //Required-cannot be empty
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
Available Filters:
tokenAgeDays
- Token age in daysbuyVolume
- Total buy-side volumesellVolume
- Total sell-side volumevolume
- Total trading volumeliquidity
- Liquidity in pools (USD equivalent)marketCap
- Market capitalizationfdv
- Fully Diluted Valuationnetflow
- Net inflow (inflows - outflows)holders
- Number of token holdersnofBuyers
- Count of unique buyersnofSellers
- Count of unique sellerspriceChange
- Token price movement percentage
Sorting Options: Add order
object with orderBy
(column name) and order
(desc/asc):
{
"order": {
"orderBy": "liquidity",
"order": "desc"
}
}
Response Schema:
[
{
"chain": "ethereum",
"tokenAddressHex": "0x...",
"tokenSymbol": "TOKEN",
"tokenAgeDays": "5",
"marketCap": 25000000,
"liquidity": "1500000",
"currentPriceUsd": "2.45",
"priceChange": "12.5",
"fdv": "30000000",
"fdvMcRatio": "1.2",
"nofBuyers": "1250",
"nofTraders": "2100",
"nofSellers": "850",
"nofBuys": "3200",
"nofSells": "2100",
"buyVolume": "850000",
"sellVolume": "650000",
"volume": "1500000",
"netflow": "200000",
"inflowFdvRatio": "0.08",
"outflowFdvRatio": "0.06"
}
]
Args:
date_range: Date range dictionary with 'from' and 'to' keys (default: last 7 days)
watchlist_filter: List of token addresses to filter by (default: empty list)
sectors_filter: List of sectors to filter tokens by (default: empty list)
only_smart_money: Only smart money flag (default: False)
chains: List of chains to query (default: None) - LIMIT TO <3 CHAINS TO AVOID TIMEOUTS
sm_label_filter: List of smart money labels to filter by (default: None)
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
2. Flow Intelligence
Endpoint: POST /tgm/flow-intelligence
Credit Cost: 1 credit per call (requires attribution) Description: Token flow summary across different wallet categories
Request Parameters:
{
"parameters": {
"chain": "ethereum",
"tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"timeframe": "1d"
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
token_address: The contract address of the token
date_range: Date range dictionary with 'from' and 'to' keys (default: last 7 days)
chain: The blockchain to query (default: "ethereum")
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
Response Schema:
[
{
"publicFigureFlow": "1250000",
"publicFigureAvgAbsFlow": "125000",
"publicFigureWallets": "10",
"topPnlFlow": "2500000",
"topPnlAvgAbsFlow": "250000",
"topPnlWallets": "10",
"whaleFlow": "15000000",
"whaleAvgAbsFlow": "750000",
"whaleWallets": "20",
"smartTraderFlow": "8500000",
"smartTraderAvgAbsFlow": "425000",
"smartTraderWallets": "20",
"exchangeFlow": "-25000000",
"exchangeAvgAbsFlow": "2500000",
"exchangeWallets": "10",
"freshWalletsFlow": "1000000",
"freshWalletsAvgAbsFlow": "50000",
"freshWalletsWallets": "20"
}
]
3. Who Bought/Sold
Endpoint: POST /tgm/who-bought-sold
Credit Cost: 1 credit per call (requires attribution) Description: Aggregated buyer/seller data with trading volumes
Request Parameters:
{
"parameters": {
"chain": "ethereum",
"buyOrSell": "BUY",
"timeRange": {
"from": "2025-05-01",
"to": "2025-05-02"
},
"tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
token_address: The contract address of the token
buy_or_sell: "BUY" for buyers, "SELL" for sellers
time_range: Time range dictionary with 'from' and 'to' keys (default: last 1 day)
chain: The blockchain to query (default: "ethereum")
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
4. DEX Trades
Endpoint: POST /tgm/dex-trades
Credit Cost: 1 credit per call (requires attribution) Description: All DEX trades for specific tokens
Request Parameters:
{
"parameters": {
"chain": "ethereum",
"tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"onlySmartMoney": true,
"date": {
"from": "2025-05-01",
"to": "2025-05-03"
}
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
token_address: The contract address of the token
date_range: Date range dictionary with 'from' and 'to' keys (default: last 1 day)
chain: The blockchain to query (default: "ethereum")
only_smart_money: Return only Smart Money trades (default: False)
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
5. Token Transfers
Endpoint: POST /tgm/transfers
Credit Cost: 0 credits (FREE) Description: Top token transfers by value
Request Parameters:
{
"parameters": {
"chain": "ethereum",
"tokenAddress": "0x5a98fcbea516cf06857215779fd812ca3bef1b32",
"date": {
"from": "2025-05-01",
"to": "2025-05-03"
},
"dexIncluded": true,
"cexIncluded": true,
"onlySmartMoney": true
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
token_address: The contract address of the token
date_range: Date range dictionary with 'from' and 'to' keys (default: last 1 day)
chain: The blockchain to query (default: "ethereum")
dex_included: Whether to include DEX trades (default: True)
cex_included: Whether to include CEX transfers (default: True)
only_smart_money: Whether to include only Smart Money wallets (default: False)
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
6. Token Holders
Endpoint: POST /tgm/holders
Credit Cost: 5 credits per call (Restricted by default) Description: Top holders analysis with balance changes
Request Parameters:
{
"parameters": {
"chain": "ethereum",
"tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"date": {
"from": "2025-05-01",
"to": "2025-05-03"
},
"isEntity": false,
"includeLabels": [],
"label": "top_100_holders",
"isStablecoin": false
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Holder Types:
"smart_money"
with"includeLabels": ["Fund", "30D Smart Trader"]
"exchange"
with"includeLabels": ["Exchange"]
"top_100_holders"
for general top holders
Args:
token_address: The contract address of the token
date_range: Date range dictionary with 'from' and 'to' keys (default: last 1 day)
chain: The blockchain to query (default: "ethereum")
is_entity: Whether to return entity data (default: False)
include_labels: Labels to include (default: None)
label: Label type (default: "top_100_holders")
is_stablecoin: Whether the token is a stablecoin (default: False)
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
7. Token Flows
Endpoint: POST /tgm/flows
Credit Cost: 1 credit per call (requires attribution) Description: Historical inflows/outflows by holder categories
Request Parameters:
{
"parameters": {
"chain": "ethereum",
"tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"date": {
"from": "2025-05-01",
"to": "2025-05-03"
},
"label": "top_100_holders"
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
token_address: The contract address of the token
date_range: Date range dictionary with 'from' and 'to' keys (default: last 1 day)
chain: The blockchain to query (default: "ethereum")
label: Label type (default: "top_100_holders")
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
Holder Types:
"smart_money"
with"includeLabels": ["Fund", "30D Smart Trader"]
"exchange"
with"includeLabels": ["Exchange"]
"top_100_holders"
for general top holders
8. PnL Leaderboard
Endpoint: POST /tgm/pnl-leaderboard
Credit Cost: 5 credits per call (Restricted by default) Description: Top traders by realized/unrealized PnL for specific tokens
Request Parameters:
{
"parameters": {
"chain": "ethereum",
"date": {
"from": "2025-05-01",
"to": "2025-05-03"
},
"tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
token_address: The contract address of the token
date_range: Date range dictionary with 'from' and 'to' keys (default: last 30 days)
chain: The blockchain to query (default: "ethereum")
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
9. Jupiter DCA
Endpoint: POST /tgm/jup-dca
Credit Cost: 0 credits (FREE) Description: Jupiter DCA orders for tokens on Solana
Request Parameters:
{
"parameters": {
"chain": "solana",
"tokenAddress": "So11111111111111111111111111111111111111112",
"includeLabels": ["Smart Money"],
"excludeLabels": []
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
Args:
token_address: The contract address of the token
chain: The blockchain to query (default: "solana")
include_labels: Labels to include (default: None)
exclude_labels: Labels to exclude (default: None)
page: Page number for pagination (default: 1)
records_per_page: Number of results per page (default: 100)
Supported Chains
Arbitrum
arbitrum
✅
✅
✅
Avalanche
avalanche
✅
✅
✅
Base
base
✅
✅
✅
Berachain
berachain
✅
✅
✅
Bitcoin
bitcoin
✅
✅
-
BNB
bnb
✅
✅
✅
Blast
blast
✅
✅
✅
Ethereum
ethereum
✅
✅
✅
Fantom
fantom
✅
✅
✅
HyperEVM
hyperevm
✅
✅
✅
IOTA
iotaevm
✅
✅
✅
Linea
linea
✅
✅
✅
Mantle
mantle
✅
✅
✅
Optimism
optimism
✅
✅
✅
Polygon
polygon
✅
✅
✅
Ronin
ronin
✅
✅
✅
Scroll
scroll
✅
✅
✅
Sei
sei
✅
✅
✅
Solana
solana
✅
✅
✅
Sonic
sonic
✅
✅
✅
TON
ton
✅
✅
-
TRON
tron
✅
✅
-
Unichain
unichain
✅
✅
✅
zkSync
zksync
✅
✅
✅
Smart Money Labels
Available Smart Money filter options:
"30D Smart Trader"
- Top performers in last 30 days"90D Smart Trader"
- Top performers in last 90 days"180D Smart Trader"
- Top performers in last 180 days"Fund"
- Institutional funds and investment entities"Smart Trader"
- General high-performing traders
Error Handling
Common HTTP Status Codes:
200 OK
- Successful response400 Bad Request
- Invalid parameters or request format401 Unauthorized
- Missing or invalid API key403 Forbidden
- Insufficient subscription tier429 Too Many Requests
- Rate limit exceeded500 Internal Server Error
- Server error504 Gateway Timeout
- Request timeout
Performance Optimization Tips
Limit chains per request - Query max 2 chains simultaneously for better performance
Use shorter timeframes - 1 month lookback periods are faster than larger ranges
Apply filters - Use date ranges, volume filters, and specific token addresses
Implement pagination - Don't fetch large datasets in single requests
Cache responses - Store frequently accessed data locally when possible
Data Redistribution Guidelines
Endpoint Status Legend:
✅ Allowed - Can redistribute with proper attribution
⚠️ Restricted - Requires approval for redistribution
🚫 Prohibited - Cannot redistribute
Attribution Requirements:
Include backlink to Nansen.ai
Display "Powered by Nansen API" in your application
Attribution required for all public/commercial use
Contact: For restricted endpoints or enterprise usage, contact Nansen sales team.
Last updated
Was this helpful?