🦎 GeckoTerminal API (Unofficial Wrapper)

A lightweight, type-safe TypeScript/JavaScript wrapper for the GeckoTerminal DeFi & DEX aggregator API.

Installation • Quick Start • Documentation • Examples

✨ Features

• 🔒 Type-safe - Full TypeScript support with comprehensive type definitions
• 📦 Lightweight - Zero dependencies except axios
• 🚀 Modern - ESM and CommonJS support
• 🎯 Complete - All GeckoTerminal API endpoints covered
• 💪 Easy to use - Simple and intuitive API
• ⚡ Fast - Optimized for performance

📦 Installation

npm install @exortek/geckoterminal-api

yarn add @exortek/geckoterminal-api

pnpm add @exortek/geckoterminal-api

Requirements

• Node.js >= 20 (per package engines)

Import styles

• ESM (recommended):

  import GeckoTerminal from '@exortek/geckoterminal-api';

• CommonJS:

  // Depending on your bundler/Node CJS interop, one of these will work:
  const GeckoTerminal = require('@exortek/geckoterminal-api');
  // or
  // const GeckoTerminal = require('@exortek/geckoterminal-api').default;

🚀 Quick Start

import GeckoTerminal from '@exortek/geckoterminal-api';

const client = new GeckoTerminal();

// Get trending pools on Ethereum
const trending = await client.pools.getTrendingPools({
  network: 'eth',
  page: 1,
});

console.log(trending.data.data);

📚 Documentation

Initialization

import GeckoTerminal from '@exortek/geckoterminal-api';

// Default configuration
const client = new GeckoTerminal();

// Custom configuration
const client = new GeckoTerminal({
  timeout: 10000,
  headers: {
    'User-Agent': 'MyApp/1.0',
  },
});

Available Endpoints

🌐 Networks

// Get all supported networks
const networks = await client.networks.getNetworks(1);

🏪 DEXes

// Get supported DEXes on a network
const dexes = await client.dexes.getSupportedDeXes('eth', 1);

💰 Pools

// Get specific pool
const pool = await client.pools.getPool({
  network: 'eth',
  address: '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
});

// Get multiple pools
const pools = await client.pools.getMultiplePools({
  network: 'eth',
  addresses: '0xabc...,0xdef...',
});

// Get top pools
const topPools = await client.pools.getTopPools({
  network: 'eth',
  page: 1,
});

// Get new pools
const newPools = await client.pools.getNewPools({
  network: 'eth',
  page: 1,
});

// Get trending pools
const trending = await client.pools.getTrendingPools({
  network: 'eth',
  page: 1,
});

// Search pools
const search = await client.pools.searchPools({
  query: 'USDC',
  network: 'eth',
  page: 1,
});

// Get pools by DEX
const uniswapPools = await client.pools.getDexPools({
  network: 'eth',
  dex: 'uniswap_v3',
  page: 1,
});

// Get pool tokens info
const tokensInfo = await client.pools.getPoolTokensInfo({
  network: 'eth',
  poolAddress: '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
});

🪙 Tokens

// Get token info
const token = await client.tokens.getToken({
  network: 'eth',
  address: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
});

// Get multiple tokens
const tokens = await client.tokens.getMultipleTokens({
  network: 'eth',
  addresses: '0xabc...,0xdef...',
});

// Get token pools
const tokenPools = await client.tokens.getTokenPools({
  network: 'eth',
  tokenAddress: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
  page: 1,
});

// Get token info (detailed)
const info = await client.tokens.getTokenInfo({
  network: 'eth',
  tokenAddress: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
});

// Get recently updated tokens
const recentTokens = await client.tokens.getRecentlyUpdatedTokensInfo();

📊 OHLCV

// Get OHLCV data
const ohlcv = await client.ohlcv.getOhlcv({
  network: 'eth',
  poolAddress: '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
  timeFrame: 'day',
  aggregate: '1',
  limit: 100,
  currency: 'usd',
  token: 'base',
});

Timeframes: minute, hour, day
Aggregates:

• minute: 1, 5, 15
• hour: 1, 4, 12
• day: 1

💱 Trades

// Get recent trades
const trades = await client.trades.getPast24HrTradesByPoolAddress({
  network: 'eth',
  poolAddress: '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
  tradeVolumeInUsdGreaterThan: 1000,
});

💵 Simple Price

// Get token price
const price = await client.simple.getTokenPriceByTokenAddress({
  network: 'eth',
  tokenAddresses: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
  includeMarketCap: true,
  include24hrVol: true,
});

💡 Examples

Get WETH Price

const WETH = '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2';

const price = await client.simple.getTokenPriceByTokenAddress({
  network: 'eth',
  tokenAddresses: WETH,
});

console.log(`WETH Price: $${price.data.data.attributes.token_prices[WETH]}`);

Find Trending Pools

const trending = await client.pools.getTrendingPools({
  network: 'eth',
  page: 1,
});

trending.data.data.forEach((pool) => {
  console.log(`${pool.attributes.name}: $${pool.attributes.reserve_in_usd}`);
});

Search for Pools

const results = await client.pools.searchPools({
  query: 'USDC',
  network: 'eth',
});

results.data.data.forEach((pool) => {
  console.log(pool.attributes.name);
});

Get Historical OHLCV Data

const ohlcv = await client.ohlcv.getOhlcv({
  network: 'eth',
  poolAddress: '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
  timeFrame: 'hour',
  aggregate: '1',
  limit: 24, // Last 24 hours
});

ohlcv.data.data.attributes.ohlcv_list.forEach(([timestamp, open, high, low, close, volume]) => {
  console.log(`Time: ${new Date(timestamp * 1000).toISOString()}`);
  console.log(`OHLC: ${open}, ${high}, ${low}, ${close}`);
  console.log(`Volume: ${volume}`);
});

Get Large Trades

const trades = await client.trades.getPast24HrTradesByPoolAddress({
  network: 'eth',
  poolAddress: '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
  tradeVolumeInUsdGreaterThan: 100000, // Only trades > $100k
});

trades.data.data.forEach((trade) => {
  console.log(`${trade.attributes.kind}: $${trade.attributes.volume_in_usd}`);
  console.log(`TX: ${trade.attributes.tx_hash}`);
});

🔧 Configuration

Custom Axios Config

You can pass custom axios configuration to any method:

const response = await client.networks.getNetworks(1, {
  timeout: 5000,
  headers: {
    'Custom-Header': 'value',
  },
});

Client-wide Configuration

const client = new GeckoTerminal({
  timeout: 15000,
  baseURL: 'https://api.geckoterminal.com/api/v2',
  headers: {
    'User-Agent': 'MyApp/1.0.0',
  },
});

📖 API Reference

Supported Networks

Popular networks include:

• eth - Ethereum
• bsc - BNB Smart Chain
• polygon_pos - Polygon POS
• arbitrum - Arbitrum
• optimism - Optimism
• avax - Avalanche
• base - Base
• And many more...

Rate Limiting

The GeckoTerminal API has rate limits. This wrapper does NOT include any built‑in retry/backoff. If you need retries (e.g., to handle HTTP 429 Too Many Requests), you can add your own Axios interceptors on the client instance.

Good practices:

• Add small delays between requests when making many calls
• Cache responses when possible
• Respect the API's terms of service

Example with a simple delay between calls:

const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

for (const network of networks) {
  const pools = await client.pools.getTopPools({ network, page: 1 });
  await delay(300); // 300ms delay
}

Example Axios interceptor with basic retry on 429 using the standard Retry-After header:

import axios from 'axios';
import GeckoTerminal from '@exortek/geckoterminal-api';

const client = new GeckoTerminal();

client.interceptors.response.use(
  (r) => r,
  async (error) => {
    const cfg: any = error?.config;
    if (error?.response?.status !== 429) return Promise.reject(error);

    cfg.__retry = (cfg.__retry ?? 0) + 1;
    if (cfg.__retry > 3) return Promise.reject(error); // max 3 retries

    // Respect standard Retry-After header when present
    const retryAfter = error.response?.headers?.['retry-after'] as string | undefined;
    let delayMs = 500 + 250 * cfg.__retry; // small backoff

    if (retryAfter) {
      const secs = Number(retryAfter);
      if (Number.isFinite(secs)) {
        delayMs = Math.min(5000, Math.max(250, secs * 1000));
      } else {
        const date = new Date(retryAfter);
        const diff = date.getTime() - Date.now();
        if (Number.isFinite(diff)) {
          delayMs = Math.min(5000, Math.max(250, diff));
        }
      }
    }

    await new Promise((res) => setTimeout(res, delayMs));
    return axios.request(cfg); // re-run the original request using its full config
  },
);

🛠️ TypeScript Support

This package is written in TypeScript and includes full type definitions.

import GeckoTerminal from '@exortek/geckoterminal-api';
import type { PoolsResponse, TokenResponse } from '@exortek/geckoterminal-api';

const client = new GeckoTerminal();

// Full type inference
const pools: PoolsResponse = await client.pools.getTopPools({
  network: 'eth',
  page: 1,
});

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• GeckoTerminal Website
• GeckoTerminal API Documentation
• npm Package
• GitHub Repository

⚠️ Disclaimer

This is an unofficial wrapper for the GeckoTerminal API. Please refer to GeckoTerminal's official documentation and terms of service.

💖 Support

If you find this package helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting new features
• 📖 Improving documentation

Made with ❤️ by ExorTek Documentation generated with ❤️ using Junie.