> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coingecko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DeFi & Onchain Analytics

> Analyze onchain token and pool data across 250+ networks, track DEX OHLCV and trade history, and monitor wallet distribution with token holder charts from CoinGecko API.

<Note>
  ### TL;DR

  Use [/onchain/simple/networks/../token\_price/..](/reference/onchain-simple-price) for onchain token pricing, [/onchain/networks/../pools/../ohlcv/..](/reference/pool-ohlcv-contract-address) for DEX candlestick data, [/onchain/networks/../pools/../trades](/reference/pool-trades-contract-address) for trade history, and [/onchain/networks/../tokens/../top\_holders](/reference/top-token-holders-token-address) to track wallet distribution.
</Note>

<br />

**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](#putting-it-all-together) 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**

<Tip>
  **Want to get started even faster?**<br />Copy the contents of this page from [defi-onchain-analytics.md](https://docs.coingecko.com/docs/defi-onchain-analytics.md) and paste it directly into your AI tool for instant context.
</Tip>

<Card title="Navigate the API faster with AI" icon="sparkles" href="https://docs.coingecko.com/skills">
  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.
</Card>

***

## Endpoint Overview

| Endpoint                                                                                      | What It Gives You                                                 | Best For                                          |
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------- |
| [/onchain/simple/networks/../token\_price/..](/reference/onchain-simple-price)                | Real-time token prices by contract address on any network         | Pricing DEX tokens across 250+ networks           |
| [/onchain/networks/../tokens/../](/reference/token-data-contract-address)                     | Token market data including price, volume, FDV, and price changes | Onchain token analytics and screening             |
| [/onchain/networks/../tokens/../info](/reference/token-info-contract-address)                 | Token metadata, socials, websites, and analytics score            | Researching token fundamentals                    |
| [/onchain/networks/../pools/../](/reference/pool-address)                                     | Pool details with reserve, volume, price, and transaction counts  | Analyzing pool liquidity and activity             |
| [/onchain/networks/trending\_pools](/reference/trending-pools-list)                           | Trending liquidity pools across all networks                      | Discovering hot pools and new opportunities       |
| [/onchain/pools/megafilter](/reference/pools-megafilter)                                      | Pools filtered by volume, liquidity, age, network, and more       | Advanced pool screening and discovery             |
| [/onchain/networks/../pools/../ohlcv/..](/reference/pool-ohlcv-contract-address)              | Pool-level OHLCV with minute and second granularity               | DEX candlestick charts and technical analysis     |
| [/onchain/networks/../tokens/../ohlcv/..](/reference/token-ohlcv-token-address)               | Token-level OHLCV aggregated across all pools                     | Token price charts independent of any single pool |
| [/onchain/networks/../pools/../trades](/reference/pool-trades-contract-address)               | Last 300 trades in the past 24 hours for a pool                   | Trade monitoring and execution analysis           |
| [/onchain/networks/../tokens/../trades](/reference/token-trades-contract-address)             | Last 300 trades across all pools for a token                      | Cross-pool trade activity tracking                |
| [/onchain/networks/../tokens/../top\_holders](/reference/top-token-holders-token-address)     | Top token holders with balances and ownership percentages         | Whale tracking and concentration analysis         |
| [/onchain/networks/../tokens/../holders\_chart](/reference/token-holders-chart-token-address) | Historical holder count over time                                 | Tracking adoption trends and distribution changes |

<Callout icon="key" color="#FFC107" iconType="regular">
  Replace `YOUR_API_KEY` in the examples below with your actual CoinGecko API key.<br />Don't have one yet? [Get your API key here](https://www.coingecko.com/en/api/pricing).
</Callout>

***

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

*🔗 More endpoint details [here](/reference/onchain-simple-price)*

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:**

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

**Key parameters:**

| Parameter          | Why It Matters                                                     |
| ------------------ | ------------------------------------------------------------------ |
| `network` (path)   | The blockchain network (e.g., `eth`, `solana`, `base`, `arbitrum`) |
| `addresses` (path) | Comma-separated token contract addresses to price                  |

**Response highlights:**

<CodeGroup>
  ```json JSON theme={null}
  {
    "data": {
      "id": "eth_0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "type": "simple_token_price",
      "attributes": {
        "token_prices": {
          "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": "1.0",
          "0x6b175474e89094c44da98b954eedeac495271d0f": "0.9998"
        }
      }
    }
  }
  ```
</CodeGroup>

<Tip>
  Use the [/onchain/networks](/reference/networks-list) endpoint to get the full list of 250+ supported networks and their identifiers.
</Tip>

***

## Token Data and Metadata

### `/onchain/networks/{network}/tokens/{address}`

*🔗 More endpoint details [here](/reference/token-data-contract-address)*

Returns comprehensive market data for an onchain token - price, volume, FDV, market cap, price changes across multiple timeframes, and transaction counts.

**Example request:**

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

**Key parameters:**

| Parameter        | Why It Matters                                              |
| ---------------- | ----------------------------------------------------------- |
| `network` (path) | The blockchain network                                      |
| `address` (path) | Token contract address                                      |
| `include`        | Add `top_pools` to see the most active pools for this token |

**Response highlights:**

<CodeGroup>
  ```json JSON theme={null}
  {
    "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 }
        }
      }
    }
  }
  ```
</CodeGroup>

### `/onchain/networks/{network}/tokens/{address}/info`

*🔗 More endpoint details [here](/reference/token-info-contract-address)*

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:**

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

**Response highlights:**

<CodeGroup>
  ```json JSON theme={null}
  {
    "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"
      }
    }
  }
  ```
</CodeGroup>

<Tip>
  The `coingecko_coin_id` field bridges onchain data to CoinGecko's main API - use it to cross-reference with [/coins/\{id}](/reference/coins-id) for community data, developer metrics, and more.
</Tip>

***

## Pool Discovery and Liquidity

### `/onchain/networks/{network}/pools/{address}`

*🔗 More endpoint details [here](/reference/pool-address)*

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:**

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

**Key parameters:**

| Parameter        | Why It Matters                                               |
| ---------------- | ------------------------------------------------------------ |
| `address` (path) | The pool contract address                                    |
| `include`        | Add `base_token`, `quote_token`, `dex` for full pool context |

**Response highlights:**

<CodeGroup>
  ```json JSON theme={null}
  {
    "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 } }
      }
    }
  }
  ```
</CodeGroup>

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](/reference/trending-pools-list)*

Surfaces the hottest liquidity pools across all networks - useful for spotting early DeFi momentum and new token launches gaining traction.

**Example request:**

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

**Key parameters:**

| Parameter  | Why It Matters                                                       |
| ---------- | -------------------------------------------------------------------- |
| `include`  | Add `base_token`, `quote_token`, `dex`, `network` for richer context |
| `duration` | Filter by `1h`, `6h`, or `24h` trending window                       |
| `page`     | Paginate through results                                             |

**Response highlights:**

<CodeGroup>
  ```json JSON theme={null}
  {
    "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 } }
        }
      }
    ]
  }
  ```
</CodeGroup>

<Tip>
  To narrow results to a specific chain, use the [/onchain/networks/\{network}/trending\_pools](/reference/trending-pools-network) endpoint instead.
</Tip>

### `/onchain/pools/megafilter`

*🔗 More endpoint details [here](/reference/pools-megafilter)*

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:**

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

**Key parameters:**

| Parameter                                   | Why It Matters                                                                           |
| ------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `networks`                                  | Filter by specific chains (e.g., `eth,solana,base`)                                      |
| `volume_24h_usd_min` / `volume_24h_usd_max` | Set volume thresholds to find active pools                                               |
| `reserve_usd_min` / `reserve_usd_max`       | Filter by liquidity depth                                                                |
| `sort`                                      | Sort by `volume_24h_usd_desc`, `reserve_usd_desc`, `h24_price_change_percent_desc`, etc. |
| `pool_age_min` / `pool_age_max`             | Filter by pool age in hours - useful for finding new pools                               |

**Response highlights:**

<CodeGroup>
  ```json JSON theme={null}
  {
    "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" } }
        }
      }
    ]
  }
  ```
</CodeGroup>

***

## DEX OHLCV Charts

### `/onchain/networks/{network}/pools/{pool_address}/ohlcv/{timeframe}`

*🔗 More endpoint details [here](/reference/pool-ohlcv-contract-address)*

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):

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

**Key parameters:**

| Parameter          | Why It Matters                                                    |
| ------------------ | ----------------------------------------------------------------- |
| `timeframe` (path) | Choose `second`, `minute`, `hour`, or `day`                       |
| `aggregate`        | Combine candles (e.g., `5` for 5-minute, `4` for 4-hour candles)  |
| `limit`            | Up to 1000 data points per request                                |
| `before_timestamp` | Paginate backward in time for historical data                     |
| `currency`         | `usd` for fiat-denominated or `token` for base-token denomination |

**Response highlights:**

<CodeGroup>
  ```json JSON theme={null}
  {
    "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]
        ]
      }
    }
  }
  ```
</CodeGroup>

Each entry is `[timestamp, open, high, low, close, volume]`.

### `/onchain/networks/{network}/tokens/{token_address}/ohlcv/{timeframe}`

*🔗 More endpoint details [here](/reference/token-ohlcv-token-address)*

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):

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

**Key parameters:**

| Parameter          | Why It Matters                                        |
| ------------------ | ----------------------------------------------------- |
| `timeframe` (path) | Choose `second`, `minute`, `hour`, or `day`           |
| `aggregate`        | Combine candles for wider timeframes                  |
| `currency`         | `usd` for fiat or `token` for base-token denomination |

<Note>
  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.
</Note>

***

## Onchain Trade History

### `/onchain/networks/{network}/pools/{pool_address}/trades`

*🔗 More endpoint details [here](/reference/pool-trades-contract-address)*

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:**

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

**Key parameters:**

| Parameter                          | Why It Matters                                          |
| ---------------------------------- | ------------------------------------------------------- |
| `trade_volume_in_usd_greater_than` | Filter out noise - only see trades above your threshold |

**Response highlights:**

<CodeGroup>
  ```json JSON theme={null}
  {
    "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"
        }
      }
    ]
  }
  ```
</CodeGroup>

### `/onchain/networks/{network}/tokens/{token_address}/trades`

*🔗 More endpoint details [here](/reference/token-trades-contract-address)*

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:**

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

**Key parameters:**

| Parameter                          | Why It Matters                      |
| ---------------------------------- | ----------------------------------- |
| `trade_volume_in_usd_greater_than` | Filter by minimum trade size in USD |

<Tip>
  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.
</Tip>

***

## Token Holder Analytics

### `/onchain/networks/{network}/tokens/{address}/top_holders`

*🔗 More endpoint details [here](/reference/top-token-holders-token-address)*

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:**

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

**Response highlights:**

<CodeGroup>
  ```json JSON theme={null}
  {
    "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"
        }
      }
    ]
  }
  ```
</CodeGroup>

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](/reference/token-holders-chart-token-address)*

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:**

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

**Key parameters:**

| Parameter   | Why It Matters                            |
| ----------- | ----------------------------------------- |
| `timeframe` | Choose the time window for the chart data |

**Response highlights:**

<CodeGroup>
  ```json JSON theme={null}
  {
    "data": {
      "attributes": {
        "holders_chart": [
          { "date": "2024-03-01", "count": 156789 },
          { "date": "2024-03-02", "count": 158234 },
          { "date": "2024-03-03", "count": 159876 }
        ]
      }
    }
  }
  ```
</CodeGroup>

<Tip>
  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.
</Tip>

***

## 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

<br />

<Card title="Integrate with CoinGecko MCP Server" icon="server" href="https://docs.coingecko.com/docs/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.
</Card>

***

Have feedback or need help? Reach out to `eason.lim@coingecko[dot]com`


Built with [Mintlify](https://mintlify.com).