geckoterminal-api

name	geckoterminal-api
version	1.1.0
description	GeckoTerminal API - DeFi and DEX aggregator providing real-time cryptocurrency prices, trading volumes, OHLCV charts, and liquidity data across 250+ blockchain networks and 1,800+ decentralized exchanges

GeckoTerminal API Skill

GeckoTerminal is a DeFi and DEX aggregator that provides real-time cryptocurrency prices, trading volumes, transactions, and liquidity data across decentralized exchanges. The API enables developers to access on-chain market data for any token using its contract address.

Key Value Proposition: Access live, on-chain market data for 6M+ tokens across 250+ blockchain networks and 1,800+ DEXes - all indexed by contract address rather than ticker symbols, enabling queries for tokens not listed on centralized exchanges.

When to Use This Skill

• Querying real-time prices for tokens on decentralized exchanges
• Building DeFi dashboards with live pool and token data
• Fetching OHLCV candlestick data for charting applications
• Discovering trending or newly created liquidity pools
• Tracking trading activity and transactions for specific pools
• Finding all pools trading a specific token across DEXes
• Building trading bots that need on-chain price feeds
• Analyzing liquidity and volume across multiple chains

When NOT to Use This Skill

• For centralized exchange (CEX) data (use CoinGecko or exchange APIs)
• For tokens only on CEXes with no DEX liquidity
• For market cap data (use CoinGecko API for verified supply data)
• For high-frequency trading requiring <1 second updates (rate limits apply)
• For historical data beyond 6 months (OHLCV limitation)
• For off-chain order book data (GeckoTerminal is AMM/DEX focused)

---

Core Concepts

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                    GeckoTerminal API v2                         │
│                 api.geckoterminal.com/api/v2                    │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│   Networks    │    │    Tokens     │    │    Pools      │
│   & DEXes     │    │               │    │               │
├───────────────┤    ├───────────────┤    ├───────────────┤
│ /networks     │    │ /tokens/...   │    │ /pools/...    │
│ /dexes        │    │ /simple/...   │    │ /trending_... │
│ 250+ chains   │    │ 6M+ tokens    │    │ /new_pools    │
└───────────────┘    └───────────────┘    └───────────────┘
        │                     │                     │
        └─────────────────────┼─────────────────────┘
                              │
                              ▼
                    ┌───────────────────┐
                    │   Market Data     │
                    ├───────────────────┤
                    │ • OHLCV Charts    │
                    │ • Trade History   │
                    │ • Pool Analytics  │
                    │ • Price Changes   │
                    └───────────────────┘

Key Differences from CoinGecko

Feature	GeckoTerminal	CoinGecko
Data Source	On-chain DEX only	CEX + DEX
Token ID	Contract address	Coin ID (slug)
Coverage	All traded tokens	Listed tokens only
OHLCV Source	On-chain trades	Exchange feeds
Market Cap	FDV only (on-chain)	Verified supply data

---

API Basics

Base URL

https://api.geckoterminal.com/api/v2

Rate Limits

Tier	Rate Limit	Notes
Free	30 calls/minute	No API key required
Paid (CoinGecko)	500 calls/minute	Via CoinGecko subscription

Headers

# Required header for all requests
-H 'accept: application/json'

Response Format

All responses follow JSON:API specification:

{
  "data": {
    "id": "eth_0x...",
    "type": "token",
    "attributes": {
      "name": "Token Name",
      "symbol": "TKN",
      "price_usd": "1.23"
    }
  }
}

---

Endpoints Reference

Networks

List all supported networks:

GET /networks

curl -X GET 'https://api.geckoterminal.com/api/v2/networks?page=1' \
  -H 'accept: application/json'

Response:

{
  "data": [
    {
      "id": "eth",
      "type": "network",
      "attributes": {
        "name": "Ethereum",
        "coingecko_asset_platform_id": "ethereum"
      }
    },
    {
      "id": "solana",
      "type": "network",
      "attributes": {
        "name": "Solana",
        "coingecko_asset_platform_id": "solana"
      }
    }
  ]
}

Common Network IDs:

Network	ID
Ethereum	eth
Solana	solana
Base	base
Arbitrum	arbitrum
Polygon	polygon_pos
BSC	bsc
Avalanche	avax
Optimism	optimism

DEXes

List DEXes on a network:

GET /networks/{network}/dexes

curl -X GET 'https://api.geckoterminal.com/api/v2/networks/eth/dexes' \
  -H 'accept: application/json'

Query Parameters:

Parameter	Description	Default
page	Page number for pagination	1

---

Token Prices (Simple Endpoint)

Get token prices by address:

GET /simple/networks/{network}/token_price/{addresses}

# Single token
curl -X GET 'https://api.geckoterminal.com/api/v2/simple/networks/eth/token_price/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2' \
  -H 'accept: application/json'

# Multiple tokens (comma-separated, max 30)
curl -X GET 'https://api.geckoterminal.com/api/v2/simple/networks/eth/token_price/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' \
  -H 'accept: application/json'

Response:

{
  "data": {
    "id": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "type": "simple_token_price",
    "attributes": {
      "token_prices": {
        "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": "3245.67"
      }
    }
  }
}

---

Token Information

Get detailed token info:

GET /networks/{network}/tokens/{address}

curl -X GET 'https://api.geckoterminal.com/api/v2/networks/eth/tokens/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2' \
  -H 'accept: application/json'

Get multiple tokens:

GET /networks/{network}/tokens/multi/{addresses}

# Up to 30 addresses
curl -X GET 'https://api.geckoterminal.com/api/v2/networks/eth/tokens/multi/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' \
  -H 'accept: application/json'

Get token metadata:

GET /networks/{network}/tokens/{address}/info

Returns token information including name, symbol, image URL, social links, and description.

Get recently updated tokens:

GET /tokens/info_recently_updated

# Get 100 most recently updated tokens with network info
curl -X GET 'https://api.geckoterminal.com/api/v2/tokens/info_recently_updated?include=network' \
  -H 'accept: application/json'

Query Parameters:

Parameter	Description	Values
include	Include related resources	network
network	Filter by specific network	e.g., eth, solana

Response includes image_url and decimal places for each token.

---

Pools

Get pools for a token:

GET /networks/{network}/tokens/{token_address}/pools

curl -X GET 'https://api.geckoterminal.com/api/v2/networks/eth/tokens/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2/pools' \
  -H 'accept: application/json'

Get specific pool:

GET /networks/{network}/pools/{pool_address}

curl -X GET 'https://api.geckoterminal.com/api/v2/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640' \
  -H 'accept: application/json'

Get multiple pools:

GET /networks/{network}/pools/multi/{addresses}

Pool Response Attributes:

{
  "attributes": {
    "name": "WETH / USDC 0.05%",
    "address": "0x88e6...",
    "base_token_price_usd": "3245.67",
    "quote_token_price_usd": "1.00",
    "base_token_price_quote_token": "3245.67",
    "quote_token_price_base_token": "0.000308",
    "base_token_price_native_currency": "1.0",
    "quote_token_price_native_currency": "0.000308",
    "reserve_in_usd": "450000000",
    "fdv_usd": "12000000000",
    "market_cap_usd": "8000000000",
    "pool_created_at": "2023-05-01T12:00:00Z",
    "volume_usd": {
       
       
       
       
    
     
       
       
       
       
    
     
                
                
                
                
    
  

Include Parameters:

When querying pools, use include to get related token/DEX data:

# Include base token, quote token, and DEX info
curl -X GET 'https://api.geckoterminal.com/api/v2/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640?include=base_token,quote_token,dex' \
  -H 'accept: application/json'

Include Value	Returns
base_token	Base token metadata (name, symbol, coingecko_coin_id)
quote_token	Quote token metadata
dex	DEX information

Get pool token info:

GET /networks/{network}/pools/{pool_address}/info

Returns detailed token information for tokens in a specific pool.

---

Trending & New Pools

Trending pools (network-specific):

GET /networks/{network}/trending_pools

curl -X GET 'https://api.geckoterminal.com/api/v2/networks/solana/trending_pools' \
  -H 'accept: application/json'

Trending pools (all networks):

GET /networks/trending_pools

New pools (network-specific):

GET /networks/{network}/new_pools

New pools (all networks):

GET /networks/new_pools

---

Top Pools

Top pools on a network:

GET /networks/{network}/pools

Query Parameters:

Parameter	Description	Values
page	Page number	Integer
sort	Sort order	h24_volume_usd_desc, h24_tx_count_desc
include	Include related data	base_token, quote_token, dex

# Top pools by 24h volume
curl -X GET 'https://api.geckoterminal.com/api/v2/networks/eth/pools?sort=h24_volume_usd_desc&page=1' \
  -H 'accept: application/json'

# Top pools by transaction count
curl -X GET 'https://api.geckoterminal.com/api/v2/networks/solana/pools?order=h24_tx_count_desc&page=1' \
  -H 'accept: application/json'

Top pools on a specific DEX:

GET /networks/{network}/dexes/{dex}/pools

# Top pools on Uniswap V3
curl -X GET 'https://api.geckoterminal.com/api/v2/networks/eth/dexes/uniswap_v3/pools?include=base_token,quote_token' \
  -H 'accept: application/json'

---

OHLCV Data

Get candlestick data:

GET /networks/{network}/pools/{pool_address}/ohlcv/{timeframe}

Timeframe Options:

Timeframe	Aggregate Values	Description
minute	1, 5, 15	1m, 5m, 15m candles
hour	1, 4, 12	1h, 4h, 12h candles
day	1	Daily candles

Query Parameters:

Parameter	Description	Default
aggregate	Candle period	Required
before_timestamp	Unix epoch seconds	Now
limit	Number of candles	100 (max 1000)
currency	Price currency	usd or token
token	Which token price	base or quote (can also pass token address)

Note: The token parameter can now accept a token address directly (as long as it exists in the pool being queried), allowing you to specify exactly which token's price data you want returned.

# 15-minute candles
curl -X GET 'https://api.geckoterminal.com/api/v2/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640/ohlcv/minute?aggregate=15&limit=100' \
  -H 'accept: application/json'

# Daily candles for last 30 days
curl -X GET 'https://api.geckoterminal.com/api/v2/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640/ohlcv/day?aggregate=1&limit=30' \
  -H 'accept: application/json'

Response:

{
  "data": {
    "attributes": {
      "ohlcv_list": [
        [1679414400, 3240.5, 3255.2, 3238.1, 3250.0, 12500000],
        [1679500800, 3250.0, 3262.8, 3245.3, 3258.6, 15200000]
      ]
    }
  },
  "meta": {
    "base": { "address": "0x...", "symbol": "WETH" },
    "quote": {     
  

OHLCV Array Format: [timestamp, open, high, low, close, volume]

---

Trade History

Get recent trades:

GET /networks/{network}/pools/{pool_address}/trades

curl -X GET 'https://api.geckoterminal.com/api/v2/networks/solana/pools/69grLw4PcSypZnn3xpsozCJFT8vs8WA5817VUVnzNGTh/trades' \
  -H 'accept: application/json'

Returns the latest 300 trades in the past 24 hours for the pool.

Query Parameters:

Parameter	Description	Values
trade_volume_in_usd_greater_than	Filter by minimum trade size	Number (e.g., 1000)

# Get trades with minimum $1000 volume
curl -X GET 'https://api.geckoterminal.com/api/v2/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640/trades?trade_volume_in_usd_greater_than=1000' \
  -H 'accept: application/json'

---

Search

Search for pools:

GET /search/pools?query={query}

# Search by token symbol, name, or address
curl -X GET 'https://api.geckoterminal.com/api/v2/search/pools?query=PEPE' \
  -H 'accept: application/json'

# Search within a specific network
curl -X GET 'https://api.geckoterminal.com/api/v2/search/pools?query=PEPE&network=eth' \
  -H 'accept: application/json'

Query Parameters:

Parameter	Description	Values
query	Search term (symbol, name, or address)	String
network	Filter by network	e.g., eth, solana
include	Include related data	base_token, quote_token, dex

Returns top 5 matching pools by default.

---

Complete Endpoint Reference

Category	Endpoint	Method	Description
Networks	/networks	GET	List all supported networks
Networks	/networks/{network}/dexes	GET	List DEXes on a network
Simple	/simple/networks/{network}/token_price/{addresses}	GET	Get token prices (up to 30)
Tokens	/networks/{network}/tokens/{address}	GET	Get specific token info
Tokens	/networks/{network}/tokens/multi/{addresses}	GET	Get multiple tokens (up to 30)
Tokens	/networks/{network}/tokens/{address}/info	GET	Get token metadata
Tokens	/tokens/info_recently_updated	GET	Get 100 recently updated tokens
Pools	/networks/{network}/pools	GET	Top pools on network
Pools	/networks/{network}/pools/{pool_address}	GET	Get specific pool
Pools	/networks/{network}/pools/multi/{addresses}	GET	Get multiple pools (up to 30)
Pools	/networks/{network}/pools/{pool_address}/info	GET	Get pool token info
Pools	/networks/{network}/tokens/{address}/pools	GET	Get pools for a token
Pools	/networks/{network}/dexes/{dex}/pools	GET	Top pools on a DEX
Trending	/networks/{network}/trending_pools

---

Python Client

Installation

pip install geckoterminal-api

Synchronous Usage

from geckoterminal_api import GeckoTerminalAPI

# Initialize client
gt = GeckoTerminalAPI()

# Get all networks
networks = gt.networks()

# Get token price on Ethereum
price = gt.simple_token_price(
    network="eth",
    addresses="0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
)

# Get pools for a token
pools = gt.network_token_pools(
    network="eth",
    token_address="0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
)

# Get trending pools on Solana
trending = gt.network_trending_pools(network="solana")

# Get new pools
new_pools = gt.network_new_pools(network="base")

# Get OHLCV data
ohlcv = gt.network_pool_ohlcv(
    network="eth",
    pool_address="0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
    timeframe="hour",
    aggregate=1,
    limit=100
)

# Get trade history
trades = gt.network_pool_trades(
    network="solana",
    pool="69grLw4PcSypZnn3xpsozCJFT8vs8WA5817VUVnzNGTh"
)

Asynchronous Usage

import asyncio
from geckoterminal_api import AsyncGeckoTerminalAPI

async def main():
    agt = AsyncGeckoTerminalAPI()

    # Get networks
    networks = await agt.networks()

    # Get trending pools
    trending = await agt.network_trending_pools(network="eth")

    return networks, trending

networks, trending = asyncio.run(main())

With Proxy

# Synchronous
gt = GeckoTerminalAPI(proxies={
    'http': 'http://10.10.10.10:8000',
    'https': 'http://10.10.10.10:8000'
})

# Asynchronous
agt = AsyncGeckoTerminalAPI(proxy="http://proxy.com:8000")

---

Node.js Client

Installation

npm install geckoterminal-api

Usage

import { GeckoTerminalAPI } from 'geckoterminal-api';

const gt = new GeckoTerminalAPI();

// Get networks
const networks = await gt.getNetworks();

// Get DEXes on Ethereum
const dexes = await gt.getDexes('eth');

// Get token pools
const pools = await gt.getPoolsByToken('eth', '0xc02aa...');

// Get trending pools
const trending = await gt.getTrendingPoolsByNetwork('solana');

// Get OHLCV data
const ohlcv = await gt.getPoolOhlcv('eth', '0x88e6a...', {
  timeframe: 'hour',
  aggregate: 1,
  limit: 100
});

// Get recent trades
const trades = await gt.getTrades('solana', '69grLw4...');

// Search pools
const results = await gt.searchPools('PEPE');

// Get prices (up to 30 tokens)
 prices =  gt.(, [
  ,
  
]);

---

Common Use Cases

Get Token Price by Address

from geckoterminal_api import GeckoTerminalAPI

gt = GeckoTerminalAPI()

# WETH on Ethereum
weth_price = gt.simple_token_price(
    network="eth",
    addresses="0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
)
print(f"WETH: ${weth_price['data']['attributes']['token_prices']['0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2']}")

Find Best Liquidity Pool

# Get all pools for a token, sorted by volume
pools = gt.network_token_pools(
    network="eth",
    token_address="0x6982508145454ce325ddbe47a25d4ec3d2311933"  # PEPE
)

# First pool has highest liquidity/volume
top_pool = pools['data'][0]
print(f"Best pool: {top_pool['attributes']['name']}")
print(f"24h Volume: ${top_pool['attributes']['volume_usd']['h24']}")
print(f"Liquidity: ${top_pool['attributes']['reserve_in_usd']}")

Build Price Chart

import pandas as pd

# Get 4-hour candles for last 7 days
ohlcv = gt.network_pool_ohlcv(
    network="eth",
    pool_address="0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
    timeframe="hour",
    aggregate=4,
    limit=42  # 7 days * 6 candles/day
)

# Convert to DataFrame
candles = ohlcv['data']['attributes']['ohlcv_list']
df = pd.DataFrame(candles, columns=['timestamp', 'open', 'high', 'low', 'close', 'volume'])
df['timestamp'] = pd.to_datetime(df['timestamp'], unit='s')

Monitor New Token Launches

# Get newly created pools across all networks
new_pools = gt.new_pools()

for pool in new_pools['data'][:10]:
    attrs = pool['attributes']
    print(f"Pool: {attrs['name']}")
    print(f"Network: {pool['relationships']['network']['data']['id']}")
    print(f"Created: {attrs['pool_created_at']}")
    print(f"Volume: ${attrs['volume_usd']['h24']}")
    print("---")

---

Important Notes

Timestamp Format

Always use Unix epoch seconds, not milliseconds:

# Correct
before_timestamp = 1679414400

# Wrong - will cause errors
before_timestamp = 1679414400000

Market Cap vs FDV

• market_cap_usd returns null for unlisted tokens or those without verified supply
• fdv (Fully Diluted Valuation) is always available, calculated from on-chain supply

Pool Ranking

Top 20 pools are ranked by combining:

• reserve_in_usd (liquidity)
• volume_usd (24h trading volume)

Price Reference

price_usd reflects the token's USD value in its first listed top pool.

---

Troubleshooting

Rate Limit Errors

Error: 429 Too Many Requests

Solution: Implement request throttling (max 30/min for free tier):

import time

def rate_limited_request(func, *args, **kwargs):
    result = func(*args, **kwargs)
    time.sleep(2)  # 2 seconds = 30 requests/minute max
    return result

Token Not Found

• Verify the contract address is correct
• Ensure the token has liquidity on a DEX
• Check the network ID matches where the token is deployed

Empty OHLCV Data

• Pool may be too new (no trading history)
• Timestamp may be outside available data range (max 6 months)
• Pool may have very low volume

---

Resources

Official Documentation

• API Guide
• Swagger Docs
• DEX API Overview

Client Libraries

• Python: geckoterminal-api
• Node.js: geckoterminal-api

Related Services

• CoinGecko API - CEX data and /onchain endpoints
• GeckoTerminal Website - Web interface

---

Version History

• 1.1.0 (2026-01-12): Enhanced with complete API reference

  • Added complete endpoint reference table (21 endpoints)
  • Enhanced pool response with all available fields (FDV, market cap, pool_created_at, native currency prices)
  • Added transaction statistics with buyer/seller counts for all time intervals
  • Added /tokens/info_recently_updated endpoint with network filtering
  • Added /networks/{network}/dexes/{dex}/pools endpoint for DEX-specific pools
  • Added /networks/{network}/pools/{pool_address}/info for pool token info
  • Added trade size filtering parameter for trades endpoint
  • Added network parameter for search endpoint
  • Enhanced include parameter documentation for all endpoints
  • Added note about token address support in OHLCV token parameter
  • Updated with API changelog updates through October 2024

• 1.0.0 (2026-01-12): Initial skill release

  • Complete GeckoTerminal API v2 documentation
  • All endpoints (networks, tokens, pools, OHLCV, trades)
  • Python client examples (sync + async)
  • Node.js client examples
  • Rate limiting guidance
  • Common use cases and troubleshooting