CLI and Node.js client for the GeckoTerminal DEX API v2. Fetch networks, DEXes, pools, tokens, OHLCV, and trades with data frame–style output: ASCII table, JSON, or CSV. Use from the shell or import in TypeScript/JavaScript.
- npm: gecko-terminal-cli
- GitHub: fintechtonic/gecko-terminal-cli
- Full API coverage — Networks, DEXes, pools (single, multi, top, by DEX, trending, new, search), tokens (single, multi, pools, info), simple token prices, OHLCV, trades
- Usable data frames — All responses normalized to flat rows; output as table, JSON, or CSV
- Configurable file output — Save any command output to a file; set path with
-fand base directory with--output-dirorGECKO_OUTPUT_DIR - Batch & multi-network —
pools-trending,pools-new, anddexes-multiaccept multiple networks;pricesupports--from-filewith chunking and rate limiting - Rate limiting — Client throttles requests to respect the public API (~10 calls/minute)
npm install -g gecko-terminal-cliOr run without installing:
npx gecko-terminal-cli --helpBinaries: gecko and gecko-terminal.
# List supported networks (table)
gecko networks
# List DEXes on Ethereum
gecko dexes eth
# Top pools on Ethereum by 24h volume
gecko pools-top eth --sort h24_volume_usd_desc
# Token price (e.g. WETH)
gecko price eth 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2| Option | Description |
|---|---|
-o, --output <format> |
Output format: table (default when TTY), json, or csv |
--pretty |
Pretty-print JSON |
--raw |
Print raw API response as JSON (ignores normalizers) |
-f, --output-file <path> |
Write output to this file (creates parent dirs if needed) |
--output-dir <dir> |
Base directory for the output file when using -f with a relative path. If omitted, uses env GECKO_OUTPUT_DIR or current directory |
- File path: use
-for--output-filewith either an absolute path or a path relative to the current directory (or--output-dir). - Base directory: set
--output-dirfor one run, orGECKO_OUTPUT_DIRin the environment for a default.
Examples:
# Save to ./out/networks.csv
gecko networks -o csv -f out/networks.csv
# Save to a specific directory
gecko pools-top eth -o json --output-dir ./data -f pools-eth.json
# Use environment for default output directory (e.g. Windows)
set GECKO_OUTPUT_DIR=C:\exports
gecko price eth 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -f weth-price.json| Command | Description |
|---|---|
networks |
List supported networks |
dexes <network> |
List DEXes for a network |
dexes-multi <networks...> |
DEXes for multiple networks (merged, with network column; rate-limited) |
pool <network> <address> |
Get pool by address |
pools-multi <network> <addr...> |
Get multiple pools (max 30 addresses) |
pools-top <network> |
Top pools by network |
pools-by-dex <network> <dex> |
Top pools by DEX |
pools-trending [networks...] |
Trending pools; no args = all networks; with args = those networks merged |
pools-new [networks...] |
New pools; same multi-network behavior as trending |
pools-search <query> |
Search pools |
token <network> <address> |
Get token by address |
tokens-multi <network> <addr...> |
Get multiple tokens (max 30) |
token-pools <network> <tokenAddress> |
Top pools for a token |
token-info <network> <address> |
Token metadata (name, symbol, socials) |
pool-info <network> <poolAddress> |
Pool tokens info (base/quote metadata) |
tokens-recent [network] |
Recently updated token info |
price <network> [addr...] |
Token price(s); --from-file <path> for batch (chunked, rate-limited) |
ohlcv <network> <poolAddress> <timeframe> |
Pool OHLCV; timeframe: day, hour, minute |
trades <network> <poolAddress> |
Past 24h trades for pool |
gecko networksSample output (table):
id | name | coingecko_asset_platform_id
----------------------+-------------------------+----------------------------
eth | Ethereum | ethereum
bsc | BNB Chain | binance-smart-chain
polygon_pos | Polygon POS | polygon-pos
base | Base | base
...
gecko networks -o csvSample output (CSV):
id,name,coingecko_asset_platform_id
eth,Ethereum,ethereum
bsc,BNB Chain,binance-smart-chain
polygon_pos,Polygon POS,polygon-pos
base,Base,base
...
gecko dexes ethSample output (table):
id | name
--------------------------------+----------------------------------
uniswap_v2 | Uniswap V2
sushiswap | SushiSwap
uniswap_v3 | Uniswap V3
curve | Curve
...
gecko pools-top eth --sort h24_volume_usd_desc
gecko pools-trending eth --duration 24h
gecko pools-trending eth bsc base -o csv -f out/trending.csvgecko price eth 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 --market-cap --with-24hr-vol
gecko price eth --from-file tokens.txt -o csv -f out/prices.csvgecko ohlcv eth 0x60594a405d53811d3bc4766596efd80fd545a270 day --limit 30
gecko trades eth 0x60594a405d53811d3bc4766596efd80fd545a270All batch and multi-network operations are built into the CLI (no external scripts).
Rate limit: The API allows ~10 calls per minute. Commands that make multiple calls (multi-network or batch price) automatically wait 6.5 seconds between calls.
Multi-network commands:
| Use case | Example |
|---|---|
| Trending pools (single network) | gecko pools-trending eth -o csv -f out/trending-eth.csv |
Trending pools (multiple networks, merged with network column) |
gecko pools-trending eth bsc base polygon_pos arbitrum -o csv -f out/trending-multi.csv |
| New pools (multiple networks) | gecko pools-new eth base -o csv -f out/new-pools.csv |
| DEXes (single network) | gecko dexes eth -o csv -f out/dexes-eth.csv |
DEXes (multiple networks, merged with network column) |
gecko dexes-multi eth bsc base -o csv -f out/dexes-multi.csv |
Batch token prices:
- From command line (up to 30 per call; more are auto-chunked):
gecko price eth <addr1> <addr2> ... -o csv -f out/prices.csv - From file (any number of addresses; auto-chunked and rate-limited):
Put one token address per line in a file, then:
gecko price eth --from-file tokens.txt -o csv -f out/prices.csv
Addresses are sent in chunks of 30 with a delay between chunks; output is one merged table/CSV/JSON.
Output location: -f, --output-file <path> writes to the given file (creates parent dirs); --output-dir <dir> sets the base directory; GECKO_OUTPUT_DIR is the env default.
One-liners:
gecko networks -o csv -f out/networks.csv
gecko dexes-multi eth base -o csv -f out/dexes.csv
gecko pools-trending eth bsc base polygon_pos arbitrum -o json -f out/trending.json
gecko price eth --from-file my-tokens.txt -o csv -f out/prices.csvimport {
createClient,
getNetworks,
getTopPoolsByNetwork,
normalizeNetworksList,
normalizePoolsList,
toCsv,
toTable,
toDataFrame,
} from "gecko-terminal-cli";
const client = createClient();
// Networks as CSV
const networksRes = await getNetworks(client, { page: 1 });
const networkRows = normalizeNetworksList(networksRes);
console.log(toCsv(networkRows));
// Top pools on Ethereum as data frame
const poolsRes = await getTopPoolsByNetwork(client, "eth", { page: 1 });
const poolRows = normalizePoolsList(poolsRes);
const df = toDataFrame(poolRows);
console.log(df.columns);
console.log(toTable(poolRows));All API responses can be normalized to flat rows (array of plain objects). Output helpers:
toTable(rows)— ASCII tabletoJson(rows, pretty)— JSON arraytoCsv(rows)— CSV with quoted fieldstoDataFrame(rows)—{ columns, rows }for programmatic use
Normalizers: normalizeNetworksList, normalizeDexesList, normalizePoolsList, normalizePoolDetail, normalizeMultiPoolDetails, normalizeTokenDetail, normalizeMultiTokenDetail, normalizeSimpleTokenPrice, normalizeOhlcv, normalizeTrades, normalizeTokenInfo, normalizePoolTokensInfo, normalizeTokenInfoRecentlyUpdated.
| Variable | Description |
|---|---|
GECKO_API_BASE_URL |
Override API base URL (default: https://api.geckoterminal.com/api/v2) |
GECKO_OUTPUT_DIR |
Default directory for -f when --output-dir is not set |
The public API allows about 10 requests per minute. The client throttles automatically; multi-network and batch price commands add a ~6.5s delay between API calls.
MIT