geckoterminal-api

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

enuno 12 3 Updated 4mo ago

GitHub

Install

npx skillscat add enuno/claude-command-and-control/geckoterminal-api

Install via the SkillsCat registry.

SKILL.md

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

geckoterminal-api

Install

GeckoTerminal API Skill

When to Use This Skill

When NOT to Use This Skill

Core Concepts

Architecture Overview

Key Differences from CoinGecko

API Basics

Base URL

Rate Limits

Headers

Response Format

Endpoints Reference

Networks

DEXes

Token Prices (Simple Endpoint)

Token Information

Pools

Trending & New Pools

Top Pools

OHLCV Data

Trade History

Search

Complete Endpoint Reference

Python Client

Installation

Synchronous Usage

Asynchronous Usage

With Proxy

Node.js Client

Installation

Usage

Common Use Cases

Get Token Price by Address

Find Best Liquidity Pool

Build Price Chart

Monitor New Token Launches

Important Notes

Timestamp Format

Market Cap vs FDV

Pool Ranking

Price Reference

Troubleshooting

Rate Limit Errors

Token Not Found

Empty OHLCV Data

Resources

Official Documentation

Client Libraries

Related Services

Version History

Categories

Install

Recommended Skills