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": {
      "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'

| 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": { "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: | 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 | GET | Trending pools on network | | Trending | /networks/trending_pools | GET | Trending pools (all networks) | | New | /networks/{network}/new_pools | GET | New pools on network | | New | /networks/new_pools | GET | New pools (all networks) | | OHLCV | /networks/{network}/pools/{pool}/ohlcv/{timeframe} | GET | Candlestick data | | Trades | /networks/{network}/pools/{pool}/trades | GET | Recent trades (up to 300) | | Search | /search/pools | GET | Search pools by query |

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

Client Libraries

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