Skip to main content

​
TL;DR

Use /onchain/simple/networks/../token_price/.. for onchain token pricing, /onchain/networks/../pools/../ohlcv/.. for DEX candlestick data, /onchain/networks/../pools/../trades for trade history, and /onchain/networks/../tokens/../top_holders to track wallet distribution.

Onchain analytics gives you a direct view into what’s happening on the blockchain - whether you’re tracking DEX liquidity and trading activity, analyzing token holder distribution, or building dashboards that surface real-time pool metrics across 250+ networks. This guide walks you through the CoinGecko API endpoints that matter most for DeFi and onchain analytics workflows, and ties them together into a complete workflow at the end:
  • Onchain token and pool data across 250+ supported networks via GeckoTerminal
  • DEX OHLCV, liquidity, and trade history for granular market analysis
  • Token holder charts to track wallet distribution and concentration over time
Estimated reading time: 12 minutes
Want to get started even faster?
Copy the contents of this page from defi-onchain-analytics.md and paste it directly into your AI tool for instant context.

Navigate the API faster with AI

Install the CoinGecko SKILL to give your AI coding agent built-in knowledge of every endpoint, parameter, and workflow. Setup takes less than 3 minutes.

​
Endpoint Overview

EndpointWhat It Gives YouBest For
/onchain/simple/networks/../token_price/..Real-time token prices by contract address on any networkPricing DEX tokens across 250+ networks
/onchain/networks/../tokens/../Token market data including price, volume, FDV, and price changesOnchain token analytics and screening
/onchain/networks/../tokens/../infoToken metadata, socials, websites, and analytics scoreResearching token fundamentals
/onchain/networks/../pools/../Pool details with reserve, volume, price, and transaction countsAnalyzing pool liquidity and activity
/onchain/networks/trending_poolsTrending liquidity pools across all networksDiscovering hot pools and new opportunities
/onchain/pools/megafilterPools filtered by volume, liquidity, age, network, and moreAdvanced pool screening and discovery
/onchain/networks/../pools/../ohlcv/..Pool-level OHLCV with minute and second granularityDEX candlestick charts and technical analysis
/onchain/networks/../tokens/../ohlcv/..Token-level OHLCV aggregated across all poolsToken price charts independent of any single pool
/onchain/networks/../pools/../tradesLast 300 trades in the past 24 hours for a poolTrade monitoring and execution analysis
/onchain/networks/../tokens/../tradesLast 300 trades across all pools for a tokenCross-pool trade activity tracking
/onchain/networks/../tokens/../top_holdersTop token holders with balances and ownership percentagesWhale tracking and concentration analysis
/onchain/networks/../tokens/../holders_chartHistorical holder count over timeTracking adoption trends and distribution changes
Replace YOUR_API_KEY in the examples below with your actual CoinGecko API key.
Don’t have one yet? Get your API key here.

​
Onchain Token Pricing - /onchain/simple/networks/{network}/token_price/{addresses}

🔗 More endpoint details here The fastest way to get real-time prices for any onchain token by contract address - including tokens not yet listed on CoinGecko’s main platform. Supports querying multiple token addresses in a single call. Example request: 
curl -X GET "https://pro-api.coingecko.com/api/v3/onchain/simple/networks/eth/token_price/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48,0x6b175474e89094c44da98b954eedeac495271d0f" \
  -H "x-cg-pro-api-key: YOUR_API_KEY"
Key parameters:
ParameterWhy It Matters
network (path)The blockchain network (e.g., eth, solana, base, arbitrum)
addresses (path)Comma-separated token contract addresses to price
Response highlights: 
{
  "data": {
    "id": "eth_0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "type": "simple_token_price",
    "attributes": {
      "token_prices": {
        "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": "1.0",
        "0x6b175474e89094c44da98b954eedeac495271d0f": "0.9998"
      }
    }
  }
}
Use the /onchain/networks endpoint to get the full list of 250+ supported networks and their identifiers.

​
Token Data and Metadata

​
/onchain/networks/{network}/tokens/{address}

🔗 More endpoint details here Returns comprehensive market data for an onchain token - price, volume, FDV, market cap, price changes across multiple timeframes, and transaction counts. Example request: 
curl -X GET "https://pro-api.coingecko.com/api/v3/onchain/networks/eth/tokens/0x6982508145454ce325ddbe47a25d4ec3d2311933?include=top_pools" \
  -H "x-cg-pro-api-key: YOUR_API_KEY"
Key parameters:
ParameterWhy It Matters
network (path)The blockchain network
address (path)Token contract address
includeAdd top_pools to see the most active pools for this token
Response highlights: 
{
  "data": {
    "id": "eth_0x6982508145454ce325ddbe47a25d4ec3d2311933",
    "type": "token",
    "attributes": {
      "name": "Pepe",
      "symbol": "PEPE",
      "fdv_usd": "3456789012",
      "market_cap_usd": "3210456789",
      "total_supply": "420690000000000",
      "volume_usd": { "h24": "234567890" },
      "price_change_percentage": {
        "h1": "0.45",
        "h24": "5.67",
        "h6": "2.34"
      },
      "total_reserve_in_usd": "45678901",
      "transactions": {
        "h24": { "buys": 8765, "sells": 7654, "buyers": 4321, "sellers": 3456 }
      }
    }
  }
}

​
/onchain/networks/{network}/tokens/{address}/info

🔗 More endpoint details here Get rich metadata for any onchain token - description, socials, websites, and GeckoTerminal analytics score. Essential for building token profile pages or research dashboards. Example request: 
curl -X GET "https://pro-api.coingecko.com/api/v3/onchain/networks/eth/tokens/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/info" \
  -H "x-cg-pro-api-key: YOUR_API_KEY"
Response highlights: 
{
  "data": {
    "attributes": {
      "name": "USD Coin",
      "symbol": "USDC",
      "coingecko_coin_id": "usd-coin",
      "description": "USDC is a fully collateralized US dollar stablecoin...",
      "websites": ["https://www.circle.com/en/usdc"],
      "gt_score": 92.34,
      "discord_url": "https://...",
      "twitter_handle": "circle"
    }
  }
}
The coingecko_coin_id field bridges onchain data to CoinGecko’s main API - use it to cross-reference with /coins/{id} for community data, developer metrics, and more.

​
Pool Discovery and Liquidity

​
/onchain/networks/{network}/pools/{address}

🔗 More endpoint details here Returns detailed data for a specific liquidity pool - reserve (TVL), volume, price, transaction counts, and price change metrics. The core endpoint for analyzing pool health and activity. Example request: 
curl -X GET "https://pro-api.coingecko.com/api/v3/onchain/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640?include=base_token,quote_token,dex" \
  -H "x-cg-pro-api-key: YOUR_API_KEY"
Key parameters:
ParameterWhy It Matters
address (path)The pool contract address
includeAdd base_token, quote_token, dex for full pool context
Response highlights: 
{
  "data": {
    "type": "pool",
    "attributes": {
      "name": "USDC / WETH 0.05%",
      "base_token_price_usd": "3456.78",
      "quote_token_price_usd": "1.0",
      "reserve_in_usd": "234567890",
      "pool_created_at": "2022-05-04T12:00:00Z",
      "fdv_usd": "415678901234",
      "volume_usd": { "h1": "5678901", "h24": "123456789" },
      "price_change_percentage": { "h1": "0.12", "h24": "2.34" },
      "transactions": { "h24": { "buys": 12345, "sells": 10234 } }
    }
  }
}
The reserve_in_usd field is your liquidity indicator - it shows the total value locked in the pool.

​
/onchain/networks/trending_pools

🔗 More endpoint details here Surfaces the hottest liquidity pools across all networks - useful for spotting early DeFi momentum and new token launches gaining traction. Example request: 
curl -X GET "https://pro-api.coingecko.com/api/v3/onchain/networks/trending_pools?include=base_token,dex,network&duration=24h" \
  -H "x-cg-pro-api-key: YOUR_API_KEY"
Key parameters:
ParameterWhy It Matters
includeAdd base_token, quote_token, dex, network for richer context
durationFilter by 1h, 6h, or 24h trending window
pagePaginate through results
Response highlights: 
{
  "data": [
    {
      "type": "pool",
      "attributes": {
        "name": "USDC / WETH",
        "base_token_price_usd": "3456.78",
        "reserve_in_usd": "234567890",
        "volume_usd": { "h24": "123456789" },
        "price_change_percentage": { "h24": "2.34" },
        "transactions": { "h24": { "buys": 12345, "sells": 10234 } }
      }
    }
  ]
}
To narrow results to a specific chain, use the /onchain/networks/{network}/trending_pools endpoint instead.

​
/onchain/pools/megafilter

🔗 More endpoint details here The most powerful pool discovery endpoint - filter pools by volume, liquidity, age, network, DEX, and more. Ideal for building custom screeners or finding pools that match specific criteria. Example request: 
curl -X GET "https://pro-api.coingecko.com/api/v3/onchain/pools/megafilter?networks=eth,solana&volume_24h_usd_min=100000&reserve_usd_min=50000&sort=volume_24h_usd_desc" \
  -H "x-cg-pro-api-key: YOUR_API_KEY"
Key parameters:
ParameterWhy It Matters
networksFilter by specific chains (e.g., eth,solana,base)
volume_24h_usd_min / volume_24h_usd_maxSet volume thresholds to find active pools
reserve_usd_min / reserve_usd_maxFilter by liquidity depth
sortSort by volume_24h_usd_desc, reserve_usd_desc, h24_price_change_percent_desc, etc.
pool_age_min / pool_age_maxFilter by pool age in hours - useful for finding new pools
Response highlights: 
{
  "data": [
    {
      "type": "pool",
      "attributes": {
        "name": "WETH / USDC",
        "reserve_in_usd": "234567890",
        "volume_usd": { "h24": "123456789" },
        "price_change_percentage": { "h24": "2.34" },
        "pool_created_at": "2022-05-04T12:00:00Z"
      },
      "relationships": {
        "network": { "data": { "id": "eth" } },
        "dex": { "data": { "id": "uniswap_v3" } }
      }
    }
  ]
}

​
DEX OHLCV Charts

​
/onchain/networks/{network}/pools/{pool_address}/ohlcv/{timeframe}

🔗 More endpoint details here Returns OHLCV candle data for a specific pool - with day, hour, minute, and second timeframes and customizable aggregation periods. The foundation for DEX candlestick charts and technical analysis. Example request (5-minute candles for a Uniswap V3 ETH/USDC pool): 
curl -X GET "https://pro-api.coingecko.com/api/v3/onchain/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640/ohlcv/minute?aggregate=5&limit=100&currency=usd" \
  -H "x-cg-pro-api-key: YOUR_API_KEY"
Key parameters:
ParameterWhy It Matters
timeframe (path)Choose second, minute, hour, or day
aggregateCombine candles (e.g., 5 for 5-minute, 4 for 4-hour candles)
limitUp to 1000 data points per request
before_timestampPaginate backward in time for historical data
currencyusd for fiat-denominated or token for base-token denomination
Response highlights: 
{
  "data": {
    "attributes": {
      "ohlcv_list": [
        [1709424300, 3456.78, 3462.10, 3450.00, 3458.90, 1234567.89],
        [1709424600, 3458.90, 3470.00, 3455.20, 3465.45, 987654.32]
      ]
    }
  }
}
Each entry is [timestamp, open, high, low, close, volume].

​
/onchain/networks/{network}/tokens/{token_address}/ohlcv/{timeframe}

🔗 More endpoint details here Similar to pool OHLCV, but aggregated across all pools for a given token. Use this when you want a token’s overall price action rather than a single pool’s perspective. Example request (daily candles for PEPE): 
curl -X GET "https://pro-api.coingecko.com/api/v3/onchain/networks/eth/tokens/0x6982508145454ce325ddbe47a25d4ec3d2311933/ohlcv/day?aggregate=1&limit=30&currency=usd" \
  -H "x-cg-pro-api-key: YOUR_API_KEY"
Key parameters:
ParameterWhy It Matters
timeframe (path)Choose second, minute, hour, or day
aggregateCombine candles for wider timeframes
currencyusd for fiat or token for base-token denomination
Pool OHLCV reflects a single pool’s price action, while Token OHLCV aggregates across all pools for that token. Use Token OHLCV for a broader market view, and Pool OHLCV for DEX-specific analysis.

​
Onchain Trade History

​
/onchain/networks/{network}/pools/{pool_address}/trades

🔗 More endpoint details here Returns the last 300 trades in the past 24 hours for a specific pool - useful for monitoring execution, analyzing trade size distribution, or triggering alerts on large swaps. Example request: 
curl -X GET "https://pro-api.coingecko.com/api/v3/onchain/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640/trades?trade_volume_in_usd_greater_than=10000" \
  -H "x-cg-pro-api-key: YOUR_API_KEY"
Key parameters:
ParameterWhy It Matters
trade_volume_in_usd_greater_thanFilter out noise - only see trades above your threshold
Response highlights: 
{
  "data": [
    {
      "attributes": {
        "block_number": 19345678,
        "block_timestamp": "2024-03-15T10:30:00Z",
        "kind": "buy",
        "volume_in_usd": "52345.67",
        "from_token_amount": "15.234",
        "to_token_amount": "52345.67",
        "price_from_in_usd": "3437.12",
        "tx_hash": "0xabc...def"
      }
    }
  ]
}

​
/onchain/networks/{network}/tokens/{token_address}/trades

🔗 More endpoint details here Returns the last 300 trades across all pools for a given token - gives you a complete picture of trading activity regardless of which pool the trade happened in. Example request: 
curl -X GET "https://pro-api.coingecko.com/api/v3/onchain/networks/eth/tokens/0x6982508145454ce325ddbe47a25d4ec3d2311933/trades?trade_volume_in_usd_greater_than=5000" \
  -H "x-cg-pro-api-key: YOUR_API_KEY"
Key parameters:
ParameterWhy It Matters
trade_volume_in_usd_greater_thanFilter by minimum trade size in USD
Use pool trades when analyzing a specific trading venue. Use token trades when you need a cross-pool view of all trading activity for a token.

​
Token Holder Analytics

​
/onchain/networks/{network}/tokens/{address}/top_holders

🔗 More endpoint details here Returns the top token holders with their wallet addresses, balances, and ownership percentages. Essential for analyzing token concentration, tracking whale wallets, and assessing distribution health. Example request: 
curl -X GET "https://pro-api.coingecko.com/api/v3/onchain/networks/eth/tokens/0x6982508145454ce325ddbe47a25d4ec3d2311933/top_holders" \
  -H "x-cg-pro-api-key: YOUR_API_KEY"
Response highlights: 
{
  "data": [
    {
      "attributes": {
        "wallet_address": "0x1234...abcd",
        "wallet_tag": "Binance",
        "balance": "50000000000000",
        "ownership_percentage": "11.88",
        "value_usd": "410000000"
      }
    },
    {
      "attributes": {
        "wallet_address": "0x5678...efgh",
        "wallet_tag": null,
        "balance": "25000000000000",
        "ownership_percentage": "5.94",
        "value_usd": "205000000"
      }
    }
  ]
}
The wallet_tag field identifies known entities (exchanges, protocols, treasuries) - helping you distinguish between institutional and retail holders.

​
/onchain/networks/{network}/tokens/{address}/holders_chart

🔗 More endpoint details here Returns the historical holder count over time - track how the number of unique wallets holding a token changes. A rising holder count often signals growing adoption, while a declining count may indicate distribution concerns. Example request: 
curl -X GET "https://pro-api.coingecko.com/api/v3/onchain/networks/eth/tokens/0x6982508145454ce325ddbe47a25d4ec3d2311933/holders_chart?timeframe=one_month" \
  -H "x-cg-pro-api-key: YOUR_API_KEY"
Key parameters:
ParameterWhy It Matters
timeframeChoose the time window for the chart data
Response highlights: 
{
  "data": {
    "attributes": {
      "holders_chart": [
        { "date": "2024-03-01", "count": 156789 },
        { "date": "2024-03-02", "count": 158234 },
        { "date": "2024-03-03", "count": 159876 }
      ]
    }
  }
}
Combine top holders data with the holders chart for a complete distribution analysis - top holders shows current concentration, while the chart reveals the adoption trend over time.

​
Putting It All Together

Here’s how these endpoints fit into a typical DeFi and onchain analytics workflow:
  1. Get token prices - Use /onchain/simple/networks/{network}/token_price/{addresses} for real-time onchain pricing
  2. Research token fundamentals - Query token data and token info endpoints for market metrics and metadata
  3. Discover active pools - Check /onchain/networks/trending_pools or use megafilter for custom screening
  4. Analyze pool liquidity - Pull pool details to assess reserve depth, volume, and transaction activity
  5. Chart price action - Fetch pool or token OHLCV for candlestick charts at any granularity
  6. Monitor trades - Use pool or token trades endpoints to track recent swap activity
  7. Assess token distribution - Query top holders and holders chart to evaluate concentration and adoption trends

Integrate with CoinGecko MCP Server

Connect your AI agent directly to CoinGecko’s API using our MCP server - enabling real-time crypto data queries from tools like Claude Desktop, Cursor, and more.
Have feedback or need help? Reach out to eason.lim@coingecko[dot]com