GeckoTerminal API Skill

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

---

API Basics

Base URL

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

Rate Limits

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:

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:

---

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:

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": {
      "h24": "125000000",
      "h6": "32000000",
      "h1": "5400000",
      "m5": "450000"
    },
    "price_change_percentage": {
      "h24": "2.5",
      "h6": "0.8",
      "h1": "0.2",
      "m5": "0.05"
    },
    "transactions": {
      "h24": { "buys": 1250, "sells": 980, "buyers": 890, "sellers": 720 },
      "h6": { "buys": 320, "sells": 280, "buyers": 210, "sellers": 180 },
      "h1": { "buys": 52, "sells": 41, "buyers": 38, "sellers": 29 },
      "m5": { "buys": 5, "sells": 3, "buyers": 4, "sellers": 2 }
    }
  }
}

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'

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:

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

Query Parameters:

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": { "address": "0x...", "symbol": "USDC" }
  }
}

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:

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

Returns top 5 matching pools by default.

---

Complete Endpoint Reference

---

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)
const prices = await gt.getPrices('eth', [
  '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
  '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
]);

---

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