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

Overview

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

Important Notes:

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

  • All endpoints focus on Smart Trader and Fund labels only

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

1. Smart Traders and Funds Token Balances (Aggregated)

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

Request Parameters:

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

Args:

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

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

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

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

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

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

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

Response Schema:

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

2. Smart Traders and Funds DEX Trade Transactions

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

Request Parameters:

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

Args:

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

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

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

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

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

Response Schema:

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

3. Smart Traders and Funds Net Flows (Aggregated)

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

Request Parameters:

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

Args:

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

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

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

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

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

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

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

Response Schema:

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

Note: Volume values represent net flows where:

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

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

4. Smart Traders and Funds DCAs (Solana)

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

Request Parameters:

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

Args:

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

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

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

  • tokenaddress: Optional token address to filter by

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

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

Response Schema:

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

Smart Money Labels

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

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

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

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

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

  • "Fund" - Institutional funds and investment entities

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

Chain Support for Smart Money

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

Chain
Supported

Arbitrum

Avalanche

Base

Berachain

BNB

Blast

Ethereum

Fantom

HyperEVM

IOTA

Linea

Mantle

Optimism

Polygon

Ronin

Scroll

Sei

Solana

Sonic

TON

⚠️ Limited

TRON

⚠️ Limited

Unichain

zkSync

Profiler API Endpoints

Overview

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

1. Address Balances

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

Request Parameters:

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

Args:

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

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

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

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

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

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

Response Schema:

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

2. Address Historical Balances

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

Request Parameters:

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

Args:

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

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

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

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

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

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

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

3. Address Transactions

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

Request Parameters:

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

Args:

  • walletAddresses: A single address to query (required)

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

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

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

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

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

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

4. Address Counterparties

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

Request Parameters:

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

Args:

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

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

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

  • groupBy: "wallet" or "entity"

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

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

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

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

Tips for Finding Related Wallets:

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

  • Include CEX deposit addresses (NOT withdrawal addresses)

  • Go one level deeper:

    • Find addresses that interacted with the most likely addresses

    • Find addresses that deposited to the same CEX deposit addresses

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

Response includes:

  • Interacting addresses and labels

  • USD volume in/out

  • Number of transactions in/out

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

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

Request Parameters:

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

Args:

  • walletAddresses: List of addresses to query

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

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

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

Special Connections Include:

  • First Funder

  • Signer / Previous Signer

  • Multisig Signer of / Previous Multisig Signer of

  • Deployed via / Deployed by

  • Deployed Contract / Created Contract / Created by

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

6. Wallet PnL Summary

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

Request Parameters:

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

Args:

  • walletAddress: The wallet address to analyze

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

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

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

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

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

7. Wallet PnL for Token

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

Request Parameters:

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

Args:

  • walletAddress: The wallet address to analyze

  • tokenAddress: Token address to generate PnL stats for

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

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

  • showRealized: Include realized profit or not

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

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

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

Response includes:

  • Token price and ROI (realized/unrealized)

  • PnL in USD (realized/unrealized)

  • Bought/sold amounts and USD values

  • Cost basis and average sold price

  • Current holdings

  • Number of buy/sell transactions

  • Maximum balance held

8. Address Transactions for Token

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

Request Parameters:

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

Args:

  • walletAddress: The address to analyze

  • tokenAddress: The token address to analyze

  • datetimeFrom: Start datetime in ISO format

  • datetimeTo: End datetime in ISO format

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

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

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

Chain Support Note

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

Token God Mode API Endpoints

Overview

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

Performance Warning:

  • Use ≤ 3 chains at a time to avoid timeouts

  • Recommended chain triplets:

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

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

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

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

1. Token Screener

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

Request Structure:

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

Available Filters:

  • tokenAgeDays - Token age in days

  • buyVolume - Total buy-side volume

  • sellVolume - Total sell-side volume

  • volume - Total trading volume

  • liquidity - DEX liquidity (USD)

  • marketCap - Market capitalization

  • fdv - Fully Diluted Valuation

  • netflow - Net inflow (buys - sells)

  • holders - Number of token holders

  • nofBuyers - Count of unique buyers

  • nofSellers - Count of unique sellers

  • nofTxs - Number of transactions

  • nofTraders - Number of traders

  • priceChange - Price change percentage

Example Use Cases:

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

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

2. Token Holders

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

Request Parameters:

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

Holder Type Options:

  • "top_100_holders" - General top holders (default)

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

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

Response includes:

  • Current balance and USD value

  • Ownership percentage

  • 24h, 7d, 30d balance changes

  • Total sent/received amounts

3. Token DEX Trades

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

Request Parameters:

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

Response includes:

  • Trade timestamp and direction (BUY/SELL)

  • Token amounts and symbols

  • USD value and price

  • Trader address and label

  • Transaction hash

4. Token Transfers

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

Request Parameters:

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

5. Token Flows

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

Request Parameters:

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

Response tracks:

  • Daily price and total balance

  • Number of holders

  • Inflows and outflows

  • USD value of holdings

6. Token Flow Intelligence

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

Request Parameters:

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

Categories analyzed:

  • Public Figures (celebrities/influencers)

  • Top PnL Traders (profitable addresses)

  • Whales (high-balance wallets)

  • Smart Traders (consistently profitable)

  • Exchanges (CEX flows)

  • Fresh Wallets (newly created)

Note: The API uses timeframe parameter, not date_range.

7. Who Bought/Sold

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

Request Parameters:

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

Args:

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

  • Shows aggregated volumes in both tokens and USD

8. PnL Leaderboard

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

Request Parameters:

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

Response includes:

  • Realized and unrealized PnL

  • Win rate percentage

  • Total trades and average trade size

9. Jupiter DCA (Solana)

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

Request Parameters:

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

Date Range Support

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

Performance Best Practices

  1. Chain Limits: Query maximum 3 chains per request

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

  3. Filtering: Apply filters to reduce result set size

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

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

Response Data Notes

  • Positive net flows = more buying than selling

  • Negative exchange flows = tokens leaving exchanges (bullish)

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

  • Smart Money = addresses with profitable trading history

Supported Chains

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

Last updated

Was this helpful?