gecko-terminal-cli

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

Features

• Full API coverage — Networks, DEXes, pools (single, multi, top, by DEX, trending, new, search, megafilter, by category), tokens (single, multi, pools, info, OHLCV, trades, holders, traders), categories, 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 -f and base directory with --output-dir or GECKO_OUTPUT_DIR
• Batch & multi-network — pools-trending, pools-new, and dexes-multi accept multiple networks; price supports --from-file with chunking and rate limiting
• Rate limiting — Client throttles requests to respect the public API (~10 calls/minute)

Install

npm install -g gecko-terminal-cli

Or run without installing:

npx gecko-terminal-cli --help

Binaries: gecko and gecko-terminal.

Quick start

# 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

CLI options (global)

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

Saving output to a file (configurable location)

• File path: use -f or --output-file with either an absolute path or a path relative to the current directory (or --output-dir).
• Base directory: set --output-dir for one run, or GECKO_OUTPUT_DIR in 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

Commands reference

| 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 50 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 | | pools-megafilter | Filter pools across networks (networks, dexes, sort, min/max filters) | | categories | List GeckoTerminal categories | | pools-by-category <categoryId> | Pools for a category | | pools-trending-search | Trending search pools (top 4–10) | | token <network> <address> | Get token by address | | tokens-multi <network> <addr...> | Get multiple tokens (max 50) | | token-pools <network> <tokenAddress> | Top pools for a token | | token-info <network> <address> | Token metadata (name, symbol, socials) | | token-ohlcv <network> <tokenAddress> <timeframe> | Token OHLCV; timeframe: day, hour, minute, second | | token-trades <network> <tokenAddress> | Past 24h trades for token (across pools) | | token-holders <network> <tokenAddress> | Top token holders (optional PnL details) | | token-traders <network> <tokenAddress> | Top token traders with PnL metrics | | token-holders-chart <network> <tokenAddress> | Historical token holders chart | | 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, second | | trades <network> <poolAddress> | Past 24h trades for pool |

Usage examples with sample outputs

Networks (table and CSV)

gecko networks

Sample 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 csv

Sample 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
...

DEXes for a network

gecko dexes eth

Sample output (table):

id                              | name
--------------------------------+----------------------------------
uniswap_v2                      | Uniswap V2
sushiswap                       | SushiSwap
uniswap_v3                      | Uniswap V3
curve                           | Curve
...

Top pools and trending

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.csv

Token price (single or batch)

gecko price eth 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 --market-cap --with-24hr-vol
gecko price eth --from-file tokens.txt -o csv -f out/prices.csv

OHLCV and trades

gecko ohlcv eth 0x60594a405d53811d3bc4766596efd80fd545a270 day --limit 30
gecko trades eth 0x60594a405d53811d3bc4766596efd80fd545a270

Batch and multi-network workflows

All 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 50 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 50 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.csv

Programmatic use

import {
  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));

Data frames and normalizers

All API responses can be normalized to flat rows (array of plain objects). Output helpers:

• toTable(rows) — ASCII table
• toJson(rows, pretty) — JSON array
• toCsv(rows) — CSV with quoted fields
• toDataFrame(rows) — { columns, rows } for programmatic use

Normalizers: normalizeNetworksList, normalizeDexesList, normalizePoolsList, normalizePoolDetail, normalizeMultiPoolDetails, normalizeTokenDetail, normalizeMultiTokenDetail, normalizeSimpleTokenPrice, normalizeOhlcv, normalizeTokenOhlcv, normalizeTrades, normalizeTokenTrades, normalizeTokenHolders, normalizeTokenTraders, normalizeTokenHoldersChart, normalizeTokenInfo, normalizePoolTokensInfo, normalizeTokenInfoRecentlyUpdated, normalizeCategories.

Environment

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

Note: For Starknet, API address fields use padded format (66 chars, 0x0...). If you compare or store addresses, normalize to a consistent format.

Rate limit

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.

License

MIT