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)

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 days

  • buyVolume - Total buy-side volume

  • sellVolume - Total sell-side volume

  • volume - Total trading volume

  • liquidity - Liquidity in pools (USD equivalent)

  • marketCap - Market capitalization

  • fdv - Fully Diluted Valuation

  • netflow - Net inflow (inflows - outflows)

  • holders - Number of token holders

  • nofBuyers - Count of unique buyers

  • nofSellers - Count of unique sellers

  • priceChange - 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

Chain Name
Parameter Value
Profiler
Token God Mode
Smart Money

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 response

  • 400 Bad Request - Invalid parameters or request format

  • 401 Unauthorized - Missing or invalid API key

  • 403 Forbidden - Insufficient subscription tier

  • 429 Too Many Requests - Rate limit exceeded

  • 500 Internal Server Error - Server error

  • 504 Gateway Timeout - Request timeout

Performance Optimization Tips

  1. Limit chains per request - Query max 2 chains simultaneously for better performance

  2. Use shorter timeframes - 1 month lookback periods are faster than larger ranges

  3. Apply filters - Use date ranges, volume filters, and specific token addresses

  4. Implement pagination - Don't fetch large datasets in single requests

  5. 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?