coingecko-pro 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,4308 @@
+/**
+ * @module client
+ * Main HTTP client for the CoinGecko REST API.
+ *
+ * Features:
+ * - Automatic base URL selection (Pro vs Free tier)
+ * - In-memory TTL cache
+ * - Token-bucket rate limiting
+ * - Exponential-backoff retry on 429 / 503
+ * - AbortController request timeout
+ * - Lifecycle hooks (onRequest, onResponse, onError)
+ */
+/**
+ * Configuration options accepted by {@link CoinGeckoClient}.
+ */
+interface CoinGeckoClientConfig {
+    /**
+     * CoinGecko Pro API key.
+     * When present the client targets `pro-api.coingecko.com` and adds the
+     * `x-cg-pro-api-key` header.
+     */
+    apiKey?: string;
+    /**
+     * Override the base URL entirely (useful for testing or proxies).
+     * When omitted the base URL is derived from `apiKey`.
+     */
+    baseUrl?: string;
+    /**
+     * Default response cache TTL in milliseconds.
+     * @default 30_000
+     */
+    cacheTtl?: number;
+    /**
+     * Maximum number of retry attempts for transient errors (429, 503).
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Base delay in milliseconds for the first retry. Subsequent retries use
+     * exponential backoff: `retryDelay * 2^attempt`.
+     * @default 1000
+     */
+    retryDelay?: number;
+    /**
+     * Maximum requests per minute enforced by the built-in rate limiter.
+     * Defaults to `500` when an `apiKey` is present (Pro tier), otherwise `30`.
+     */
+    rateLimit?: number;
+    /**
+     * Request timeout in milliseconds. Requests that exceed this duration are
+     * aborted and throw a {@link CoinGeckoError} with `status: 0`.
+     * @default 15_000
+     */
+    timeout?: number;
+    /**
+     * Called immediately before every outgoing request with the resolved URL.
+     */
+    onRequest?: (url: string) => void;
+    /**
+     * Called after every completed request with the URL, HTTP status, and
+     * elapsed time in milliseconds.
+     */
+    onResponse?: (url: string, status: number, ms: number) => void;
+    /**
+     * Called whenever a request fails (after all retries are exhausted).
+     */
+    onError?: (url: string, error: Error) => void;
+}
+/**
+ * HTTP client for the CoinGecko REST API.
+ *
+ * Instantiate once and reuse across your application.  The client is
+ * safe to call concurrently; each call is independently rate-limited and
+ * cached.
+ *
+ * @example
+ * ```ts
+ * // Pro tier
+ * const client = new CoinGeckoClient({ apiKey: process.env.CG_KEY });
+ * const data = await client.get('/coins/markets', { vs_currency: 'usd' });
+ *
+ * // Free tier
+ * const client = new CoinGeckoClient();
+ * ```
+ */
+declare class CoinGeckoClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly cacheTtl;
+    private readonly maxRetries;
+    private readonly retryDelay;
+    private readonly timeout;
+    private readonly onRequest;
+    private readonly onResponse;
+    private readonly onError;
+    private readonly cache;
+    private readonly rateLimiter;
+    /**
+     * @param config - Optional configuration. See {@link CoinGeckoClientConfig}.
+     */
+    constructor(config?: CoinGeckoClientConfig);
+    /**
+     * Performs a GET request to the given API path.
+     *
+     * Results are cached by default. Pass `options.cacheTtl = 0` to bypass
+     * caching for a specific call.
+     *
+     * @template T      - Expected shape of the response body.
+     * @param path      - API endpoint path, e.g. `/coins/markets`.
+     * @param params    - Query parameters. `undefined`/`null` values are omitted.
+     * @param options   - Per-call overrides.
+     * @returns Parsed JSON response body cast to `T`.
+     * @throws {@link CoinGeckoError} on non-2xx responses or network failures.
+     */
+    get<T>(path: string, params?: Record<string, unknown>, options?: {
+        cacheTtl?: number;
+    }): Promise<T>;
+    /**
+     * Performs a single fetch with an AbortController timeout, then handles
+     * caching and lifecycle hooks.
+     */
+    private fetchWithTimeout;
+}
+
+/**
+ * Common/shared types used across multiple CoinGecko API endpoints.
+ */
+/**
+ * Standard pagination query parameters used across list endpoints.
+ *
+ * @example
+ * const params: PaginationParams = { per_page: 50, page: 2 };
+ */
+interface PaginationParams {
+    /** Total results per page. Valid values: 1–250. Default: 100. */
+    per_page?: number;
+    /** Page number to retrieve. Default: 1. */
+    page?: number;
+}
+/**
+ * Standard coin/NFT image URLs provided in three sizes.
+ *
+ * @example
+ * const img: ImageUrls = {
+ *   thumb: "https://assets.coingecko.com/.../thumb/bitcoin.png",
+ *   small: "https://assets.coingecko.com/.../small/bitcoin.png",
+ *   large: "https://assets.coingecko.com/.../large/bitcoin.png",
+ * };
+ */
+interface ImageUrls {
+    /** Thumbnail-size image URL. */
+    thumb?: string;
+    /** Small-size image URL. */
+    small?: string;
+    /** Large-size image URL. */
+    large?: string;
+}
+/**
+ * A single historical market data point returned by chart endpoints.
+ * The tuple format is `[unix_timestamp_ms, value]`.
+ *
+ * @example
+ * const point: MarketDataPoint = [1712534400000, 69840];
+ */
+type MarketDataPoint = [number, number];
+/**
+ * Supported vs-currency codes for CoinGecko price queries.
+ * Includes fiat currencies, major crypto assets, and commodity metals.
+ *
+ * @remarks
+ * Full list available via `/simple/supported_vs_currencies`.
+ */
+type VsCurrency = 'btc' | 'eth' | 'ltc' | 'bch' | 'bnb' | 'eos' | 'xrp' | 'xlm' | 'link' | 'dot' | 'yfi' | 'sol' | 'usd' | 'aed' | 'ars' | 'aud' | 'bdt' | 'bhd' | 'bmd' | 'brl' | 'cad' | 'chf' | 'clp' | 'cny' | 'czk' | 'dkk' | 'eur' | 'gbp' | 'gel' | 'hkd' | 'huf' | 'idr' | 'ils' | 'inr' | 'jpy' | 'krw' | 'kwd' | 'lkr' | 'mmk' | 'mxn' | 'myr' | 'ngn' | 'nok' | 'nzd' | 'php' | 'pkr' | 'pln' | 'rub' | 'sar' | 'sek' | 'sgd' | 'thb' | 'try' | 'twd' | 'uah' | 'vef' | 'vnd' | 'zar' | 'xdr' | 'xag' | 'xau' | 'bits' | 'sats' | string;
+/**
+ * Sort order options for coins markets endpoint.
+ */
+type CoinsMarketOrder = 'market_cap_asc' | 'market_cap_desc' | 'volume_asc' | 'volume_desc' | 'id_asc' | 'id_desc';
+/**
+ * Sort order options for exchange tickers endpoint.
+ */
+type TickerOrder = 'trust_score_desc' | 'trust_score_asc' | 'volume_desc' | 'volume_asc';
+/**
+ * Sort order options for exchange tickers by exchange ID.
+ */
+type ExchangeTickerOrder = 'market_cap_asc' | 'market_cap_desc' | 'trust_score_desc' | 'trust_score_asc' | 'volume_desc' | 'volume_asc' | 'base_target';
+/**
+ * Locale codes supported by the `/coins/markets` endpoint.
+ */
+type Locale = 'ar' | 'bg' | 'cs' | 'da' | 'de' | 'el' | 'en' | 'es' | 'fi' | 'fr' | 'he' | 'hi' | 'hr' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lt' | 'nl' | 'no' | 'pl' | 'pt' | 'ro' | 'ru' | 'sk' | 'sl' | 'sv' | 'th' | 'tr' | 'uk' | 'vi' | 'zh' | 'zh-tw';
+/**
+ * A generic dictionary mapping currency codes to numeric values.
+ * Used for multi-currency price, ATH, ATL, and volume maps.
+ *
+ * @example
+ * const prices: CurrencyMap = { usd: 69840, eur: 64375, btc: 1 };
+ */
+type CurrencyMap = Record<string, number | null>;
+/**
+ * A generic dictionary mapping currency codes to ISO date-time strings.
+ * Used for ATH/ATL date maps.
+ */
+type CurrencyDateMap = Record<string, string | null>;
+/**
+ * A simple ID + name pair used in list (ID map) endpoints.
+ */
+interface IdNamePair {
+    /** Unique identifier. */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+}
+/**
+ * Return on investment data attached to certain coin responses.
+ */
+interface RoiData {
+    /** ROI multiplier (e.g. 2 = 2x return). */
+    times?: number | null;
+    /** Currency in which ROI is measured. */
+    currency?: string | null;
+    /** ROI as a percentage. */
+    percentage?: number | null;
+}
+
+/**
+ * Type definitions for all CoinGecko coin-related endpoints.
+ *
+ * Covers: /simple/price, /simple/token_price, /coins/list, /coins/markets,
+ * /coins/{id}, /coins/{id}/tickers, /coins/{id}/history,
+ * /coins/{id}/market_chart, /coins/{id}/market_chart/range,
+ * /coins/{id}/ohlc, /coins/{id}/ohlc/range (Analyst+),
+ * /coins/{id}/circulating_supply_chart (Enterprise),
+ * /coins/{id}/total_supply_chart (Enterprise),
+ * /coins/top_gainers_losers (Analyst+), /coins/list/new (Analyst+),
+ * /coins/categories/list, /coins/categories,
+ * /coins/{platform}/contract/{address} and related chart endpoints.
+ */
+
+/**
+ * Query parameters for `/simple/price`.
+ * Returns spot prices for one or more coins.
+ *
+ * @example
+ * const params: SimplePriceParams = {
+ *   ids: 'bitcoin,ethereum',
+ *   vs_currencies: 'usd,eur',
+ *   include_market_cap: true,
+ * };
+ */
+interface SimplePriceParams {
+    /**
+     * Comma-separated coin IDs.
+     * Refers to `/coins/list` for valid IDs.
+     */
+    ids: string;
+    /** Comma-separated target currencies. */
+    vs_currencies: string;
+    /** Include market cap data. Default: false. */
+    include_market_cap?: boolean;
+    /** Include 24h volume data. Default: false. */
+    include_24hr_vol?: boolean;
+    /** Include 24h price change data. Default: false. */
+    include_24hr_change?: boolean;
+    /** Include last-updated timestamp. Default: false. */
+    include_last_updated_at?: boolean;
+    /** Decimal precision for price values. */
+    precision?: string;
+}
+/**
+ * Response from `/simple/price`.
+ * A map of coin ID → currency → price (and optional extras).
+ *
+ * @example
+ * const result: SimplePriceResponse = {
+ *   bitcoin: { usd: 69840, usd_market_cap: 1381651251183 },
+ * };
+ */
+type SimplePriceResponse = Record<string, Record<string, number | null>>;
+/**
+ * Query parameters for `/simple/token_price/{id}`.
+ *
+ * @remarks Requires Analyst+ plan for more than 1 address per request.
+ */
+interface SimpleTokenPriceParams {
+    /** Comma-separated token contract addresses. */
+    contract_addresses: string;
+    /** Comma-separated target currencies. */
+    vs_currencies: string;
+    /** Include market cap data. Default: false. */
+    include_market_cap?: boolean;
+    /** Include 24h volume data. Default: false. */
+    include_24hr_vol?: boolean;
+    /** Include 24h price change data. Default: false. */
+    include_24hr_change?: boolean;
+    /** Include last-updated timestamp. Default: false. */
+    include_last_updated_at?: boolean;
+    /** Decimal precision for price values. */
+    precision?: string;
+}
+/**
+ * Query parameters for `/coins/list`.
+ */
+interface CoinsListParams {
+    /** Include contract address for each coin per platform. Default: false. */
+    include_platform?: boolean;
+    /** Filter list to only active coins. Default: false. */
+    status?: 'active' | 'inactive';
+}
+/**
+ * A minimal coin entry from `/coins/list`.
+ */
+interface CoinListEntry {
+    /** Unique coin API ID. */
+    id: string;
+    /** Coin ticker symbol (e.g. "btc"). */
+    symbol: string;
+    /** Human-readable coin name. */
+    name: string;
+    /** Map of platform → contract address when `include_platform=true`. */
+    platforms?: Record<string, string>;
+}
+/**
+ * Query parameters for `/coins/top_gainers_losers`.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface TopGainersLosersParams {
+    /** Target vs-currency for price change. */
+    vs_currency: VsCurrency;
+    /** Time duration filter. */
+    duration?: '1h' | '24h' | '7d' | '14d' | '30d' | '60d' | '1y';
+    /** Filter by top N coins by market cap. */
+    top_coins?: '300' | '500' | '1000' | 'all';
+}
+/**
+ * A single coin entry in the top gainers or losers list.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface TopMoverCoin {
+    /** Coin API ID. */
+    id: string;
+    /** Coin symbol. */
+    symbol: string;
+    /** Coin name. */
+    name: string;
+    /** Coin image URL. */
+    image: string;
+    /** Current market cap rank. */
+    market_cap_rank?: number | null;
+    /** USD price. */
+    usd?: number | null;
+    /** 24h volume in USD. */
+    usd_24h_vol?: number | null;
+    /** Price change percentage over the requested duration. */
+    usd_1h_change?: number | null;
+}
+/**
+ * Response from `/coins/top_gainers_losers`.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface TopMoversResponse {
+    /** Top 30 coins with the largest price gain. */
+    top_gainers: TopMoverCoin[];
+    /** Top 30 coins with the largest price loss. */
+    top_losers: TopMoverCoin[];
+}
+/**
+ * A coin entry from `/coins/list/new`.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface NewCoin {
+    /** Coin API ID. */
+    id: string;
+    /** Coin symbol. */
+    symbol: string;
+    /** Coin name. */
+    name: string;
+    /** Date the coin was activated on CoinGecko. */
+    activated_at?: number | null;
+}
+/**
+ * Query parameters for `/coins/markets`.
+ */
+interface CoinsMarketsParams extends PaginationParams {
+    /** Target vs-currency for all market data. */
+    vs_currency: VsCurrency;
+    /** Comma-separated coin IDs to filter results. */
+    ids?: string;
+    /** Comma-separated coin names to filter results. */
+    names?: string;
+    /** Comma-separated coin symbols to filter results. */
+    symbols?: string;
+    /**
+     * When using `symbols` lookup, `top` returns top-ranked tokens,
+     * `all` returns all matching tokens (max 50 symbols per request).
+     */
+    include_tokens?: 'top' | 'all';
+    /** Filter by coin category. Refers to `/coins/categories/list`. */
+    category?: string;
+    /** Sort order. Default: market_cap_desc. */
+    order?: CoinsMarketOrder;
+    /** Include sparkline 7-day data. Default: false. */
+    sparkline?: boolean;
+    /** Comma-separated price change percentage timeframes (1h,24h,7d,…). */
+    price_change_percentage?: string;
+    /** Response language. Default: en. */
+    locale?: Locale;
+    /** Decimal precision for currency values. */
+    precision?: string;
+    /** Include rehypothecated tokens. Default: false. */
+    include_rehypothecated?: boolean;
+}
+/**
+ * A single coin entry from `/coins/markets`.
+ *
+ * @example
+ * const coin: MarketCoin = {
+ *   id: 'bitcoin',
+ *   symbol: 'btc',
+ *   name: 'Bitcoin',
+ *   current_price: 69840,
+ *   market_cap: 1381651251183,
+ *   market_cap_rank: 1,
+ * };
+ */
+interface MarketCoin {
+    /** Coin API ID. */
+    id: string;
+    /** Coin ticker symbol. */
+    symbol: string;
+    /** Coin name. */
+    name: string;
+    /** Coin image URL. */
+    image?: string | null;
+    /** Current price in the requested vs-currency. */
+    current_price?: number | null;
+    /** Market capitalisation in the requested vs-currency. */
+    market_cap?: number | null;
+    /** Rank by market cap. */
+    market_cap_rank?: number | null;
+    /** Market cap rank including rehypothecated tokens. */
+    market_cap_rank_with_rehypothecated?: number | null;
+    /** Fully diluted valuation in the requested vs-currency. */
+    fully_diluted_valuation?: number | null;
+    /** 24h trading volume in the requested vs-currency. */
+    total_volume?: number | null;
+    /** 24h high price. */
+    high_24h?: number | null;
+    /** 24h low price. */
+    low_24h?: number | null;
+    /** Absolute price change over the last 24h. */
+    price_change_24h?: number | null;
+    /** Percentage price change over the last 24h. */
+    price_change_percentage_24h?: number | null;
+    /** Absolute market cap change over the last 24h. */
+    market_cap_change_24h?: number | null;
+    /** Percentage market cap change over the last 24h. */
+    market_cap_change_percentage_24h?: number | null;
+    /** Circulating supply. */
+    circulating_supply?: number | null;
+    /** Total supply. */
+    total_supply?: number | null;
+    /** Maximum possible supply. */
+    max_supply?: number | null;
+    /** All-time high price. */
+    ath?: number | null;
+    /** ATH change percentage from current price. */
+    ath_change_percentage?: number | null;
+    /** Date of all-time high (ISO 8601). */
+    ath_date?: string | null;
+    /** All-time low price. */
+    atl?: number | null;
+    /** ATL change percentage from current price. */
+    atl_change_percentage?: number | null;
+    /** Date of all-time low (ISO 8601). */
+    atl_date?: string | null;
+    /** Return on investment data (if available). */
+    roi?: RoiData | null;
+    /** ISO timestamp of last price update. */
+    last_updated?: string | null;
+    /** Sparkline price data for the last 7 days (when requested). */
+    sparkline_in_7d?: {
+        price: number[];
+    } | null;
+    /** Price change percentage over 1h (when requested). */
+    price_change_percentage_1h_in_currency?: number | null;
+    /** Price change percentage over 24h (when requested). */
+    price_change_percentage_24h_in_currency?: number | null;
+    /** Price change percentage over 7d (when requested). */
+    price_change_percentage_7d_in_currency?: number | null;
+    /** Price change percentage over 14d (when requested). */
+    price_change_percentage_14d_in_currency?: number | null;
+    /** Price change percentage over 30d (when requested). */
+    price_change_percentage_30d_in_currency?: number | null;
+    /** Price change percentage over 200d (when requested). */
+    price_change_percentage_200d_in_currency?: number | null;
+    /** Price change percentage over 1y (when requested). */
+    price_change_percentage_1y_in_currency?: number | null;
+}
+/**
+ * Links object within a CoinDetail response.
+ */
+interface CoinLinks {
+    homepage?: string[] | null;
+    whitepaper?: string | null;
+    blockchain_site?: string[] | null;
+    official_forum_url?: string[] | null;
+    chat_url?: string[] | null;
+    announcement_url?: string[] | null;
+    snapshot_url?: string | null;
+    twitter_screen_name?: string | null;
+    facebook_username?: string | null;
+    bitcointalk_thread_identifier?: number | null;
+    telegram_channel_identifier?: string | null;
+    subreddit_url?: string | null;
+    repos_url?: {
+        github?: string[] | null;
+        bitbucket?: string[] | null;
+    } | null;
+}
+/**
+ * Platform detail entry (decimal places and contract address).
+ */
+interface PlatformDetail {
+    decimal_place?: number | null;
+    contract_address?: string | null;
+}
+/**
+ * Category detail with ID and name.
+ */
+interface CategoryDetail {
+    id: string;
+    name: string;
+}
+/**
+ * Comprehensive market data block inside a CoinDetail response.
+ */
+interface CoinMarketData {
+    current_price?: CurrencyMap | null;
+    total_value_locked?: number | null;
+    mcap_to_tvl_ratio?: number | null;
+    fdv_to_tvl_ratio?: number | null;
+    roi?: RoiData | null;
+    ath?: CurrencyMap | null;
+    ath_change_percentage?: CurrencyMap | null;
+    ath_date?: Record<string, string | null> | null;
+    atl?: CurrencyMap | null;
+    atl_change_percentage?: CurrencyMap | null;
+    atl_date?: Record<string, string | null> | null;
+    market_cap?: CurrencyMap | null;
+    market_cap_rank?: number | null;
+    market_cap_fdv_ratio?: number | null;
+    fully_diluted_valuation?: CurrencyMap | null;
+    market_cap_change_24h?: number | null;
+    market_cap_change_percentage_24h?: number | null;
+    market_cap_change_percentage_24h_in_currency?: CurrencyMap | null;
+    total_supply?: number | null;
+    max_supply?: number | null;
+    circulating_supply?: number | null;
+    total_volume?: CurrencyMap | null;
+    high_24h?: CurrencyMap | null;
+    low_24h?: CurrencyMap | null;
+    price_change_24h?: number | null;
+    price_change_percentage_24h?: number | null;
+    price_change_percentage_7d?: number | null;
+    price_change_percentage_14d?: number | null;
+    price_change_percentage_30d?: number | null;
+    price_change_percentage_60d?: number | null;
+    price_change_percentage_200d?: number | null;
+    price_change_percentage_1y?: number | null;
+    price_change_24h_in_currency?: CurrencyMap | null;
+    price_change_percentage_1h_in_currency?: CurrencyMap | null;
+    price_change_percentage_24h_in_currency?: CurrencyMap | null;
+    price_change_percentage_7d_in_currency?: CurrencyMap | null;
+    price_change_percentage_14d_in_currency?: CurrencyMap | null;
+    price_change_percentage_30d_in_currency?: CurrencyMap | null;
+    price_change_percentage_60d_in_currency?: CurrencyMap | null;
+    price_change_percentage_200d_in_currency?: CurrencyMap | null;
+    price_change_percentage_1y_in_currency?: CurrencyMap | null;
+    last_updated?: string | null;
+    sparkline_7d?: {
+        price: number[];
+    } | null;
+}
+/**
+ * Community data block inside a CoinDetail response.
+ */
+interface CoinCommunityData {
+    facebook_likes?: number | null;
+    twitter_followers?: number | null;
+    reddit_average_posts_48h?: number | null;
+    reddit_average_comments_48h?: number | null;
+    reddit_subscribers?: number | null;
+    reddit_accounts_active_48h?: number | null;
+    telegram_channel_user_count?: number | null;
+}
+/**
+ * Developer data block inside a CoinDetail response.
+ */
+interface CoinDeveloperData {
+    forks?: number | null;
+    stars?: number | null;
+    subscribers?: number | null;
+    total_issues?: number | null;
+    closed_issues?: number | null;
+    pull_requests_merged?: number | null;
+    pull_request_contributors?: number | null;
+    code_additions_deletions_4_weeks?: {
+        additions: number | null;
+        deletions: number | null;
+    } | null;
+    commit_count_4_weeks?: number | null;
+    last_4_weeks_commit_activity_series?: number[] | null;
+}
+/**
+ * Full coin detail response from `/coins/{id}`.
+ *
+ * @example
+ * const coin: CoinDetail = {
+ *   id: 'bitcoin',
+ *   symbol: 'btc',
+ *   name: 'Bitcoin',
+ *   market_cap_rank: 1,
+ * };
+ */
+interface CoinDetail {
+    /** Coin API ID. */
+    id: string;
+    /** Coin ticker symbol. */
+    symbol: string;
+    /** Coin name. */
+    name: string;
+    /** CoinGecko web slug. */
+    web_slug?: string | null;
+    /** Asset platform ID (null for native chains). */
+    asset_platform_id?: string | null;
+    /** Map of platform → contract address. */
+    platforms?: Record<string, string> | null;
+    /** Detailed platform info including decimal places. */
+    detail_platforms?: Record<string, PlatformDetail> | null;
+    /** Average block time in minutes. */
+    block_time_in_minutes?: number | null;
+    /** Hashing algorithm name (e.g. "SHA-256"). */
+    hashing_algorithm?: string | null;
+    /** Category names. */
+    categories?: string[] | null;
+    /** Category details (id + name) when `include_categories_details=true`. */
+    categories_details?: CategoryDetail[] | null;
+    /** Whether the coin is in preview/listing mode. */
+    preview_listing?: boolean | null;
+    /** Public notice message. */
+    public_notice?: string | null;
+    /** Additional notices. */
+    additional_notices?: string[] | null;
+    /** Localised names keyed by locale code. */
+    localization?: Record<string, string> | null;
+    /** Localised descriptions keyed by locale code. */
+    description?: Record<string, string> | null;
+    /** External links (homepage, socials, repos). */
+    links?: CoinLinks | null;
+    /** Coin image URLs. */
+    image?: ImageUrls | null;
+    /** Country of origin. */
+    country_origin?: string | null;
+    /** Genesis/launch date (YYYY-MM-DD). */
+    genesis_date?: string | null;
+    /** Positive sentiment vote percentage. */
+    sentiment_votes_up_percentage?: number | null;
+    /** Negative sentiment vote percentage. */
+    sentiment_votes_down_percentage?: number | null;
+    /** Number of users who have this coin in watchlist. */
+    watchlist_portfolio_users?: number | null;
+    /** Market cap rank. */
+    market_cap_rank?: number | null;
+    /** Market cap rank including rehypothecated tokens. */
+    market_cap_rank_with_rehypothecated?: number | null;
+    /** Full market data block. */
+    market_data?: CoinMarketData | null;
+    /** Community engagement data. */
+    community_data?: CoinCommunityData | null;
+    /** Developer activity data. */
+    developer_data?: CoinDeveloperData | null;
+    /** ISO timestamp of last update. */
+    last_updated?: string | null;
+    /** Sparkline 7-day price data (when `sparkline=true`). */
+    tickers?: CoinTicker[] | null;
+}
+/**
+ * Exchange info embedded in a ticker.
+ */
+interface TickerMarket {
+    /** Exchange name. */
+    name: string;
+    /** Exchange identifier (API ID). */
+    identifier: string;
+    /** Whether the exchange has trading incentives. */
+    has_trading_incentive: boolean;
+    /** Exchange logo URL (present when `include_exchange_logo=true`). */
+    logo?: string | null;
+}
+/**
+ * A single trading pair ticker for a coin.
+ *
+ * @example
+ * const ticker: CoinTicker = {
+ *   base: 'BTC',
+ *   target: 'USDT',
+ *   market: { name: 'Binance', identifier: 'binance', has_trading_incentive: false },
+ *   last: 69476,
+ *   volume: 20242.04,
+ * };
+ */
+interface CoinTicker {
+    /** Base currency symbol or contract address. */
+    base: string;
+    /** Quote/target currency symbol or contract address. */
+    target: string;
+    /** Exchange reference. */
+    market: TickerMarket;
+    /** Last traded price. */
+    last?: number | null;
+    /** Trade volume. */
+    volume?: number | null;
+    /** 2% orderbook depth: cost to move price up in USD. */
+    cost_to_move_up_usd?: number | null;
+    /** 2% orderbook depth: cost to move price down in USD. */
+    cost_to_move_down_usd?: number | null;
+    /** Last price in BTC, ETH, and USD. */
+    converted_last?: {
+        btc?: number;
+        eth?: number;
+        usd?: number;
+    } | null;
+    /** Volume in BTC, ETH, and USD. */
+    converted_volume?: {
+        btc?: number;
+        eth?: number;
+        usd?: number;
+    } | null;
+    /** Trust score assigned by CoinGecko. */
+    trust_score?: string | null;
+    /** Bid-ask spread percentage. */
+    bid_ask_spread_percentage?: number | null;
+    /** ISO timestamp of this ticker. */
+    timestamp?: string | null;
+    /** ISO timestamp of the last trade. */
+    last_traded_at?: string | null;
+    /** ISO timestamp of the last data fetch. */
+    last_fetch_at?: string | null;
+    /** Whether this ticker is anomalous. */
+    is_anomaly?: boolean | null;
+    /** Whether this ticker data is stale. */
+    is_stale?: boolean | null;
+    /** Direct trading URL on the exchange. */
+    trade_url?: string | null;
+    /** Token info URL (null for non-token markets). */
+    token_info_url?: string | null;
+    /** Coin ID for the base currency. */
+    coin_id?: string | null;
+    /** Coin ID for the target currency. */
+    target_coin_id?: string | null;
+    /** Market cap of the base coin in USD (may appear on exchange ticker responses). */
+    coin_mcap_usd?: number | null;
+}
+/**
+ * Response wrapper from `/coins/{id}/tickers`.
+ */
+interface CoinTickersResponse {
+    /** Coin name. */
+    name: string;
+    /** Array of tickers. */
+    tickers: CoinTicker[];
+}
+/**
+ * Response from `/coins/{id}/history`.
+ */
+interface CoinHistoricalData {
+    /** Coin API ID. */
+    id?: string | null;
+    /** Coin symbol. */
+    symbol?: string | null;
+    /** Coin name. */
+    name?: string | null;
+    /** Localised names. */
+    localization?: Record<string, string> | null;
+    /** Image URLs. */
+    image?: Pick<ImageUrls, 'thumb' | 'small'> | null;
+    /** Market data at the snapshot date. */
+    market_data?: {
+        current_price?: Record<string, number> | null;
+        market_cap?: Record<string, number> | null;
+        total_volume?: Record<string, number> | null;
+    } | null;
+    /** Community data at the snapshot date. */
+    community_data?: CoinCommunityData | null;
+    /** Developer data at the snapshot date. */
+    developer_data?: CoinDeveloperData | null;
+}
+/**
+ * Response from `/coins/{id}/market_chart` and related range endpoints.
+ *
+ * @example
+ * const chart: MarketChartResponse = {
+ *   prices: [[1712534400000, 69840]],
+ *   market_caps: [[1712534400000, 1381651251183]],
+ *   total_volumes: [[1712534400000, 20154184933]],
+ * };
+ */
+interface MarketChartResponse {
+    /** Array of [timestamp_ms, price] data points. */
+    prices: MarketDataPoint[];
+    /** Array of [timestamp_ms, market_cap] data points. */
+    market_caps: MarketDataPoint[];
+    /** Array of [timestamp_ms, volume] data points. */
+    total_volumes: MarketDataPoint[];
+}
+/**
+ * A single OHLC data point: [timestamp_ms, open, high, low, close].
+ *
+ * @example
+ * const candle: OhlcDataPoint = [1712534400000, 69000, 70215, 68060, 69840];
+ */
+type OhlcDataPoint = [number, number, number, number, number];
+/**
+ * Response from circulating supply chart endpoints.
+ * Each entry is [timestamp_ms, supply_value].
+ *
+ * @remarks Requires Enterprise plan
+ */
+type SupplyChartResponse = MarketDataPoint[];
+/**
+ * A minimal category entry from `/coins/categories/list`.
+ */
+interface CategoryListEntry {
+    /** Category ID. */
+    category_id: string;
+    /** Category name. */
+    name: string;
+}
+/**
+ * A category with market data from `/coins/categories`.
+ */
+interface Category {
+    /** Category ID. */
+    id: string;
+    /** Category name. */
+    name: string;
+    /** Market cap in USD. */
+    market_cap?: number | null;
+    /** 1h market cap change percentage. */
+    market_cap_change_1h?: number | null;
+    /** 24h market cap change percentage. */
+    market_cap_change_24h?: number | null;
+    /** 7d market cap change percentage. */
+    market_cap_change_7d?: number | null;
+    /** 30d market cap change percentage. */
+    market_cap_change_30d?: number | null;
+    /** 24h trading volume in USD. */
+    volume_24h?: number | null;
+    /** ISO timestamp of last update. */
+    updated_at?: string | null;
+    /** Top 3 coins in this category. */
+    top_3_coins?: string[] | null;
+    /** Top 3 coin image URLs. */
+    top_3_coins_id?: string[] | null;
+}
+/**
+ * Query parameters for `/asset_platforms`.
+ */
+interface AssetPlatformsParams {
+    /**
+     * Filter by platform type.
+     * `nft` returns only NFT-supported platforms.
+     */
+    filter?: 'nft' | string;
+}
+/**
+ * Query parameters for `/coins/{id}`.
+ */
+interface CoinDetailParams {
+    /** Include all localised names. Default: true. */
+    localization?: boolean;
+    /** Include ticker data. Default: true. */
+    tickers?: boolean;
+    /** Include market data. Default: true. */
+    market_data?: boolean;
+    /** Include community data. Default: true. */
+    community_data?: boolean;
+    /** Include developer data. Default: true. */
+    developer_data?: boolean;
+    /** Include 7-day sparkline data. Default: false. */
+    sparkline?: boolean;
+    /** Include category details (id + name). Default: false. */
+    include_categories_details?: boolean;
+}
+/**
+ * Query parameters for `/coins/{id}/tickers`.
+ */
+interface CoinTickerParams extends PaginationParams {
+    /** Filter results by exchange ID. */
+    exchange_ids?: string;
+    /** Include exchange logo URLs. Default: false. */
+    include_exchange_logo?: boolean;
+    /** Sort order. Default: trust_score_desc. */
+    order?: 'trust_score_desc' | 'trust_score_asc' | 'volume_desc' | 'volume_asc';
+    /** Return 2% orderbook depth data. Default: false. */
+    depth?: boolean;
+}
+/**
+ * Query parameters for `/coins/{id}/history`.
+ */
+interface CoinHistoryParams {
+    /**
+     * Historical snapshot date in `dd-mm-yyyy` format.
+     * @example '30-12-2022'
+     */
+    date: string;
+    /** Include all localised names. Default: true. */
+    localization?: boolean;
+}
+/**
+ * Query parameters for `/coins/{id}/market_chart`.
+ */
+interface MarketChartParams {
+    /** Target vs-currency for price data. */
+    vs_currency: VsCurrency;
+    /**
+     * Data granularity window.
+     * Pass a number of days (1–max) or `'max'` for all available history.
+     */
+    days: number | 'max';
+    /**
+     * Data interval granularity. Auto-selected when omitted.
+     * - `'daily'` — one point per day
+     * - `'hourly'` — one point per hour (max 90 days)
+     * - `'minutely'` — one point per minute (max 1 day, free tier only)
+     */
+    interval?: 'daily' | 'hourly' | 'minutely';
+    /** Decimal precision for currency values. */
+    precision?: string;
+}
+/**
+ * Query parameters for `/coins/{id}/market_chart/range`.
+ */
+interface MarketChartRangeParams {
+    /** Target vs-currency for price data. */
+    vs_currency: VsCurrency;
+    /** Start of the time range as a UNIX timestamp (seconds). */
+    from: number;
+    /** End of the time range as a UNIX timestamp (seconds). */
+    to: number;
+    /** Data interval granularity. Auto-selected when omitted. */
+    interval?: 'daily' | 'hourly' | 'minutely';
+    /** Decimal precision for currency values. */
+    precision?: string;
+}
+/**
+ * Query parameters for `/coins/{id}/ohlc`.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface OhlcParams {
+    /** Target vs-currency for OHLC data. */
+    vs_currency: VsCurrency;
+    /**
+     * Number of days of data to retrieve.
+     * Supported values: 1, 7, 14, 30, 90, 180, 365, or `'max'`.
+     */
+    days: 1 | 7 | 14 | 30 | 90 | 180 | 365 | 'max';
+    /** Decimal precision for currency values. */
+    precision?: string;
+}
+/**
+ * Query parameters for `/coins/{id}/ohlc/range`.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface OhlcRangeParams {
+    /** Target vs-currency for OHLC data. */
+    vs_currency: VsCurrency;
+    /** Start of the time range as a UNIX timestamp (seconds). */
+    from: number;
+    /** End of the time range as a UNIX timestamp (seconds). */
+    to: number;
+    /** Time series interval. */
+    interval?: 'daily' | 'hourly';
+    /** Decimal precision for currency values. */
+    precision?: string;
+}
+/**
+ * Query parameters for circulating/total supply chart endpoints.
+ *
+ * @remarks Requires Enterprise plan
+ */
+interface SupplyChartParams {
+    /**
+     * Number of days of data to retrieve.
+     * Supported values: 1, 7, 14, 30, 90, 180, 365, or `'max'`.
+     */
+    days: number | 'max';
+}
+/**
+ * Query parameters for circulating/total supply chart range endpoints.
+ *
+ * @remarks Requires Enterprise plan
+ */
+interface SupplyChartRangeParams {
+    /** Start of the time range as a UNIX timestamp (seconds). */
+    from: number;
+    /** End of the time range as a UNIX timestamp (seconds). */
+    to: number;
+}
+/**
+ * Query parameters for `/coins/categories`.
+ */
+interface CategoriesParams {
+    /**
+     * Sort order for the returned categories.
+     * Default: `market_cap_desc`.
+     */
+    order?: 'market_cap_desc' | 'market_cap_asc' | 'name_desc' | 'name_asc' | 'market_cap_change_24h_desc' | 'market_cap_change_24h_asc';
+}
+
+/**
+ * @module endpoints/coins
+ * CoinGecko coin-related endpoints.
+ *
+ * Covers simple price, coins list, market data, coin detail, tickers,
+ * historical charts, OHLC, supply charts, contract-address lookups, and
+ * categories.
+ */
+
+/**
+ * All coin-related CoinGecko API methods.
+ *
+ * Obtain an instance via the top-level SDK facade, e.g.:
+ * ```ts
+ * const sdk = new CoinGeckoSDK({ apiKey: '...' });
+ * const prices = await sdk.coins.price({ ids: 'bitcoin', vs_currencies: 'usd' });
+ * ```
+ */
+declare class CoinsEndpoints {
+    private readonly client;
+    constructor(client: CoinGeckoClient);
+    /**
+     * @description Get the current price of one or more coins in the requested
+     * vs-currencies. Optionally include market cap, 24h volume, 24h change, and
+     * last-updated timestamp in the response.
+     *
+     * @param params - Query parameters including required `ids` and
+     *   `vs_currencies` plus optional data flags.
+     * @returns A map of coin ID → currency code → numeric value.
+     *
+     * @example
+     * ```ts
+     * const prices = await coins.price({
+     *   ids: 'bitcoin,ethereum',
+     *   vs_currencies: 'usd,eur',
+     *   include_market_cap: true,
+     * });
+     * // { bitcoin: { usd: 69840, usd_market_cap: 1.38e12 }, ethereum: { usd: 3700 } }
+     * ```
+     */
+    price(params: SimplePriceParams): Promise<SimplePriceResponse>;
+    /**
+     * @description Get the current price of one or more ERC-20/token contract
+     * addresses on a given asset platform (e.g. `ethereum`).
+     *
+     * @param platformId - Asset platform ID (e.g. `'ethereum'`, `'polygon-pos'`).
+     * @param params - Query parameters including required `contract_addresses` and
+     *   `vs_currencies`.
+     * @returns A map of contract address → currency code → numeric value.
+     *
+     * @remarks Requires Analyst+ plan for more than one address per request.
+     *
+     * @example
+     * ```ts
+     * const tokenPrices = await coins.tokenPrice('ethereum', {
+     *   contract_addresses: '0xdac17f958d2ee523a2206206994597c13d831ec7',
+     *   vs_currencies: 'usd',
+     * });
+     * ```
+     */
+    tokenPrice(platformId: string, params: SimpleTokenPriceParams): Promise<SimplePriceResponse>;
+    /**
+     * @description Get the full list of vs-currency codes supported by CoinGecko
+     * (e.g. `'usd'`, `'eur'`, `'btc'`).
+     *
+     * @returns An array of currency code strings.
+     *
+     * @example
+     * ```ts
+     * const currencies = await coins.supportedVsCurrencies();
+     * // ['btc', 'eth', 'usd', 'eur', ...]
+     * ```
+     */
+    supportedVsCurrencies(): Promise<string[]>;
+    /**
+     * @description Get the full list of coins available on CoinGecko, including
+     * their IDs, symbols, and names.  Optionally include contract addresses per
+     * platform.
+     *
+     * @param params - Optional query parameters.
+     * @returns An array of minimal coin entries.
+     *
+     * @example
+     * ```ts
+     * const coins = await coins.list({ include_platform: true });
+     * // [{ id: 'bitcoin', symbol: 'btc', name: 'Bitcoin', platforms: {} }, ...]
+     * ```
+     */
+    list(params?: CoinsListParams): Promise<CoinListEntry[]>;
+    /**
+     * @description Get coin market data (price, market cap, volume, etc.) for
+     * all or a filtered set of coins ordered by market cap.
+     *
+     * @param params - Query parameters including required `vs_currency`.
+     * @returns An array of `MarketCoin` objects with full market statistics.
+     *
+     * @example
+     * ```ts
+     * const top10 = await coins.markets({ vs_currency: 'usd', per_page: 10 });
+     * ```
+     */
+    markets(params: CoinsMarketsParams): Promise<MarketCoin[]>;
+    /**
+     * @description Get the top 30 gaining and top 30 losing coins over a given
+     * time duration, filtered by the requested vs-currency.
+     *
+     * @param params - Optional query parameters including `vs_currency`,
+     *   `duration`, and `top_coins` filter.
+     * @returns An object with `top_gainers` and `top_losers` arrays.
+     *
+     * @remarks Requires Analyst+ plan.
+     *
+     * @example
+     * ```ts
+     * const movers = await coins.topGainersLosers({ vs_currency: 'usd', duration: '24h' });
+     * console.log(movers.top_gainers[0]);
+     * ```
+     */
+    topGainersLosers(params?: TopGainersLosersParams): Promise<TopMoversResponse>;
+    /**
+     * @description Get a list of the 200 most recently listed coins on CoinGecko,
+     * ordered by listing date descending.
+     *
+     * @returns An array of `NewCoin` entries with activation timestamps.
+     *
+     * @remarks Requires Analyst+ plan.
+     *
+     * @example
+     * ```ts
+     * const newCoins = await coins.listNew();
+     * console.log(newCoins[0].activated_at);
+     * ```
+     */
+    listNew(): Promise<NewCoin[]>;
+    /**
+     * @description Get comprehensive data for a specific coin by its CoinGecko
+     * ID, including market data, links, community stats, developer activity, and
+     * more.
+     *
+     * @param id - CoinGecko coin ID (e.g. `'bitcoin'`).
+     * @param params - Optional flags controlling which data blocks to include.
+     * @returns A `CoinDetail` object with all available metadata.
+     *
+     * @example
+     * ```ts
+     * const bitcoin = await coins.getById('bitcoin', { market_data: true, tickers: false });
+     * console.log(bitcoin.market_data?.current_price?.usd);
+     * ```
+     */
+    getById(id: string, params?: CoinDetailParams): Promise<CoinDetail>;
+    /**
+     * @description Get the exchange tickers for a specific coin, optionally
+     * filtered by exchange.
+     *
+     * @param id - CoinGecko coin ID (e.g. `'bitcoin'`).
+     * @param params - Optional pagination, exchange filter, and sort params.
+     * @returns A `CoinTickersResponse` wrapping the coin name and ticker array.
+     *
+     * @example
+     * ```ts
+     * const { tickers } = await coins.tickers('bitcoin', { exchange_ids: 'binance' });
+     * ```
+     */
+    tickers(id: string, params?: CoinTickerParams): Promise<CoinTickersResponse>;
+    /**
+     * @description Get historical snapshot data for a coin on a specific past
+     * date, including price, market cap, and volume.
+     *
+     * @param id - CoinGecko coin ID (e.g. `'bitcoin'`).
+     * @param params - Query parameters including required `date` (`dd-mm-yyyy`).
+     * @returns A `CoinHistoricalData` snapshot object.
+     *
+     * @example
+     * ```ts
+     * const snapshot = await coins.history('bitcoin', { date: '30-12-2022' });
+     * console.log(snapshot.market_data?.current_price?.usd);
+     * ```
+     */
+    history(id: string, params: CoinHistoryParams): Promise<CoinHistoricalData>;
+    /**
+     * @description Get historical market chart data (price, market cap, and
+     * volume) for a coin over a given number of days.  Data granularity is
+     * automatically selected unless `interval` is specified.
+     *
+     * @param id - CoinGecko coin ID (e.g. `'ethereum'`).
+     * @param params - Query parameters including required `vs_currency` and
+     *   `days`.
+     * @returns A `MarketChartResponse` containing price, market cap, and volume
+     *   time series.
+     *
+     * @example
+     * ```ts
+     * const chart = await coins.marketChart('ethereum', { vs_currency: 'usd', days: 30 });
+     * const [ts, price] = chart.prices[0];
+     * ```
+     */
+    marketChart(id: string, params: MarketChartParams): Promise<MarketChartResponse>;
+    /**
+     * @description Get historical market chart data (price, market cap, and
+     * volume) for a coin within a UNIX timestamp range.
+     *
+     * @param id - CoinGecko coin ID.
+     * @param params - Query parameters including `vs_currency`, `from`, and `to`
+     *   UNIX timestamps (seconds).
+     * @returns A `MarketChartResponse` containing price, market cap, and volume
+     *   time series.
+     *
+     * @example
+     * ```ts
+     * const chart = await coins.marketChartRange('bitcoin', {
+     *   vs_currency: 'usd',
+     *   from: 1640995200,
+     *   to: 1672531200,
+     * });
+     * ```
+     */
+    marketChartRange(id: string, params: MarketChartRangeParams): Promise<MarketChartResponse>;
+    /**
+     * @description Get OHLC (open, high, low, close) candlestick data for a coin
+     * over a given number of days.
+     *
+     * @param id - CoinGecko coin ID.
+     * @param params - Query parameters including required `vs_currency` and
+     *   `days`.
+     * @returns An array of OHLC data points, each formatted as
+     *   `[timestamp_ms, open, high, low, close]`.
+     *
+     * @remarks Requires Analyst+ plan.
+     *
+     * @example
+     * ```ts
+     * const candles = await coins.ohlc('bitcoin', { vs_currency: 'usd', days: 7 });
+     * const [ts, open, high, low, close] = candles[0];
+     * ```
+     */
+    ohlc(id: string, params: OhlcParams): Promise<OhlcDataPoint[]>;
+    /**
+     * @description Get OHLC (open, high, low, close) candlestick data for a coin
+     * within a UNIX timestamp range.
+     *
+     * @param id - CoinGecko coin ID.
+     * @param params - Query parameters including required `vs_currency`, `from`,
+     *   and `to` UNIX timestamps (seconds).
+     * @returns An array of OHLC data points, each formatted as
+     *   `[timestamp_ms, open, high, low, close]`.
+     *
+     * @remarks Requires Analyst+ plan.
+     *
+     * @example
+     * ```ts
+     * const candles = await coins.ohlcRange('bitcoin', {
+     *   vs_currency: 'usd',
+     *   from: 1640995200,
+     *   to: 1672531200,
+     * });
+     * ```
+     */
+    ohlcRange(id: string, params: OhlcRangeParams): Promise<OhlcDataPoint[]>;
+    /**
+     * @description Get the historical circulating supply chart for a coin over a
+     * given number of days.
+     *
+     * @param id - CoinGecko coin ID.
+     * @param params - Query parameters including required `days`.
+     * @returns An array of `[timestamp_ms, supply_value]` data points.
+     *
+     * @remarks Requires Enterprise plan.
+     *
+     * @example
+     * ```ts
+     * const supply = await coins.circulatingSupplyChart('bitcoin', { days: 365 });
+     * const [ts, value] = supply[0];
+     * ```
+     */
+    circulatingSupplyChart(id: string, params: SupplyChartParams): Promise<MarketDataPoint[]>;
+    /**
+     * @description Get the historical circulating supply chart for a coin within
+     * a UNIX timestamp range.
+     *
+     * @param id - CoinGecko coin ID.
+     * @param params - Query parameters including required `from` and `to` UNIX
+     *   timestamps (seconds).
+     * @returns An array of `[timestamp_ms, supply_value]` data points.
+     *
+     * @remarks Requires Enterprise plan.
+     *
+     * @example
+     * ```ts
+     * const supply = await coins.circulatingSupplyChartRange('bitcoin', {
+     *   from: 1640995200,
+     *   to: 1672531200,
+     * });
+     * ```
+     */
+    circulatingSupplyChartRange(id: string, params: SupplyChartRangeParams): Promise<MarketDataPoint[]>;
+    /**
+     * @description Get the historical total supply chart for a coin over a given
+     * number of days.
+     *
+     * @param id - CoinGecko coin ID.
+     * @param params - Query parameters including required `days`.
+     * @returns An array of `[timestamp_ms, supply_value]` data points.
+     *
+     * @remarks Requires Enterprise plan.
+     *
+     * @example
+     * ```ts
+     * const supply = await coins.totalSupplyChart('ethereum', { days: 90 });
+     * ```
+     */
+    totalSupplyChart(id: string, params: SupplyChartParams): Promise<MarketDataPoint[]>;
+    /**
+     * @description Get the historical total supply chart for a coin within a
+     * UNIX timestamp range.
+     *
+     * @param id - CoinGecko coin ID.
+     * @param params - Query parameters including required `from` and `to` UNIX
+     *   timestamps (seconds).
+     * @returns An array of `[timestamp_ms, supply_value]` data points.
+     *
+     * @remarks Requires Enterprise plan.
+     *
+     * @example
+     * ```ts
+     * const supply = await coins.totalSupplyChartRange('ethereum', {
+     *   from: 1640995200,
+     *   to: 1672531200,
+     * });
+     * ```
+     */
+    totalSupplyChartRange(id: string, params: SupplyChartRangeParams): Promise<MarketDataPoint[]>;
+    /**
+     * @description Get full coin data for a token by its smart contract address
+     * on a given asset platform.
+     *
+     * @param platformId - Asset platform ID (e.g. `'ethereum'`, `'binance-smart-chain'`).
+     * @param contractAddress - Token contract address (e.g. `'0xdac17f…'`).
+     * @returns A `CoinDetail` object equivalent to `/coins/{id}`.
+     *
+     * @example
+     * ```ts
+     * const usdt = await coins.getByContract(
+     *   'ethereum',
+     *   '0xdac17f958d2ee523a2206206994597c13d831ec7',
+     * );
+     * console.log(usdt.name); // 'Tether'
+     * ```
+     */
+    getByContract(platformId: string, contractAddress: string): Promise<CoinDetail>;
+    /**
+     * @description Get historical market chart data (price, market cap, volume)
+     * for a token identified by its contract address on a given asset platform.
+     *
+     * @param platformId - Asset platform ID (e.g. `'ethereum'`).
+     * @param contractAddress - Token contract address.
+     * @param params - Query parameters including required `vs_currency` and
+     *   `days`.
+     * @returns A `MarketChartResponse` with price, market cap, and volume time
+     *   series.
+     *
+     * @example
+     * ```ts
+     * const chart = await coins.contractMarketChart(
+     *   'ethereum',
+     *   '0xdac17f958d2ee523a2206206994597c13d831ec7',
+     *   { vs_currency: 'usd', days: 30 },
+     * );
+     * ```
+     */
+    contractMarketChart(platformId: string, contractAddress: string, params: MarketChartParams): Promise<MarketChartResponse>;
+    /**
+     * @description Get historical market chart data for a token identified by
+     * its contract address, within a UNIX timestamp range.
+     *
+     * @param platformId - Asset platform ID (e.g. `'ethereum'`).
+     * @param contractAddress - Token contract address.
+     * @param params - Query parameters including required `vs_currency`, `from`,
+     *   and `to` UNIX timestamps (seconds).
+     * @returns A `MarketChartResponse` with price, market cap, and volume time
+     *   series.
+     *
+     * @example
+     * ```ts
+     * const chart = await coins.contractMarketChartRange(
+     *   'ethereum',
+     *   '0xdac17f958d2ee523a2206206994597c13d831ec7',
+     *   { vs_currency: 'usd', from: 1640995200, to: 1672531200 },
+     * );
+     * ```
+     */
+    contractMarketChartRange(platformId: string, contractAddress: string, params: MarketChartRangeParams): Promise<MarketChartResponse>;
+    /**
+     * @description Get a flat list of all coin categories available on
+     * CoinGecko, returning only the category ID and name.
+     *
+     * @returns An array of `CategoryListEntry` items with `category_id` and
+     *   `name`.
+     *
+     * @example
+     * ```ts
+     * const list = await coins.categoriesList();
+     * // [{ category_id: 'decentralized-finance-defi', name: 'DeFi' }, ...]
+     * ```
+     */
+    categoriesList(): Promise<CategoryListEntry[]>;
+    /**
+     * @description Get all coin categories with market data (market cap, 24h
+     * change, volume, top coins), optionally sorted.
+     *
+     * @param params - Optional query parameters for sort order.
+     * @returns An array of `Category` objects with market statistics.
+     *
+     * @example
+     * ```ts
+     * const categories = await coins.categories({ order: 'market_cap_desc' });
+     * console.log(categories[0].name, categories[0].market_cap);
+     * ```
+     */
+    categories(params?: CategoriesParams): Promise<Category[]>;
+}
+
+/**
+ * Type definitions for CoinGecko exchange-related endpoints.
+ *
+ * Covers: /exchanges, /exchanges/list, /exchanges/{id},
+ * /exchanges/{id}/tickers, /exchanges/{id}/volume_chart,
+ * /exchanges/{id}/volume_chart/range (Analyst+).
+ */
+
+/**
+ * A minimal exchange entry from `/exchanges/list`.
+ */
+interface ExchangeListEntry {
+    /** Exchange API ID. */
+    id: string;
+    /** Exchange name. */
+    name: string;
+}
+/**
+ * Exchange entry from `/exchanges` with full market data.
+ *
+ * @example
+ * const ex: Exchange = {
+ *   id: 'binance',
+ *   name: 'Binance',
+ *   trust_score: 10,
+ *   trust_score_rank: 1,
+ *   trade_volume_24h_btc: 207319,
+ * };
+ */
+interface Exchange {
+    /** Exchange API ID. */
+    id: string;
+    /** Exchange name. */
+    name: string;
+    /** Year the exchange was established. */
+    year_established?: number | null;
+    /** Country of incorporation. */
+    country?: string | null;
+    /** Exchange description. */
+    description?: string | null;
+    /** Exchange website URL. */
+    url?: string | null;
+    /** Exchange logo image URL. */
+    image?: string | null;
+    /** Whether the exchange offers trading incentives. */
+    has_trading_incentive?: boolean | null;
+    /** CoinGecko trust score (1–10). */
+    trust_score?: number | null;
+    /** Rank by trust score. */
+    trust_score_rank?: number | null;
+    /** 24h trading volume denominated in BTC. */
+    trade_volume_24h_btc?: number | null;
+}
+/**
+ * Detailed exchange data from `/exchanges/{id}`.
+ * Includes social links, tickers, and volume.
+ *
+ * @example
+ * const detail: ExchangeDetail = {
+ *   name: 'Binance',
+ *   centralized: true,
+ *   trust_score: 9,
+ *   trade_volume_24h_btc: 207319.13,
+ *   tickers: [...],
+ * };
+ */
+interface ExchangeDetail {
+    /** Exchange name. */
+    name?: string | null;
+    /** Year the exchange was established. */
+    year_established?: number | null;
+    /** Country of incorporation. */
+    country?: string | null;
+    /** Exchange description. */
+    description?: string | null;
+    /** Exchange website URL. */
+    url?: string | null;
+    /** Exchange logo image URL. */
+    image?: string | null;
+    /** Facebook page URL. */
+    facebook_url?: string | null;
+    /** Reddit community URL. */
+    reddit_url?: string | null;
+    /** Telegram channel URL. */
+    telegram_url?: string | null;
+    /** Slack workspace URL. */
+    slack_url?: string | null;
+    /** Additional social/info URL 1. */
+    other_url_1?: string | null;
+    /** Additional social/info URL 2. */
+    other_url_2?: string | null;
+    /** Twitter handle. */
+    twitter_handle?: string | null;
+    /** Whether the exchange offers trading incentives. */
+    has_trading_incentive?: boolean | null;
+    /** Whether this is a centralized exchange. */
+    centralized?: boolean | null;
+    /** Public notice displayed on the exchange. */
+    public_notice?: string | null;
+    /** Alert notice for the exchange. */
+    alert_notice?: string | null;
+    /** CoinGecko trust score. */
+    trust_score?: number | null;
+    /** Rank by trust score. */
+    trust_score_rank?: number | null;
+    /** 24h trading volume in BTC. */
+    trade_volume_24h_btc?: number | null;
+    /** Number of coins listed on the exchange. */
+    coins?: number | null;
+    /** Number of trading pairs. */
+    pairs?: number | null;
+    /** Top 100 tickers (limited; use `/tickers` endpoint for more). */
+    tickers?: CoinTicker[] | null;
+}
+/**
+ * Query parameters for `/exchanges/{id}/tickers`.
+ */
+interface ExchangeTickersParams extends Omit<PaginationParams, 'per_page'> {
+    /** Filter by coin IDs (comma-separated). */
+    coin_ids?: string;
+    /** Include exchange logo. Default: false. */
+    include_exchange_logo?: boolean;
+    /** Include 2% orderbook depth data. Default: false. */
+    depth?: boolean;
+    /** Sort order. Default: trust_score_desc. */
+    order?: ExchangeTickerOrder;
+    /** Display DEX pair base/target as symbols instead of contract addresses. */
+    dex_pair_format?: 'contract_address' | 'symbol';
+}
+/**
+ * Response wrapper from `/exchanges/{id}/tickers`.
+ */
+interface ExchangeTickersResponse {
+    /** Exchange name. */
+    name: string;
+    /** Array of tickers. */
+    tickers: ExchangeTicker[];
+}
+/**
+ * A single exchange ticker (extends CoinTicker with exchange-specific fields).
+ */
+interface ExchangeTicker extends CoinTicker {
+    /** Market cap of the base coin in USD. */
+    coin_mcap_usd?: number | null;
+}
+/**
+ * A single volume chart data point: [timestamp_ms, volume_string].
+ * Volume is returned as a string to preserve precision.
+ *
+ * @example
+ * const point: VolumeChartPoint = [1711792200000, '306800.051794'];
+ */
+type VolumeChartPoint = [number, string];
+/**
+ * Response from `/exchanges/{id}/volume_chart`.
+ * Array of [timestamp_ms, volume_btc] pairs.
+ */
+type VolumeChartResponse = VolumeChartPoint[];
+/**
+ * Query parameters for `/exchanges/{id}/volume_chart`.
+ */
+interface VolumeChartParams {
+    /** Number of days of historical data. */
+    days: '1' | '7' | '14' | '30' | '90' | '180' | '365';
+}
+/**
+ * Query parameters for `/exchanges/{id}/volume_chart/range`.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface VolumeChartRangeParams {
+    /** Start of date range (Unix timestamp seconds). */
+    from: number;
+    /** End of date range (Unix timestamp seconds). */
+    to: number;
+}
+
+/**
+ * Type definitions for CoinGecko derivatives-related endpoints.
+ *
+ * Covers: /derivatives, /derivatives/exchanges,
+ * /derivatives/exchanges/{id}, /derivatives/exchanges/list.
+ */
+
+/**
+ * A single derivatives ticker from `/derivatives`.
+ *
+ * @example
+ * const ticker: DerivativeTicker = {
+ *   market: 'Binance (Futures)',
+ *   symbol: 'BTC-PERPUSDT',
+ *   index_id: 'BTC',
+ *   price: '69434.1',
+ *   contract_type: 'perpetual',
+ *   open_interest: 7690212057.6,
+ *   volume_24h: 132888173.547,
+ * };
+ */
+interface DerivativeTicker {
+    /** Derivatives exchange name. */
+    market?: string | null;
+    /** Ticker symbol. */
+    symbol?: string | null;
+    /** Underlying asset identifier (e.g. "BTC", "ETH"). */
+    index_id?: string | null;
+    /** Last traded price (as a string for precision). */
+    price?: string | null;
+    /** 24h price change percentage. */
+    price_percentage_change_24h?: number | null;
+    /** Contract type ("perpetual" or "futures"). */
+    contract_type?: string | null;
+    /** Current index (spot) price of the underlying asset. */
+    index?: number | null;
+    /** Basis = derivative price − index price. */
+    basis?: number | null;
+    /** Bid-ask spread. */
+    spread?: number | null;
+    /** Funding rate (perpetuals only). */
+    funding_rate?: number | null;
+    /** Open interest in USD. */
+    open_interest?: number | null;
+    /** 24h trading volume in USD. */
+    volume_24h?: number | null;
+    /** Unix timestamp of the last trade. */
+    last_traded_at?: number | null;
+    /** Expiry timestamp (ISO string), null for perpetuals. */
+    expired_at?: string | null;
+}
+/**
+ * Sort order options for `/derivatives/exchanges`.
+ */
+type DerivativesExchangeOrder = 'name_asc' | 'name_desc' | 'open_interest_btc_asc' | 'open_interest_btc_desc' | 'trade_volume_24h_btc_asc' | 'trade_volume_24h_btc_desc';
+/**
+ * Query parameters for `/derivatives/exchanges`.
+ */
+interface DerivativesExchangesParams extends PaginationParams {
+    /** Sort order. Default: open_interest_btc_desc. */
+    order?: DerivativesExchangeOrder;
+}
+/**
+ * A derivatives exchange entry from `/derivatives/exchanges`.
+ *
+ * @example
+ * const dex: DerivativeExchange = {
+ *   id: 'binance_futures',
+ *   name: 'Binance (Futures)',
+ *   open_interest_btc: 279958.61,
+ *   trade_volume_24h_btc: '574366.94',
+ *   number_of_perpetual_pairs: 330,
+ * };
+ */
+interface DerivativeExchange {
+    /** Exchange API ID. */
+    id?: string | null;
+    /** Exchange name. */
+    name?: string | null;
+    /** Total open interest in BTC. */
+    open_interest_btc?: number | null;
+    /** 24h trading volume in BTC (string for precision). */
+    trade_volume_24h_btc?: string | null;
+    /** Number of perpetual contract pairs. */
+    number_of_perpetual_pairs?: number | null;
+    /** Number of futures contract pairs. */
+    number_of_futures_pairs?: number | null;
+    /** Exchange logo image URL. */
+    image?: string | null;
+    /** Year established. */
+    year_established?: number | null;
+    /** Country of incorporation. */
+    country?: string | null;
+    /** Exchange description. */
+    description?: string | null;
+    /** Exchange website URL. */
+    url?: string | null;
+}
+/**
+ * Detailed derivatives exchange from `/derivatives/exchanges/{id}`.
+ * Extends DerivativeExchange with optional tickers.
+ */
+interface DerivativeExchangeDetail extends DerivativeExchange {
+    /** Tickers included when `include_tickers=all` or `include_tickers=unexpired`. */
+    tickers?: DerivativeTicker[] | null;
+}
+/**
+ * Query parameters for `/derivatives/exchanges/{id}`.
+ */
+interface DerivativesExchangeByIdParams {
+    /**
+     * Whether to include tickers.
+     * `all` includes all tickers; `unexpired` excludes expired ones.
+     * Omit to exclude tickers.
+     */
+    include_tickers?: 'all' | 'unexpired';
+}
+
+/**
+ * Type definitions for CoinGecko NFT-related endpoints.
+ *
+ * Covers: /nfts/list, /nfts/{id}, /nfts/{asset_platform_id}/contract/{contract_address},
+ * /nfts/markets (Analyst+), /nfts/{id}/market_chart (Analyst+),
+ * /nfts/{id}/tickers (Analyst+).
+ */
+
+/**
+ * A minimal NFT collection entry from `/nfts/list`.
+ */
+interface NftListEntry {
+    /** NFT collection API ID. */
+    id: string;
+    /** Token contract address. */
+    contract_address?: string | null;
+    /** Collection name. */
+    name: string;
+    /** Asset platform ID (e.g. "ethereum"). */
+    asset_platform_id?: string | null;
+    /** Collection ticker symbol (e.g. "BAYC"). */
+    symbol?: string | null;
+}
+/**
+ * NFT price/market-cap object with native currency and USD values.
+ */
+interface NftDualValue {
+    /** Value in the collection's native currency. */
+    native_currency?: number | null;
+    /** Value in USD. */
+    usd?: number | null;
+}
+/**
+ * NFT links block.
+ */
+interface NftLinks {
+    /** Collection website URL. */
+    homepage?: string | null;
+    /** Twitter profile URL. */
+    twitter?: string | null;
+    /** Discord server URL. */
+    discord?: string | null;
+}
+/**
+ * Block-explorer link for an NFT collection.
+ */
+interface NftExplorerLink {
+    /** Explorer name. */
+    name?: string | null;
+    /** Explorer URL for this collection. */
+    link?: string | null;
+}
+/**
+ * Full NFT collection data from `/nfts/{id}` or `/nfts/{platform}/contract/{address}`.
+ *
+ * @example
+ * const nft: NftCollection = {
+ *   id: 'pudgy-penguins',
+ *   name: 'Pudgy Penguins',
+ *   symbol: 'PPG',
+ *   native_currency: 'ethereum',
+ *   floor_price: { native_currency: 12.84, usd: 45920 },
+ * };
+ */
+interface NftCollection {
+    /** NFT collection API ID. */
+    id?: string | null;
+    /** Contract address. */
+    contract_address?: string | null;
+    /** Asset platform ID. */
+    asset_platform_id?: string | null;
+    /** Collection name. */
+    name?: string | null;
+    /** Collection symbol. */
+    symbol?: string | null;
+    /** Collection image URLs. */
+    image?: {
+        small?: string | null;
+        small_2x?: string | null;
+    } | null;
+    /** Banner image URL. */
+    banner_image?: {
+        small?: string | null;
+    } | null;
+    /** Collection description. */
+    description?: string | null;
+    /** Native currency name (e.g. "ethereum"). */
+    native_currency?: string | null;
+    /** Native currency ticker symbol (e.g. "ETH"). */
+    native_currency_symbol?: string | null;
+    /** Market cap rank among NFTs. */
+    market_cap_rank?: number | null;
+    /** Current floor price. */
+    floor_price?: NftDualValue | null;
+    /** Market capitalisation. */
+    market_cap?: NftDualValue | null;
+    /** 24h trading volume. */
+    volume_24h?: NftDualValue | null;
+    /** Floor price 24h change percentage in USD. */
+    floor_price_in_usd_24h_percentage_change?: number | null;
+    /** Floor price 24h change percentage in native and USD. */
+    floor_price_24h_percentage_change?: NftDualValue | null;
+    /** Market cap 24h change percentage. */
+    market_cap_24h_percentage_change?: NftDualValue | null;
+    /** Volume 24h change percentage. */
+    volume_24h_percentage_change?: NftDualValue | null;
+    /** Number of unique holder addresses. */
+    number_of_unique_addresses?: number | null;
+    /** Unique holder count 24h change percentage. */
+    number_of_unique_addresses_24h_percentage_change?: number | null;
+    /** Volume in USD 24h change percentage. */
+    volume_in_usd_24h_percentage_change?: number | null;
+    /** Total NFT supply. */
+    total_supply?: number | null;
+    /** Number of sales in the last day. */
+    one_day_sales?: number | null;
+    /** 24h change percentage for one-day sales count. */
+    one_day_sales_24h_percentage_change?: number | null;
+    /** Average sale price in the last day. */
+    one_day_average_sale_price?: number | null;
+    /** 24h change percentage for average sale price. */
+    one_day_average_sale_price_24h_percentage_change?: number | null;
+    /** External links. */
+    links?: NftLinks | null;
+    /** Floor price 7d change percentage. */
+    floor_price_7d_percentage_change?: NftDualValue | null;
+    /** Floor price 14d change percentage. */
+    floor_price_14d_percentage_change?: NftDualValue | null;
+    /** Floor price 30d change percentage. */
+    floor_price_30d_percentage_change?: NftDualValue | null;
+    /** Floor price 60d change percentage. */
+    floor_price_60d_percentage_change?: NftDualValue | null;
+    /** Floor price 1y change percentage. */
+    floor_price_1y_percentage_change?: NftDualValue | null;
+    /** Block explorer links. */
+    explorers?: NftExplorerLink[] | null;
+    /** Number of users who have favourited this collection. */
+    user_favorites_count?: number | null;
+    /** All-time high floor price. */
+    ath?: NftDualValue | null;
+    /** ATH change percentage. */
+    ath_change_percentage?: NftDualValue | null;
+    /** ATH date. */
+    ath_date?: {
+        native_currency?: string | null;
+        usd?: string | null;
+    } | null;
+}
+/**
+ * Query parameters for `/nfts/markets`.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface NftMarketsParams extends PaginationParams {
+    /** Asset platform to filter by. */
+    asset_platform_id?: string;
+    /** Sort order. */
+    order?: 'h24_volume_usd_asc' | 'h24_volume_usd_desc' | 'h24_volume_native_asc' | 'h24_volume_native_desc' | 'floor_price_native_asc' | 'floor_price_native_desc' | 'market_cap_native_asc' | 'market_cap_native_desc' | 'market_cap_usd_asc' | 'market_cap_usd_desc';
+}
+/**
+ * Response from `/nfts/{id}/market_chart`.
+ * Each series is an array of [timestamp_ms, value] pairs.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface NftMarketChart {
+    /** Floor price history in native currency. */
+    floor_price_native?: MarketDataPoint[] | null;
+    /** Floor price history in USD. */
+    floor_price_usd?: MarketDataPoint[] | null;
+    /** Market cap history in native currency. */
+    market_cap_native?: MarketDataPoint[] | null;
+    /** Market cap history in USD. */
+    market_cap_usd?: MarketDataPoint[] | null;
+    /** 24h volume history in native currency. */
+    volume_native?: MarketDataPoint[] | null;
+    /** 24h volume history in USD. */
+    volume_usd?: MarketDataPoint[] | null;
+}
+/**
+ * Query parameters for NFT market chart endpoints.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface NftMarketChartParams {
+    /** Number of days to look back. */
+    days: number | 'max';
+}
+/**
+ * A single NFT marketplace ticker entry.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface NftTicker {
+    /** Floor price in the marketplace's native currency. */
+    floor_price_in_native_currency?: number | null;
+    /** 24h trading volume in native currency. */
+    h24_volume_in_native_currency?: number | null;
+    /** Native currency name (e.g. "ethereum"). */
+    native_currency?: string | null;
+    /** Native currency symbol (e.g. "ETH"). */
+    native_currency_symbol?: string | null;
+    /** ISO timestamp of last update. */
+    updated_at?: string | null;
+    /** NFT marketplace API ID. */
+    nft_marketplace_id?: string | null;
+    /** Marketplace name. */
+    name?: string | null;
+    /** Marketplace logo image URL. */
+    image?: string | null;
+    /** Collection URL on the marketplace. */
+    nft_collection_url?: string | null;
+}
+/**
+ * Response from `/nfts/{id}/tickers`.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface NftTickersResponse {
+    /** Array of marketplace tickers. */
+    tickers: NftTicker[];
+}
+
+/**
+ * Type definitions for GeckoTerminal onchain DEX endpoints.
+ *
+ * Covers: /onchain/networks, /onchain/networks/{network}/dexes,
+ * /onchain/networks/{network}/pools/{address},
+ * /onchain/networks/{network}/pools/multi/{addresses},
+ * /onchain/networks/trending_pools, /onchain/networks/{network}/trending_pools,
+ * /onchain/networks/{network}/pools,
+ * /onchain/networks/{network}/dexes/{dex}/pools,
+ * /onchain/networks/new_pools, /onchain/networks/{network}/new_pools,
+ * /onchain/pools/megafilter (Analyst+),
+ * /onchain/search/pools, /onchain/pools/trending_search (Analyst+),
+ * /onchain/networks/{network}/tokens/{address}/pools,
+ * /onchain/networks/{network}/tokens/{address},
+ * /onchain/networks/{network}/tokens/multi/{addresses},
+ * /onchain/networks/{network}/tokens/{address}/info,
+ * /onchain/networks/{network}/pools/{pool_address}/info,
+ * /onchain/tokens/info_recently_updated,
+ * /onchain/networks/{network}/tokens/{address}/top_traders (Analyst+),
+ * /onchain/networks/{network}/tokens/{address}/top_holders (Analyst+),
+ * /onchain/networks/{network}/tokens/{address}/holders_chart (Analyst+),
+ * /onchain/networks/{network}/pools/{pool_address}/ohlcv/{timeframe},
+ * /onchain/networks/{network}/tokens/{address}/ohlcv/{timeframe} (Analyst+),
+ * /onchain/networks/{network}/pools/{pool_address}/trades,
+ * /onchain/networks/{network}/tokens/{address}/trades (Analyst+),
+ * /onchain/categories (Analyst+), /onchain/categories/{category_id}/pools (Analyst+).
+ */
+
+/**
+ * Generic JSON:API resource object wrapper used by GeckoTerminal responses.
+ */
+interface JsonApiResource<T> {
+    /** Resource identifier (e.g. "eth_0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"). */
+    id: string;
+    /** Resource type string (e.g. "pool", "token", "dex"). */
+    type: string;
+    /** Resource attributes. */
+    attributes: T;
+    /** Relationships to other resources. */
+    relationships?: Record<string, {
+        data: {
+            id: string;
+            type: string;
+        };
+    }> | null;
+}
+/**
+ * Generic JSON:API list response.
+ */
+interface JsonApiListResponse<T> {
+    data: JsonApiResource<T>[];
+    /** Sideloaded related resources (when `include` param is used). */
+    included?: JsonApiResource<Record<string, unknown>>[] | null;
+}
+/**
+ * Generic JSON:API single-item response.
+ */
+interface JsonApiSingleResponse<T> {
+    data: JsonApiResource<T>;
+    /** Sideloaded related resources (when `include` param is used). */
+    included?: JsonApiResource<Record<string, unknown>>[] | null;
+}
+/**
+ * Attributes for a supported network from `/onchain/networks`.
+ */
+interface NetworkAttributes {
+    /** Network name (e.g. "Ethereum"). */
+    name: string;
+    /** Short network identifier (e.g. "eth"). */
+    coingecko_asset_platform_id?: string | null;
+}
+/**
+ * A network entry from `/onchain/networks`.
+ */
+type Network = JsonApiResource<NetworkAttributes>;
+/**
+ * Response from `/onchain/networks`.
+ */
+type NetworksListResponse = JsonApiListResponse<NetworkAttributes>;
+/**
+ * Attributes for a DEX from `/onchain/networks/{network}/dexes`.
+ */
+interface DexAttributes {
+    /** DEX name (e.g. "Uniswap v3"). */
+    name: string;
+}
+/**
+ * A DEX entry from the DEX list endpoint.
+ */
+type DEX = JsonApiResource<DexAttributes>;
+/**
+ * Response from `/onchain/networks/{network}/dexes`.
+ */
+type DexListResponse = JsonApiListResponse<DexAttributes>;
+/**
+ * Transaction counts for a time window.
+ */
+interface PoolTransactionWindow {
+    /** Number of buy transactions. */
+    buys?: number | null;
+    /** Number of sell transactions. */
+    sells?: number | null;
+    /** Number of unique buyers. */
+    buyers?: number | null;
+    /** Number of unique sellers. */
+    sellers?: number | null;
+}
+/**
+ * Multi-timeframe transactions map (m5, m15, m30, h1, h6, h24).
+ */
+interface PoolTransactions {
+    m5?: PoolTransactionWindow | null;
+    m15?: PoolTransactionWindow | null;
+    m30?: PoolTransactionWindow | null;
+    h1?: PoolTransactionWindow | null;
+    h6?: PoolTransactionWindow | null;
+    h24?: PoolTransactionWindow | null;
+}
+/**
+ * Multi-timeframe string value map used for volume and price changes.
+ */
+interface PoolTimeframeStringMap {
+    m5?: string | null;
+    m15?: string | null;
+    m30?: string | null;
+    h1?: string | null;
+    h6?: string | null;
+    h24?: string | null;
+}
+/**
+ * Attributes for a pool resource from the onchain endpoints.
+ *
+ * @example
+ * const attrs: PoolAttributes = {
+ *   address: '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
+ *   name: 'WETH / USDC 0.05%',
+ *   reserve_in_usd: '90053526.89',
+ * };
+ */
+interface PoolAttributes {
+    /** Base token price in USD. */
+    base_token_price_usd?: string | null;
+    /** Base token price in the pool's native currency. */
+    base_token_price_native_currency?: string | null;
+    /** Base token balance in the pool. */
+    base_token_balance?: string | null;
+    /** Base token liquidity in USD. */
+    base_token_liquidity_usd?: string | null;
+    /** Quote token price in USD. */
+    quote_token_price_usd?: string | null;
+    /** Quote token price in native currency. */
+    quote_token_price_native_currency?: string | null;
+    /** Quote token balance in the pool. */
+    quote_token_balance?: string | null;
+    /** Quote token liquidity in USD. */
+    quote_token_liquidity_usd?: string | null;
+    /** Base token price expressed in quote token units. */
+    base_token_price_quote_token?: string | null;
+    /** Quote token price expressed in base token units. */
+    quote_token_price_base_token?: string | null;
+    /** Pool contract address. */
+    address?: string | null;
+    /** Descriptive pool name (e.g. "WETH / USDC 0.05%"). */
+    name?: string | null;
+    /** Short pool name without fee. */
+    pool_name?: string | null;
+    /** Pool fee percentage. */
+    pool_fee_percentage?: string | null;
+    /** ISO timestamp when the pool was created. */
+    pool_created_at?: string | null;
+    /** Fully diluted valuation in USD. */
+    fdv_usd?: string | null;
+    /** Market cap in USD (null if unverified). */
+    market_cap_usd?: string | null;
+    /** Price change percentages over various timeframes. */
+    price_change_percentage?: PoolTimeframeStringMap | null;
+    /** Transaction counts over various timeframes. */
+    transactions?: PoolTransactions | null;
+    /** Total volume in USD over various timeframes. */
+    volume_usd?: PoolTimeframeStringMap | null;
+    /** Net buy volume in USD over various timeframes. */
+    net_buy_volume_usd?: PoolTimeframeStringMap | null;
+    /** Buy volume in USD over various timeframes. */
+    buy_volume_usd?: PoolTimeframeStringMap | null;
+    /** Sell volume in USD over various timeframes. */
+    sell_volume_usd?: PoolTimeframeStringMap | null;
+    /** Total reserve in USD. */
+    reserve_in_usd?: string | null;
+    /** Percentage of liquidity that is locked. */
+    locked_liquidity_percentage?: string | null;
+}
+/**
+ * A pool resource from the onchain endpoints.
+ */
+type Pool = JsonApiResource<PoolAttributes>;
+/**
+ * A single pool response (JSON:API envelope).
+ */
+type PoolDetail = JsonApiSingleResponse<PoolAttributes>;
+/**
+ * Multiple pools response (JSON:API envelope).
+ */
+type PoolInfo = JsonApiListResponse<PoolAttributes>;
+/**
+ * Attributes for a token resource from the onchain endpoints.
+ */
+interface TokenAttributes {
+    /** Contract address. */
+    address?: string | null;
+    /** Token name. */
+    name?: string | null;
+    /** Token symbol. */
+    symbol?: string | null;
+    /** Number of decimal places. */
+    decimals?: number | null;
+    /** Image URL. */
+    image_url?: string | null;
+    /** CoinGecko coin ID (if matched). */
+    coingecko_coin_id?: string | null;
+    /** Price in USD. */
+    price_usd?: string | null;
+    /** Fully diluted valuation in USD. */
+    fdv_usd?: string | null;
+    /** Market cap in USD (null if unverified). */
+    market_cap_usd?: string | null;
+    /** 24h price change percentage. */
+    price_change_percentage_24h?: Record<string, string> | null;
+    /** 24h volume in USD. */
+    volume_usd?: Record<string, string> | null;
+    /** Total supply. */
+    total_supply?: string | null;
+}
+/**
+ * A token resource from the onchain endpoints.
+ */
+type TokenDetail = JsonApiResource<TokenAttributes>;
+/**
+ * Response for a single token.
+ */
+interface TokenDetailResponse {
+    data: TokenDetail;
+}
+/**
+ * GeckoTerminal score breakdown.
+ */
+interface GtScoreDetails {
+    pool?: number | null;
+    transaction?: number | null;
+    creation?: number | null;
+    info?: number | null;
+    holders?: number | null;
+}
+/**
+ * Token holder distribution percentages.
+ */
+interface HolderDistribution {
+    top_10?: string | null;
+    /** Holders ranked 11–30. */
+    '11_30'?: string | null;
+    /** Holders ranked 31–50. */
+    '31_50'?: string | null;
+    /** Remaining holders. */
+    rest?: string | null;
+}
+/**
+ * Token holder summary.
+ */
+interface TokenHolders {
+    /** Total holder count. */
+    count?: number | null;
+    /** Distribution percentages by holder rank. */
+    distribution_percentage?: HolderDistribution | null;
+    /** ISO timestamp of last holder data update. */
+    last_updated?: string | null;
+}
+/**
+ * Rich metadata attributes for a token (from `/tokens/{address}/info`).
+ */
+interface TokenInfoAttributes {
+    address?: string | null;
+    name?: string | null;
+    symbol?: string | null;
+    image_url?: string | null;
+    image?: {
+        thumb?: string | null;
+        small?: string | null;
+        large?: string | null;
+    } | null;
+    coingecko_coin_id?: string | null;
+    websites?: string[] | null;
+    description?: string | null;
+    gt_score?: number | null;
+    gt_score_details?: GtScoreDetails | null;
+    discord_url?: string | null;
+    farcaster_url?: string | null;
+    zora_url?: string | null;
+    telegram_handle?: string | null;
+    twitter_handle?: string | null;
+    categories?: string[] | null;
+    gt_categories_id?: string[] | null;
+    holders?: TokenHolders | null;
+    mint_authority?: string | null;
+    freeze_authority?: string | null;
+    is_honeypot?: boolean | string | null;
+}
+/**
+ * Token info resource.
+ */
+type TokenInfo = JsonApiResource<TokenInfoAttributes>;
+/**
+ * Response from `/tokens/{address}/info`.
+ */
+interface TokenInfoResponse {
+    data: TokenInfo;
+}
+/**
+ * A single top trader entry.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface TopTrader {
+    /** Trader wallet address. */
+    address?: string | null;
+    /** Trader type (e.g. "bot", "whale"). */
+    type?: string | null;
+    /** 24h profit and loss in USD. */
+    pnl_usd?: string | null;
+    /** 24h realized profit in USD. */
+    realized_profit_usd?: string | null;
+    /** 24h buy volume in USD. */
+    buy_volume_usd?: string | null;
+    /** 24h sell volume in USD. */
+    sell_volume_usd?: string | null;
+    /** Number of buy trades. */
+    buy_count?: number | null;
+    /** Number of sell trades. */
+    sell_count?: number | null;
+}
+/**
+ * A single top holder entry.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface TopHolder {
+    /** Holder wallet address. */
+    address?: string | null;
+    /** Holder type (e.g. "institution", "smart_money"). */
+    type?: string | null;
+    /** Amount of tokens held. */
+    amount?: string | null;
+    /** Value of holdings in USD. */
+    value_usd?: string | null;
+    /** Percentage of total supply held. */
+    percentage?: string | null;
+}
+/**
+ * A single data point in the holder count chart.
+ * Format: [unix_timestamp_seconds, holder_count].
+ *
+ * @remarks Requires Analyst+ plan
+ */
+type HolderChartPoint = [number, number];
+/**
+ * Response from `/tokens/{address}/holders_chart`.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface HolderChartResponse {
+    data?: {
+        id?: string | null;
+        type?: string | null;
+        attributes?: {
+            /** Array of [timestamp, holder_count] data points. */
+            holders_chart?: HolderChartPoint[] | null;
+        } | null;
+    } | null;
+}
+/**
+ * A single OHLCV data point.
+ * Format: [timestamp_seconds, open, high, low, close, volume].
+ *
+ * @example
+ * const candle: OHLCV = [1712534400, 3454.6, 3660.9, 3417.9, 3660.9, 306823];
+ */
+type OHLCV = [number, number, number, number, number, number];
+/**
+ * Token metadata included in OHLCV meta block.
+ */
+interface OhlcvTokenMeta {
+    /** Contract address. */
+    address?: string | null;
+    /** Token name. */
+    name?: string | null;
+    /** Token symbol. */
+    symbol?: string | null;
+    /** CoinGecko coin ID. */
+    coingecko_coin_id?: string | null;
+}
+/**
+ * Response from pool and token OHLCV endpoints.
+ */
+interface OhlcvResponse {
+    data?: {
+        id?: string | null;
+        type?: string | null;
+        attributes?: {
+            /** Array of OHLCV data points. */
+            ohlcv_list?: OHLCV[] | null;
+        } | null;
+    } | null;
+    meta?: {
+        /** Base token metadata. */
+        base?: OhlcvTokenMeta | null;
+        /** Quote token metadata. */
+        quote?: OhlcvTokenMeta | null;
+    } | null;
+}
+/**
+ * Query parameters for OHLCV endpoints.
+ */
+interface OhlcvParams {
+    /** Aggregation period (e.g. "1", "5", "15" for minutes). */
+    aggregate?: string;
+    /** Return data before this Unix timestamp. */
+    before_timestamp?: number;
+    /** Number of candles to return (max 1000). Default: 100. */
+    limit?: number;
+    /** Currency for OHLCV values. Default: "usd". */
+    currency?: 'usd' | 'token';
+    /** Return OHLCV for "base", "quote", or a specific token address. Default: "base". */
+    token?: string;
+    /** Include empty (no-trade) intervals. Default: false. */
+    include_empty_intervals?: boolean;
+}
+/**
+ * A single trade entry from pool/token trades endpoints.
+ */
+interface Trade {
+    /** Transaction hash. */
+    tx_hash?: string | null;
+    /** Unix timestamp of the trade. */
+    block_timestamp?: string | null;
+    /** Trade side ("buy" or "sell"). */
+    kind?: 'buy' | 'sell' | string | null;
+    /** Price in USD at trade time. */
+    price_usd?: string | null;
+    /** USD volume of this trade. */
+    volume_usd?: string | null;
+    /** Amount of base token traded. */
+    from_token_amount?: string | null;
+    /** Amount of quote token traded. */
+    to_token_amount?: string | null;
+}
+/**
+ * Response from pool/token trades endpoints.
+ */
+interface TradesResponse {
+    data?: JsonApiResource<{
+        trades?: Trade[] | null;
+    }>[] | null;
+}
+/**
+ * Query parameters for `/onchain/pools/megafilter`.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface MegafilterParams extends PaginationParams {
+    /** Comma-separated network IDs to filter by. */
+    network?: string;
+    /** Comma-separated DEX IDs to filter by. */
+    dex?: string;
+    /** Minimum pool age in hours. */
+    pool_created_hour_gte?: number;
+    /** Maximum pool age in hours. */
+    pool_created_hour_lte?: number;
+    /** Minimum reserve in USD. */
+    reserve_in_usd_gte?: number;
+    /** Maximum reserve in USD. */
+    reserve_in_usd_lte?: number;
+    /** Minimum fully diluted valuation in USD. */
+    fdv_usd_gte?: number;
+    /** Maximum fully diluted valuation in USD. */
+    fdv_usd_lte?: number;
+    /** Minimum market cap in USD. */
+    market_cap_usd_gte?: number;
+    /** Maximum market cap in USD. */
+    market_cap_usd_lte?: number;
+    /** Sort field (e.g. "h24_volume_usd"). */
+    sort?: string;
+    /** Filter by GeckoTerminal category ID. */
+    categories?: string;
+    /** Filter by verified or unverified tokens. */
+    token_type?: 'verified' | 'unverified';
+}
+/**
+ * A GeckoTerminal onchain category from `/onchain/categories`.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface OnchainCategory {
+    /** Category attributes. */
+    id?: string | null;
+    type?: string | null;
+    attributes?: {
+        /** Category name. */
+        name?: string | null;
+        /** Category description. */
+        description?: string | null;
+    } | null;
+}
+/**
+ * Response from `/onchain/categories`.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface OnchainCategoriesResponse {
+    data: OnchainCategory[];
+}
+
+/**
+ * Type definitions for CoinGecko global market, search, trending,
+ * exchange rates, and asset platform endpoints.
+ *
+ * Covers: /global, /global/decentralized_finance_defi,
+ * /global/market_cap_chart (Analyst+),
+ * /search, /search/trending,
+ * /exchange_rates, /asset_platforms.
+ */
+
+/**
+ * Inner data payload of the `/global` endpoint.
+ */
+interface GlobalDataPayload {
+    /** Number of active cryptocurrencies. */
+    active_cryptocurrencies?: number | null;
+    /** Number of upcoming ICOs. */
+    upcoming_icos?: number | null;
+    /** Number of ongoing ICOs. */
+    ongoing_icos?: number | null;
+    /** Number of ended ICOs. */
+    ended_icos?: number | null;
+    /** Number of active exchanges. */
+    markets?: number | null;
+    /** Total market cap in various currencies. */
+    total_market_cap?: CurrencyMap | null;
+    /** Total 24h trading volume in various currencies. */
+    total_volume?: CurrencyMap | null;
+    /** Market cap dominance percentage by coin (e.g. { btc: 50.4, eth: 14.9 }). */
+    market_cap_percentage?: Record<string, number> | null;
+    /** Total market cap 24h change percentage in USD. */
+    market_cap_change_percentage_24h_usd?: number | null;
+    /** Total volume 24h change percentage in USD. */
+    volume_change_percentage_24h_usd?: number | null;
+    /** Unix timestamp of last update. */
+    updated_at?: number | null;
+}
+/**
+ * Response from `/global`.
+ */
+interface GlobalData {
+    /** Global market data payload. */
+    data: GlobalDataPayload;
+}
+/**
+ * Inner data payload of the `/global/decentralized_finance_defi` endpoint.
+ */
+interface GlobalDefiPayload {
+    /** Total DeFi market cap (as a high-precision string). */
+    defi_market_cap?: string | null;
+    /** Ethereum market cap (as a high-precision string). */
+    eth_market_cap?: string | null;
+    /** DeFi-to-ETH market cap ratio (as a high-precision string). */
+    defi_to_eth_ratio?: string | null;
+    /** 24h DeFi trading volume (as a high-precision string). */
+    trading_volume_24h?: string | null;
+    /** DeFi dominance percentage (as a high-precision string). */
+    defi_dominance?: string | null;
+    /** Name of the top DeFi coin. */
+    top_coin_name?: string | null;
+    /** Top coin's DeFi dominance percentage. */
+    top_coin_defi_dominance?: number | null;
+}
+/**
+ * Response from `/global/decentralized_finance_defi`.
+ */
+interface GlobalDefiData {
+    /** DeFi global data payload. */
+    data: GlobalDefiPayload;
+}
+/**
+ * Query parameters for `/global/market_cap_chart`.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface GlobalMarketCapChartParams {
+    /** Number of days of historical data. */
+    days: number | 'max';
+    /** Target vs-currency for market cap values. Default: usd. */
+    vs_currency?: string;
+}
+/**
+ * Response from `/global/market_cap_chart`.
+ *
+ * @remarks Requires Analyst+ plan
+ */
+interface GlobalMarketCapChartResponse {
+    market_cap_chart: {
+        /** Array of [timestamp_ms, market_cap] data points. */
+        market_cap: MarketDataPoint[];
+        /** Array of [timestamp_ms, volume] data points. */
+        volume: MarketDataPoint[];
+    };
+}
+/**
+ * Response from `/ping`.
+ */
+interface PingResponse {
+    /** CoinGecko server status string (e.g. `"(V3) To the Moon!"`). */
+    gecko_says: string;
+}
+/**
+ * Current API plan usage from `/key`.
+ *
+ * @remarks Requires a valid Pro API key (Analyst+ plan).
+ */
+interface ApiUsageResponse {
+    /** Name of the active plan (e.g. `"Analyst"`, `"Lite"`). */
+    plan?: string | null;
+    /** Rate limit in requests per minute for the active plan. */
+    rate_limit_request_per_minute?: number | null;
+    /** Number of monthly credits used so far. */
+    monthly_call_credit?: number | null;
+    /** Remaining credits this month. */
+    current_remaining_monthly_calls?: number | null;
+    /** Total credits allocated for the current month. */
+    current_total_monthly_calls?: number | null;
+}
+/**
+ * A trending coin entry from `/search/trending`.
+ */
+interface TrendingCoin {
+    /** Coin API ID. */
+    id?: string | null;
+    /** Market cap rank. */
+    coin_id?: number | null;
+    /** Coin name. */
+    name?: string | null;
+    /** Coin symbol. */
+    symbol?: string | null;
+    /** Market cap rank. */
+    market_cap_rank?: number | null;
+    /** Thumbnail image URL. */
+    thumb?: string | null;
+    /** Small image URL. */
+    small?: string | null;
+    /** Large image URL. */
+    large?: string | null;
+    /** CoinGecko slug. */
+    slug?: string | null;
+    /** Price in BTC. */
+    price_btc?: number | null;
+    /** Score in the trending list (lower = more trending). */
+    score?: number | null;
+    /** Additional coin data. */
+    data?: {
+        price?: string | number | null;
+        price_btc?: string | null;
+        price_change_percentage_24h?: Record<string, number> | null;
+        market_cap?: string | null;
+        market_cap_btc?: string | null;
+        total_volume?: string | null;
+        total_volume_btc?: string | null;
+        sparkline?: string | null;
+    } | null;
+}
+/**
+ * A trending NFT entry from `/search/trending`.
+ */
+interface TrendingNft {
+    /** NFT collection ID. */
+    id?: string | null;
+    /** Collection name. */
+    name?: string | null;
+    /** Asset platform ID. */
+    asset_platform_id?: string | null;
+    /** NFT symbol. */
+    symbol?: string | null;
+    /** Thumbnail image URL. */
+    thumb?: string | null;
+    /** NFT floor price data. */
+    data?: {
+        floor_price?: string | null;
+        floor_price_in_usd_24h_percentage_change?: string | null;
+        h24_volume?: string | null;
+        h24_average_sale_price?: string | null;
+    } | null;
+}
+/**
+ * A trending category entry from `/search/trending`.
+ */
+interface TrendingCategory {
+    /** Category ID. */
+    id?: number | null;
+    /** Category name. */
+    name?: string | null;
+    /** Market cap in 1h change percentage. */
+    market_cap_1h_change?: number | null;
+    /** Slug. */
+    slug?: string | null;
+    /** Coins data for this category. */
+    coins_count?: number | null;
+    /** Data snapshot. */
+    data?: {
+        market_cap?: number | null;
+        market_cap_btc?: number | null;
+        total_volume?: number | null;
+        total_volume_btc?: number | null;
+        market_cap_change_percentage_24h?: Record<string, number> | null;
+        sparkline?: string | null;
+    } | null;
+}
+/**
+ * Response from `/search/trending`.
+ */
+interface TrendingResponse {
+    coins: Array<{
+        item: TrendingCoin;
+    }>;
+    nfts: TrendingNft[];
+    categories: TrendingCategory[];
+}
+/**
+ * A coin result from `/search`.
+ */
+interface SearchCoin {
+    id?: string | null;
+    name?: string | null;
+    symbol?: string | null;
+    market_cap_rank?: number | null;
+    thumb?: string | null;
+    large?: string | null;
+}
+/**
+ * An exchange result from `/search`.
+ */
+interface SearchExchange {
+    id?: string | null;
+    name?: string | null;
+    market_type?: string | null;
+    thumb?: string | null;
+    large?: string | null;
+}
+/**
+ * A category result from `/search`.
+ */
+interface SearchCategory {
+    id?: number | null;
+    name?: string | null;
+}
+/**
+ * An NFT result from `/search`.
+ */
+interface SearchNft {
+    id?: string | null;
+    name?: string | null;
+    asset_platform_id?: string | null;
+    thumb?: string | null;
+}
+/**
+ * Response from `/search`.
+ */
+interface SearchResponse {
+    coins: SearchCoin[];
+    exchanges: SearchExchange[];
+    icos: unknown[];
+    categories: SearchCategory[];
+    nfts: SearchNft[];
+}
+/**
+ * A single BTC exchange rate entry.
+ */
+interface ExchangeRateEntry {
+    /** Currency name. */
+    name?: string | null;
+    /** Currency unit symbol. */
+    unit?: string | null;
+    /** Current exchange rate value relative to BTC. */
+    value?: number | null;
+    /** Currency type ("fiat", "crypto", or "commodity"). */
+    type?: string | null;
+}
+/**
+ * Response from `/exchange_rates`.
+ */
+interface ExchangeRatesResponse {
+    /** Map of currency code → exchange rate info. */
+    rates: Record<string, ExchangeRateEntry>;
+}
+/** Convenience alias for a single exchange rate. */
+type ExchangeRate = ExchangeRateEntry;
+/**
+ * An asset platform (blockchain network) from `/asset_platforms`.
+ *
+ * @example
+ * const platform: AssetPlatform = {
+ *   id: 'ethereum',
+ *   name: 'Ethereum',
+ *   chain_identifier: 1,
+ *   shortname: 'ETH',
+ * };
+ */
+interface AssetPlatform {
+    /** Platform API ID (e.g. "ethereum"). */
+    id?: string | null;
+    /** Chain identifier (EVM chain ID). */
+    chain_identifier?: number | null;
+    /** Platform display name. */
+    name?: string | null;
+    /** Short display name or ticker. */
+    shortname?: string | null;
+    /** Native coin ID on CoinGecko. */
+    native_coin_id?: string | null;
+    /** Image URLs for the platform. */
+    image?: {
+        thumb?: string | null;
+        small?: string | null;
+        large?: string | null;
+    } | null;
+}
+
+/**
+ * Type definitions for CoinGecko Public Treasury endpoints.
+ *
+ * Covers: /entities/list, /{entity}/public_treasury/{coin_id},
+ * /public_treasury/{entity_id}, /public_treasury/{entity_id}/{coin_id}/holding_chart,
+ * /public_treasury/{entity_id}/transaction_history.
+ */
+
+/**
+ * A minimal entity entry from `/entities/list`.
+ */
+interface Entity {
+    /** Entity API ID. */
+    id: string;
+    /** Stock ticker symbol (for public companies). */
+    symbol?: string | null;
+    /** Entity name. */
+    name: string;
+    /** ISO 3166-1 alpha-2 country code. */
+    country?: string | null;
+}
+/**
+ * A single company or government holding entry.
+ */
+interface TreasuryHolding {
+    /** Entity name. */
+    name?: string | null;
+    /** Stock ticker symbol. */
+    symbol?: string | null;
+    /** Country code. */
+    country?: string | null;
+    /** Total cryptocurrency holdings. */
+    total_holdings?: number | null;
+    /** Total entry/cost value in USD. */
+    total_entry_value_usd?: number | null;
+    /** Current value of holdings in USD. */
+    total_current_value_usd?: number | null;
+    /** Percentage of total crypto supply. */
+    percentage_of_total_supply?: number | null;
+}
+/**
+ * Response from `/{entity}/public_treasury/{coin_id}` for companies.
+ */
+interface CompanyTreasuryResponse {
+    /** Total holdings across all companies. */
+    total_holdings?: number | null;
+    /** Total value of all holdings in USD. */
+    total_value_usd?: number | null;
+    /** Market cap dominance percentage. */
+    market_cap_dominance?: number | null;
+    /** List of company holdings. */
+    companies: TreasuryHolding[];
+}
+/**
+ * Response from `/{entity}/public_treasury/{coin_id}` for governments.
+ */
+interface GovernmentTreasuryResponse {
+    /** Total holdings across all governments. */
+    total_holdings?: number | null;
+    /** Total value of all holdings in USD. */
+    total_value_usd?: number | null;
+    /** Market cap dominance percentage. */
+    market_cap_dominance?: number | null;
+    /** List of government holdings. */
+    governments: TreasuryHolding[];
+}
+/**
+ * Time-series change data for a holding over various periods.
+ */
+interface HoldingTimeframeChange {
+    '7d'?: number | null;
+    '14d'?: number | null;
+    '30d'?: number | null;
+    '90d'?: number | null;
+    '1y'?: number | null;
+    ytd?: number | null;
+}
+/**
+ * A single cryptocurrency holding within an entity's treasury.
+ */
+interface EntityHolding {
+    /** Coin API ID (e.g. "bitcoin"). */
+    coin_id?: string | null;
+    /** Amount held. */
+    amount?: number | null;
+    /** Percentage of the coin's total supply. */
+    percentage_of_total_supply?: number | null;
+    /** Amount per equity share. */
+    amount_per_share?: number | null;
+    /** This holding as a percentage of entity's total treasury value. */
+    entity_value_usd_percentage?: number | null;
+    /** Current value in USD. */
+    current_value_usd?: number | null;
+    /** Total cost/entry value in USD. */
+    total_entry_value_usd?: number | null;
+    /** Average cost per unit in USD. */
+    average_entry_value_usd?: number | null;
+    /** Unrealized profit and loss in USD. */
+    unrealized_pnl?: number | null;
+    /**
+     * Holding amount changes over timeframes.
+     * Only present when `holding_amount_change` param is specified.
+     */
+    holding_amount_change?: HoldingTimeframeChange | null;
+    /**
+     * Holding change percentages over timeframes.
+     * Only present when `holding_change_percentage` param is specified.
+     */
+    holding_change_percentage?: HoldingTimeframeChange | null;
+}
+/**
+ * Full entity treasury response from `/public_treasury/{entity_id}`.
+ *
+ * @example
+ * const treasury: PublicTreasuryEntity = {
+ *   id: 'strategy',
+ *   name: 'Strategy',
+ *   type: 'company',
+ *   symbol: 'MSTR.US',
+ *   total_treasury_value_usd: 48119580010,
+ *   holdings: [{ coin_id: 'bitcoin', amount: 714644 }],
+ * };
+ */
+interface PublicTreasuryEntity {
+    /** Entity name. */
+    name?: string | null;
+    /** Entity API ID. */
+    id?: string | null;
+    /** Entity type: "company" or "government". */
+    type?: string | null;
+    /** Stock market symbol (for companies). */
+    symbol?: string | null;
+    /** ISO country code. */
+    country?: string | null;
+    /** Official website URL. */
+    website_url?: string | null;
+    /** Twitter handle. */
+    twitter_screen_name?: string | null;
+    /** Total treasury value across all holdings in USD. */
+    total_treasury_value_usd?: number | null;
+    /** Unrealized PnL (current value − total entry value). */
+    unrealized_pnl?: number | null;
+    /** Market NAV ratio. */
+    m_nav?: number | null;
+    /** Total asset value per equity share in USD. */
+    total_asset_value_per_share_usd?: number | null;
+    /** List of individual cryptocurrency holdings. */
+    holdings?: EntityHolding[] | null;
+}
+/**
+ * A single data point in the treasury holding chart.
+ * Format: [unix_timestamp_ms, value].
+ */
+type HoldingChartPoint = [number, number];
+/**
+ * Response from `/public_treasury/{entity_id}/{coin_id}/holding_chart`.
+ */
+interface TreasuryHoldingChartResponse {
+    /** Array of [timestamp_ms, holding_amount] data points. */
+    holdings?: HoldingChartPoint[] | null;
+    /** Array of [timestamp_ms, value_usd] data points. */
+    holding_value_in_usd?: HoldingChartPoint[] | null;
+}
+/**
+ * Query parameters for `/public_treasury/{entity_id}/{coin_id}/holding_chart`.
+ */
+interface TreasuryHoldingChartParams {
+    /** Number of days of historical data. Also accepts "max". */
+    days: '7' | '14' | '30' | '90' | '180' | '365' | '730' | 'max';
+    /** Include intervals with no transaction data. Default: false. */
+    include_empty_intervals?: boolean;
+}
+/**
+ * A single treasury transaction entry.
+ */
+interface TreasuryTransaction {
+    /** Coin API ID. */
+    coin_id?: string | null;
+    /** ISO date of the transaction. */
+    date?: string | null;
+    /** Transaction amount (positive = buy, negative = sell). */
+    amount?: number | null;
+    /** Transaction type ("buy" or "sell"). */
+    transaction_type?: string | null;
+    /** Entry price per unit in USD. */
+    price_per_token_usd?: number | null;
+    /** Total transaction value in USD. */
+    total_value_usd?: number | null;
+}
+/**
+ * Response from `/public_treasury/{entity_id}/transaction_history`.
+ */
+interface TreasuryTransactionHistoryResponse {
+    /** Array of transaction records. */
+    data?: TreasuryTransaction[] | null;
+}
+/**
+ * Query parameters for `/public_treasury/{entity_id}/transaction_history`.
+ */
+interface TreasuryTransactionHistoryParams extends PaginationParams {
+    /** Filter by specific coin IDs (comma-separated). */
+    coin_ids?: string;
+}
+
+/**
+ * @module endpoints/exchanges
+ * Endpoint methods for CoinGecko exchange-related API paths.
+ *
+ * Covers: /exchanges, /exchanges/list, /exchanges/{id},
+ * /exchanges/{id}/tickers, /exchanges/{id}/volume_chart,
+ * /exchanges/{id}/volume_chart/range (Analyst+).
+ */
+
+/**
+ * Endpoint group for CoinGecko exchange APIs.
+ *
+ * Obtain an instance via the SDK's top-level entry point; do not
+ * instantiate directly.
+ *
+ * @example
+ * ```ts
+ * const exchanges = new ExchangesEndpoints(client);
+ * const all = await exchanges.list();
+ * ```
+ */
+declare class ExchangesEndpoints {
+    private readonly client;
+    constructor(client: CoinGeckoClient);
+    /**
+     * Returns a paginated list of all active exchanges with market data.
+     *
+     * @param params - Optional pagination parameters (`per_page`, `page`).
+     * @returns Array of {@link Exchange} objects ordered by trust score rank.
+     *
+     * @example
+     * ```ts
+     * const page1 = await exchanges.list({ per_page: 50, page: 1 });
+     * ```
+     */
+    list(params?: {
+        per_page?: number;
+        page?: number;
+    }): Promise<Exchange[]>;
+    /**
+     * Returns a lightweight list of all exchange IDs and names.
+     *
+     * Use this endpoint to resolve exchange API IDs for subsequent calls
+     * rather than fetching full exchange data.
+     *
+     * @returns Array of {@link ExchangeListEntry} objects (`id` + `name` only).
+     *
+     * @example
+     * ```ts
+     * const ids = await exchanges.listAll();
+     * // [{ id: 'binance', name: 'Binance' }, ...]
+     * ```
+     */
+    listAll(): Promise<ExchangeListEntry[]>;
+    /**
+     * Returns full details for a single exchange by its API ID.
+     *
+     * @param id - Exchange API ID (e.g. `"binance"`). Use {@link listAll} to
+     *   discover valid IDs.
+     * @returns {@link ExchangeDetail} including social links, trust score, and
+     *   top 100 tickers.
+     *
+     * @example
+     * ```ts
+     * const binance = await exchanges.getById('binance');
+     * console.log(binance.trust_score); // 10
+     * ```
+     */
+    getById(id: string): Promise<ExchangeDetail>;
+    /**
+     * Returns paginated tickers for a specific exchange.
+     *
+     * @param id     - Exchange API ID (e.g. `"binance"`).
+     * @param params - Optional filter/sort/pagination parameters.
+     * @returns {@link ExchangeTickersResponse} containing the exchange name and
+     *   an array of tickers.
+     *
+     * @example
+     * ```ts
+     * const result = await exchanges.tickers('binance', {
+     *   coin_ids: 'bitcoin,ethereum',
+     *   order: 'trust_score_desc',
+     * });
+     * console.log(result.tickers.length);
+     * ```
+     */
+    tickers(id: string, params?: ExchangeTickersParams): Promise<ExchangeTickersResponse>;
+    /**
+     * Returns BTC-denominated volume chart data for a specific exchange.
+     *
+     * @param id     - Exchange API ID (e.g. `"binance"`).
+     * @param params - Required query parameters, including `days`.
+     * @returns {@link VolumeChartResponse} — array of `[timestamp_ms, volume_btc]`
+     *   tuples. Volume is returned as a string to preserve precision.
+     *
+     * @example
+     * ```ts
+     * const chart = await exchanges.volumeChart('binance', { days: '30' });
+     * // [[1711792200000, '306800.051794'], ...]
+     * ```
+     */
+    volumeChart(id: string, params: VolumeChartParams): Promise<VolumeChartResponse>;
+    /**
+     * Returns BTC-denominated volume chart data for an exchange over a custom
+     * Unix timestamp range.
+     *
+     * @param id     - Exchange API ID (e.g. `"binance"`).
+     * @param params - Required `from` and `to` Unix timestamps (seconds).
+     * @returns {@link VolumeChartResponse} — array of `[timestamp_ms, volume_btc]`
+     *   tuples.
+     *
+     * @remarks Requires **Analyst+** plan.
+     *
+     * @example
+     * ```ts
+     * const chart = await exchanges.volumeChartRange('binance', {
+     *   from: 1711670400,
+     *   to:   1712275200,
+     * });
+     * ```
+     */
+    volumeChartRange(id: string, params: VolumeChartRangeParams): Promise<VolumeChartResponse>;
+}
+
+/**
+ * @module endpoints/derivatives
+ * Endpoint methods for CoinGecko derivatives-related API paths.
+ *
+ * Covers: /derivatives, /derivatives/exchanges,
+ * /derivatives/exchanges/{id}, /derivatives/exchanges/list.
+ */
+
+/**
+ * Endpoint group for CoinGecko derivatives APIs.
+ *
+ * Obtain an instance via the SDK's top-level entry point; do not
+ * instantiate directly.
+ *
+ * @example
+ * ```ts
+ * const deriv = new DerivativesEndpoints(client);
+ * const tickers = await deriv.tickers();
+ * ```
+ */
+declare class DerivativesEndpoints {
+    private readonly client;
+    constructor(client: CoinGeckoClient);
+    /**
+     * Returns a list of all derivative tickers across all derivatives exchanges.
+     *
+     * @param params - Optional filter parameters.
+     * @param params.include_tickers - Whether to include tickers.
+     *   `"all"` returns all tickers; `"unexpired"` excludes expired contracts.
+     * @returns Array of {@link DerivativeTicker} objects.
+     *
+     * @example
+     * ```ts
+     * const allTickers = await deriv.tickers({ include_tickers: 'unexpired' });
+     * ```
+     */
+    tickers(params?: {
+        include_tickers?: 'all' | 'unexpired';
+    }): Promise<DerivativeTicker[]>;
+    /**
+     * Returns a paginated list of all derivatives exchanges.
+     *
+     * @param params - Optional sort and pagination parameters.
+     * @returns Array of {@link DerivativeExchange} objects.
+     *
+     * @example
+     * ```ts
+     * const top = await deriv.exchanges({
+     *   order: 'open_interest_btc_desc',
+     *   per_page: 10,
+     * });
+     * ```
+     */
+    exchanges(params?: DerivativesExchangesParams): Promise<DerivativeExchange[]>;
+    /**
+     * Returns detailed data for a single derivatives exchange by its API ID.
+     *
+     * @param id     - Derivatives exchange API ID (e.g. `"binance_futures"`).
+     * @param params - Optional parameters to include ticker data.
+     * @returns {@link DerivativeExchangeDetail} with optional tickers array.
+     *
+     * @example
+     * ```ts
+     * const detail = await deriv.exchangeById('binance_futures', {
+     *   include_tickers: 'unexpired',
+     * });
+     * console.log(detail.open_interest_btc);
+     * ```
+     */
+    exchangeById(id: string, params?: DerivativesExchangeByIdParams): Promise<DerivativeExchangeDetail>;
+    /**
+     * Returns a lightweight list of all derivatives exchange IDs and names.
+     *
+     * Use this to resolve exchange API IDs for subsequent calls.
+     *
+     * @returns Array of {@link ExchangeListEntry} objects (`id` + `name` only).
+     *
+     * @example
+     * ```ts
+     * const ids = await deriv.exchangesList();
+     * // [{ id: 'binance_futures', name: 'Binance (Futures)' }, ...]
+     * ```
+     */
+    exchangesList(): Promise<ExchangeListEntry[]>;
+}
+
+/**
+ * @module endpoints/nfts
+ * Endpoint methods for CoinGecko NFT-related API paths.
+ *
+ * Covers: /nfts/list, /nfts/{id}, /nfts/{platformId}/contract/{address},
+ * /nfts/markets (Analyst+), /nfts/{id}/market_chart (Analyst+),
+ * /nfts/{platformId}/contract/{address}/market_chart (Analyst+),
+ * /nfts/{id}/tickers (Analyst+).
+ */
+
+/**
+ * Endpoint group for CoinGecko NFT APIs.
+ *
+ * Obtain an instance via the SDK's top-level entry point; do not
+ * instantiate directly.
+ *
+ * @example
+ * ```ts
+ * const nfts = new NftsEndpoints(client);
+ * const listing = await nfts.list();
+ * ```
+ */
+declare class NftsEndpoints {
+    private readonly client;
+    constructor(client: CoinGeckoClient);
+    /**
+     * Returns a paginated list of all NFT collections supported by CoinGecko.
+     *
+     * @param params - Optional pagination parameters (`per_page`, `page`).
+     * @returns Array of {@link NftListEntry} objects with minimal metadata.
+     *
+     * @example
+     * ```ts
+     * const collections = await nfts.list({ per_page: 100, page: 1 });
+     * ```
+     */
+    list(params?: {
+        per_page?: number;
+        page?: number;
+    }): Promise<NftListEntry[]>;
+    /**
+     * Returns full data for a single NFT collection by its CoinGecko API ID.
+     *
+     * @param id - NFT collection API ID (e.g. `"pudgy-penguins"`). Use
+     *   {@link list} to discover valid IDs.
+     * @returns {@link NftCollection} with floor price, market cap, volume, and
+     *   other collection metadata.
+     *
+     * @example
+     * ```ts
+     * const penguins = await nfts.getById('pudgy-penguins');
+     * console.log(penguins.floor_price?.usd);
+     * ```
+     */
+    getById(id: string): Promise<NftCollection>;
+    /**
+     * Returns full data for a single NFT collection identified by its contract
+     * address on a specific asset platform.
+     *
+     * @param platformId - Asset platform ID (e.g. `"ethereum"`).
+     * @param address    - Token contract address (e.g. `"0xBd3531..."`).
+     * @returns {@link NftCollection} with the same fields as {@link getById}.
+     *
+     * @example
+     * ```ts
+     * const collection = await nfts.getByContract(
+     *   'ethereum',
+     *   '0xBd3531dA5CF5857e7CfAA92426877b022e612cf8',
+     * );
+     * ```
+     */
+    getByContract(platformId: string, address: string): Promise<NftCollection>;
+    /**
+     * Returns a paginated list of NFT collections with market data.
+     *
+     * @param params - Optional filter and sort parameters.
+     * @returns Array of {@link NftCollection} objects with market data.
+     *
+     * @remarks Requires **Analyst+** plan.
+     *
+     * @example
+     * ```ts
+     * const markets = await nfts.markets({
+     *   asset_platform_id: 'ethereum',
+     *   order: 'market_cap_usd_desc',
+     *   per_page: 50,
+     * });
+     * ```
+     */
+    markets(params?: NftMarketsParams): Promise<NftCollection[]>;
+    /**
+     * Returns historical market chart data for a single NFT collection.
+     *
+     * @param id     - NFT collection API ID (e.g. `"pudgy-penguins"`).
+     * @param params - Optional query parameters, including `days`.
+     * @returns {@link NftMarketChart} with floor price, market cap, and volume
+     *   time series.
+     *
+     * @remarks Requires **Analyst+** plan.
+     *
+     * @example
+     * ```ts
+     * const chart = await nfts.marketChart('pudgy-penguins', { days: 30 });
+     * console.log(chart.floor_price_usd);
+     * ```
+     */
+    marketChart(id: string, params?: NftMarketChartParams): Promise<NftMarketChart>;
+    /**
+     * Returns historical market chart data for an NFT collection identified by
+     * its contract address on a specific asset platform.
+     *
+     * @param platformId - Asset platform ID (e.g. `"ethereum"`).
+     * @param address    - Token contract address.
+     * @param params     - Optional query parameters, including `days`.
+     * @returns {@link NftMarketChart} with floor price, market cap, and volume
+     *   time series.
+     *
+     * @remarks Requires **Analyst+** plan.
+     *
+     * @example
+     * ```ts
+     * const chart = await nfts.contractMarketChart(
+     *   'ethereum',
+     *   '0xBd3531dA5CF5857e7CfAA92426877b022e612cf8',
+     *   { days: 14 },
+     * );
+     * ```
+     */
+    contractMarketChart(platformId: string, address: string, params?: NftMarketChartParams): Promise<NftMarketChart>;
+    /**
+     * Returns marketplace tickers (floor price, volume) for a single NFT
+     * collection across all supported NFT marketplaces.
+     *
+     * @param id - NFT collection API ID (e.g. `"pudgy-penguins"`).
+     * @returns {@link NftTickersResponse} with an array of marketplace tickers.
+     *
+     * @remarks Requires **Analyst+** plan.
+     *
+     * @example
+     * ```ts
+     * const result = await nfts.tickers('pudgy-penguins');
+     * result.tickers.forEach(t => console.log(t.name, t.floor_price_in_native_currency));
+     * ```
+     */
+    tickers(id: string): Promise<NftTickersResponse>;
+}
+
+/**
+ * @module endpoints/onchain
+ * OnchainEndpoints class covering all GeckoTerminal / on-chain DEX endpoints
+ * exposed under the `/onchain` path prefix.
+ *
+ * All methods delegate to {@link CoinGeckoClient.get} and return typed
+ * JSON:API response objects defined in `src/types/onchain.ts`.
+ */
+
+/**
+ * Response from the simple token price endpoint.
+ * Maps each token address to a map of currency → price value (string).
+ */
+type SimpleTokenPriceResponse = Record<string, Record<string, string>>;
+/**
+ * Query parameters for `/onchain/search/pools`.
+ */
+interface SearchPoolsParams extends PaginationParams {
+    /** Optional network ID to narrow the search (e.g. `"eth"`). */
+    network?: string;
+}
+/**
+ * Response type for the pool info endpoint.
+ */
+type PoolInfoResponse = JsonApiSingleResponse<PoolAttributes>;
+/**
+ * Provides typed access to all GeckoTerminal / on-chain DEX endpoints
+ * under the `/onchain` prefix.
+ *
+ * Instantiate indirectly through a higher-level SDK facade, or directly:
+ *
+ * @example
+ * ```ts
+ * import { CoinGeckoClient } from '../client.js';
+ * import { OnchainEndpoints } from './onchain.js';
+ *
+ * const client = new CoinGeckoClient({ apiKey: process.env.CG_KEY });
+ * const onchain = new OnchainEndpoints(client);
+ *
+ * const { data } = await onchain.networks();
+ * console.log(data.map(n => n.attributes.name));
+ * ```
+ */
+declare class OnchainEndpoints {
+    private readonly client;
+    constructor(client: CoinGeckoClient);
+    /**
+     * Returns the current USD (or other currency) price of one or more tokens
+     * on a given network.
+     *
+     * @param network   - Network ID (e.g. `"eth"`, `"bsc"`).
+     * @param addresses - Token contract address or array of addresses.
+     * @returns A map of address → { usd: "price" } (or whichever currencies were requested).
+     *
+     * @example
+     * ```ts
+     * const prices = await onchain.tokenPrice('eth', [
+     *   '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+     *   '0xdac17f958d2ee523a2206206994597c13d831ec7',
+     * ]);
+     * // { '0xa0b8...': { usd: '1.001' }, '0xdac1...': { usd: '0.9998' } }
+     * ```
+     */
+    tokenPrice(network: string, addresses: string | string[]): Promise<SimpleTokenPriceResponse>;
+    /**
+     * Returns the list of all supported networks (blockchains) on GeckoTerminal.
+     *
+     * @param params - Optional pagination parameters.
+     * @returns Paginated list of network resources.
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.networks();
+     * data.forEach(n => console.log(n.id, n.attributes.name));
+     * ```
+     */
+    networks(params?: PaginationParams): Promise<NetworksListResponse>;
+    /**
+     * Returns the list of DEXes available on a given network.
+     *
+     * @param network - Network ID (e.g. `"eth"`).
+     * @param params  - Optional pagination parameters.
+     * @returns Paginated list of DEX resources.
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.dexes('eth');
+     * data.forEach(d => console.log(d.id, d.attributes.name));
+     * ```
+     */
+    dexes(network: string, params?: PaginationParams): Promise<DexListResponse>;
+    /**
+     * Returns detailed data for a single pool by contract address.
+     *
+     * @param network - Network ID (e.g. `"eth"`).
+     * @param address - Pool contract address.
+     * @returns Single pool resource (JSON:API envelope).
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.pool('eth', '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640');
+     * console.log(data.attributes.name, data.attributes.reserve_in_usd);
+     * ```
+     */
+    pool(network: string, address: string): Promise<PoolDetail>;
+    /**
+     * Returns data for multiple pools by contract addresses in one request.
+     *
+     * @param network   - Network ID (e.g. `"eth"`).
+     * @param addresses - Array of pool contract addresses (joined as comma-separated path segment).
+     * @returns List of pool resources (JSON:API envelope).
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.pools('eth', [
+     *   '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
+     *   '0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8',
+     * ]);
+     * ```
+     */
+    pools(network: string, addresses: string[]): Promise<PoolInfo>;
+    /**
+     * Returns the top pools on a given network ranked by volume or liquidity.
+     *
+     * @param network - Network ID (e.g. `"eth"`).
+     * @param params  - Optional pagination parameters.
+     * @returns Paginated list of pool resources.
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.topPools('eth', { page: 1 });
+     * ```
+     */
+    topPools(network: string, params?: PaginationParams): Promise<JsonApiListResponse<PoolAttributes>>;
+    /**
+     * Returns the top pools for a specific DEX on a given network.
+     *
+     * @param network - Network ID (e.g. `"eth"`).
+     * @param dex     - DEX ID (e.g. `"uniswap_v3"`).
+     * @param params  - Optional pagination parameters.
+     * @returns Paginated list of pool resources.
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.topPoolsByDex('eth', 'uniswap_v3');
+     * ```
+     */
+    topPoolsByDex(network: string, dex: string, params?: PaginationParams): Promise<JsonApiListResponse<PoolAttributes>>;
+    /**
+     * Returns trending pools, either globally or filtered to a specific network.
+     *
+     * When `network` is omitted, the global trending pools endpoint is used:
+     * `GET /onchain/networks/trending_pools`.
+     * When `network` is provided: `GET /onchain/networks/{network}/trending_pools`.
+     *
+     * @param network - Optional network ID to scope results.
+     * @param params  - Optional pagination parameters.
+     * @returns Paginated list of trending pool resources.
+     *
+     * @example
+     * ```ts
+     * // Global trending
+     * const { data } = await onchain.trendingPools();
+     *
+     * // Network-scoped trending
+     * const { data: ethTrending } = await onchain.trendingPools('eth');
+     * ```
+     */
+    trendingPools(network?: string, params?: PaginationParams): Promise<JsonApiListResponse<PoolAttributes>>;
+    /**
+     * Returns newly created pools, either globally or filtered to a specific network.
+     *
+     * When `network` is omitted, the global new pools endpoint is used:
+     * `GET /onchain/networks/new_pools`.
+     * When `network` is provided: `GET /onchain/networks/{network}/new_pools`.
+     *
+     * @param network - Optional network ID to scope results.
+     * @param params  - Optional pagination parameters.
+     * @returns Paginated list of new pool resources.
+     *
+     * @example
+     * ```ts
+     * // All new pools across all networks
+     * const { data } = await onchain.newPools();
+     *
+     * // New pools on Solana only
+     * const { data: solNew } = await onchain.newPools('solana');
+     * ```
+     */
+    newPools(network?: string, params?: PaginationParams): Promise<JsonApiListResponse<PoolAttributes>>;
+    /**
+     * Returns pools matching advanced filter criteria (megafilter).
+     *
+     * @remarks
+     * **Requires Analyst+ (💼) plan.** Calls are rejected with HTTP 403 on
+     * lower-tier keys.
+     *
+     * @param params - Filter, sort, and pagination parameters.
+     * @returns Paginated list of pool resources matching the criteria.
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.megafilter({
+     *   network: 'eth',
+     *   reserve_in_usd_gte: 100_000,
+     *   sort: 'h24_volume_usd',
+     *   page: 1,
+     * });
+     * ```
+     */
+    megafilter(params: MegafilterParams): Promise<JsonApiListResponse<PoolAttributes>>;
+    /**
+     * Searches for pools matching a text query across all networks or a
+     * specific network.
+     *
+     * @param query  - Search query string (token name, symbol, or pool address).
+     * @param params - Optional network filter and pagination parameters.
+     * @returns Paginated list of matching pool resources.
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.searchPools('PEPE');
+     * const { data: ethPepe } = await onchain.searchPools('PEPE', { network: 'eth' });
+     * ```
+     */
+    searchPools(query: string, params?: SearchPoolsParams): Promise<JsonApiListResponse<PoolAttributes>>;
+    /**
+     * Returns pools that are currently trending in search on GeckoTerminal.
+     *
+     * @remarks
+     * **Requires Analyst+ (💼) plan.** Calls are rejected with HTTP 403 on
+     * lower-tier keys.
+     *
+     * @returns List of trending-search pool resources.
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.trendingSearchPools();
+     * ```
+     */
+    trendingSearchPools(): Promise<JsonApiListResponse<PoolAttributes>>;
+    /**
+     * Returns rich metadata / info for a single pool.
+     *
+     * @param network     - Network ID (e.g. `"eth"`).
+     * @param poolAddress - Pool contract address.
+     * @returns Single pool info resource (JSON:API envelope).
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.poolInfo('eth', '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640');
+     * ```
+     */
+    poolInfo(network: string, poolAddress: string): Promise<PoolInfoResponse>;
+    /**
+     * Returns OHLCV (candlestick) data for a pool.
+     *
+     * @param network     - Network ID (e.g. `"eth"`).
+     * @param poolAddress - Pool contract address.
+     * @param timeframe   - Candle timeframe: `"minute"`, `"hour"`, or `"day"`.
+     * @param params      - Optional OHLCV query parameters (aggregate, limit, etc.).
+     * @returns OHLCV response containing an array of candles and token metadata.
+     *
+     * @example
+     * ```ts
+     * const ohlcv = await onchain.poolOhlcv(
+     *   'eth',
+     *   '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
+     *   'hour',
+     *   { aggregate: '4', limit: 200 },
+     * );
+     * ohlcv.data?.attributes?.ohlcv_list?.forEach(([ts, o, h, l, c, v]) => {
+     *   console.log(new Date(ts * 1000).toISOString(), c);
+     * });
+     * ```
+     */
+    poolOhlcv(network: string, poolAddress: string, timeframe: string, params?: OhlcvParams): Promise<OhlcvResponse>;
+    /**
+     * Returns recent trades for a pool.
+     *
+     * @param network     - Network ID (e.g. `"eth"`).
+     * @param poolAddress - Pool contract address.
+     * @param params      - Optional query parameters (e.g. `trade_volume_in_usd_greater_than`).
+     * @returns Trades response containing an array of trade objects.
+     *
+     * @example
+     * ```ts
+     * const trades = await onchain.poolTrades(
+     *   'eth',
+     *   '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
+     * );
+     * ```
+     */
+    poolTrades(network: string, poolAddress: string, params?: Record<string, unknown>): Promise<TradesResponse>;
+    /**
+     * Returns price and market data for a single token by contract address.
+     *
+     * @param network - Network ID (e.g. `"eth"`).
+     * @param address - Token contract address.
+     * @returns Single token resource (JSON:API envelope).
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.token(
+     *   'eth',
+     *   '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+     * );
+     * console.log(data.attributes.symbol, data.attributes.price_usd);
+     * ```
+     */
+    token(network: string, address: string): Promise<TokenDetailResponse>;
+    /**
+     * Returns price and market data for multiple tokens in one request.
+     *
+     * @param network   - Network ID (e.g. `"eth"`).
+     * @param addresses - Array of token contract addresses (joined as comma-separated path segment).
+     * @returns List of token resources (JSON:API envelope).
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.tokens('eth', [
+     *   '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+     *   '0xdac17f958d2ee523a2206206994597c13d831ec7',
+     * ]);
+     * ```
+     */
+    tokens(network: string, addresses: string[]): Promise<JsonApiListResponse<TokenAttributes>>;
+    /**
+     * Returns rich metadata (socials, description, security flags) for a token.
+     *
+     * @param network - Network ID (e.g. `"eth"`).
+     * @param address - Token contract address.
+     * @returns Token info resource (JSON:API envelope).
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.tokenInfo(
+     *   'eth',
+     *   '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+     * );
+     * console.log(data.attributes.description, data.attributes.gt_score);
+     * ```
+     */
+    tokenInfo(network: string, address: string): Promise<TokenInfoResponse>;
+    /**
+     * Returns the list of pools that include a given token.
+     *
+     * @param network - Network ID (e.g. `"eth"`).
+     * @param address - Token contract address.
+     * @param params  - Optional pagination parameters.
+     * @returns Paginated list of pool resources containing the token.
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.tokenPools(
+     *   'eth',
+     *   '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+     * );
+     * ```
+     */
+    tokenPools(network: string, address: string, params?: PaginationParams): Promise<JsonApiListResponse<PoolAttributes>>;
+    /**
+     * Returns OHLCV (candlestick) data for a token.
+     *
+     * @remarks
+     * **Requires Analyst+ (💼) plan.** Calls are rejected with HTTP 403 on
+     * lower-tier keys.
+     *
+     * @param network   - Network ID (e.g. `"eth"`).
+     * @param address   - Token contract address.
+     * @param timeframe - Candle timeframe: `"minute"`, `"hour"`, or `"day"`.
+     * @param params    - Optional OHLCV query parameters (aggregate, limit, etc.).
+     * @returns OHLCV response containing an array of candles and token metadata.
+     *
+     * @example
+     * ```ts
+     * const ohlcv = await onchain.tokenOhlcv(
+     *   'eth',
+     *   '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+     *   'day',
+     *   { limit: 30 },
+     * );
+     * ```
+     */
+    tokenOhlcv(network: string, address: string, timeframe: string, params?: OhlcvParams): Promise<OhlcvResponse>;
+    /**
+     * Returns recent trades involving a specific token.
+     *
+     * @remarks
+     * **Requires Analyst+ (💼) plan.** Calls are rejected with HTTP 403 on
+     * lower-tier keys.
+     *
+     * @param network - Network ID (e.g. `"eth"`).
+     * @param address - Token contract address.
+     * @param params  - Optional query parameters.
+     * @returns Trades response containing recent trade objects for the token.
+     *
+     * @example
+     * ```ts
+     * const trades = await onchain.tokenTrades(
+     *   'eth',
+     *   '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+     * );
+     * ```
+     */
+    tokenTrades(network: string, address: string, params?: Record<string, unknown>): Promise<TradesResponse>;
+    /**
+     * Returns the top traders for a specific token over the last 24 hours.
+     *
+     * @remarks
+     * **Requires Analyst+ (💼) plan.** Calls are rejected with HTTP 403 on
+     * lower-tier keys.
+     *
+     * @param network - Network ID (e.g. `"eth"`).
+     * @param address - Token contract address.
+     * @returns List response containing top trader entries.
+     *
+     * @example
+     * ```ts
+     * const result = await onchain.topTraders(
+     *   'eth',
+     *   '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+     * );
+     * ```
+     */
+    topTraders(network: string, address: string): Promise<JsonApiListResponse<TopTrader>>;
+    /**
+     * Returns the top holders (largest wallets) for a specific token.
+     *
+     * @remarks
+     * **Requires Analyst+ (💼) plan.** Calls are rejected with HTTP 403 on
+     * lower-tier keys.
+     *
+     * @param network - Network ID (e.g. `"eth"`).
+     * @param address - Token contract address.
+     * @returns List response containing top holder entries.
+     *
+     * @example
+     * ```ts
+     * const result = await onchain.topHolders(
+     *   'eth',
+     *   '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+     * );
+     * ```
+     */
+    topHolders(network: string, address: string): Promise<JsonApiListResponse<TopHolder>>;
+    /**
+     * Returns a time-series chart of holder count for a specific token.
+     *
+     * @remarks
+     * **Requires Analyst+ (💼) plan.** Calls are rejected with HTTP 403 on
+     * lower-tier keys.
+     *
+     * @param network - Network ID (e.g. `"eth"`).
+     * @param address - Token contract address.
+     * @returns Holder chart response with an array of `[timestamp, count]` data points.
+     *
+     * @example
+     * ```ts
+     * const chart = await onchain.holdersChart(
+     *   'eth',
+     *   '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+     * );
+     * chart.data?.attributes?.holders_chart?.forEach(([ts, count]) => {
+     *   console.log(new Date(ts * 1000).toISOString(), count);
+     * });
+     * ```
+     */
+    holdersChart(network: string, address: string): Promise<HolderChartResponse>;
+    /**
+     * Returns a list of tokens whose info was recently updated on GeckoTerminal.
+     *
+     * Useful for syncing token metadata caches.
+     *
+     * @returns List of recently-updated token info resources (JSON:API).
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.recentlyUpdatedTokens();
+     * data.forEach(t => console.log(t.attributes.symbol, t.attributes.coingecko_coin_id));
+     * ```
+     */
+    recentlyUpdatedTokens(): Promise<JsonApiListResponse<TokenAttributes>>;
+    /**
+     * Returns the list of GeckoTerminal onchain categories.
+     *
+     * @remarks
+     * **Requires Analyst+ (💼) plan.** Calls are rejected with HTTP 403 on
+     * lower-tier keys.
+     *
+     * @returns Response containing an array of category objects.
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.categories();
+     * data.forEach(c => console.log(c.id, c.attributes?.name));
+     * ```
+     */
+    categories(): Promise<OnchainCategoriesResponse>;
+    /**
+     * Returns pools belonging to a specific GeckoTerminal onchain category.
+     *
+     * @remarks
+     * **Requires Analyst+ (💼) plan.** Calls are rejected with HTTP 403 on
+     * lower-tier keys.
+     *
+     * @param categoryId - Category ID (e.g. `"defi"`, `"meme"`).
+     * @param params     - Optional pagination parameters.
+     * @returns Paginated list of pool resources in the category.
+     *
+     * @example
+     * ```ts
+     * const { data } = await onchain.categoryPools('meme', { page: 1, per_page: 50 });
+     * data.forEach(p => console.log(p.attributes.name, p.attributes.volume_usd?.h24));
+     * ```
+     */
+    categoryPools(categoryId: string, params?: PaginationParams): Promise<JsonApiListResponse<PoolAttributes>>;
+}
+
+/**
+ * @module endpoints/global
+ * Endpoint methods for CoinGecko global market, search, trending,
+ * exchange rates, asset platforms, and token list API paths.
+ *
+ * Covers: /global, /global/decentralized_finance_defi,
+ * /global/market_cap_chart (Analyst+), /search, /search/trending,
+ * /exchange_rates, /asset_platforms, /token_lists/{platformId}/all.json.
+ */
+
+/**
+ * Endpoint group for CoinGecko global market, search, and utility APIs.
+ *
+ * Obtain an instance via the SDK's top-level entry point; do not
+ * instantiate directly.
+ *
+ * @example
+ * ```ts
+ * const global = new GlobalEndpoints(client);
+ * const data = await global.global();
+ * console.log(data.data.total_market_cap?.usd);
+ * ```
+ */
+declare class GlobalEndpoints {
+    private readonly client;
+    constructor(client: CoinGeckoClient);
+    /**
+     * Returns global cryptocurrency market data, including total market cap,
+     * volume, dominance, and number of active coins and exchanges.
+     *
+     * @returns {@link GlobalData} wrapping a {@link GlobalDataPayload}.
+     *
+     * @example
+     * ```ts
+     * const { data } = await global.global();
+     * console.log(data.market_cap_percentage?.btc); // BTC dominance %
+     * ```
+     */
+    global(): Promise<GlobalData>;
+    /**
+     * Returns global DeFi market data, including total DeFi market cap, ETH
+     * market cap, DeFi dominance, and trading volume.
+     *
+     * @returns {@link GlobalDefiData} wrapping a {@link GlobalDefiPayload}.
+     *
+     * @example
+     * ```ts
+     * const { data } = await global.globalDefi();
+     * console.log(data.defi_market_cap);
+     * ```
+     */
+    globalDefi(): Promise<GlobalDefiData>;
+    /**
+     * Returns historical global market cap and volume chart data.
+     *
+     * @param params - Required query parameters, including `days`.
+     * @returns {@link GlobalMarketCapChartResponse} with `market_cap` and
+     *   `volume` time series arrays.
+     *
+     * @remarks Requires **Analyst+** plan.
+     *
+     * @example
+     * ```ts
+     * const chart = await global.globalMarketCapChart({ days: 30 });
+     * console.log(chart.market_cap_chart.market_cap[0]); // [timestamp_ms, value]
+     * ```
+     */
+    globalMarketCapChart(params: GlobalMarketCapChartParams): Promise<GlobalMarketCapChartResponse>;
+    /**
+     * Searches for coins, exchanges, categories, and NFT collections by a
+     * free-text query string.
+     *
+     * @param query - Search term (e.g. `"bitcoin"`, `"uni"`).
+     * @returns {@link SearchResponse} with matched coins, exchanges, categories,
+     *   and NFTs.
+     *
+     * @example
+     * ```ts
+     * const results = await global.search('uniswap');
+     * results.coins.forEach(c => console.log(c.id, c.name));
+     * ```
+     */
+    search(query: string): Promise<SearchResponse>;
+    /**
+     * Returns the top trending coins, NFTs, and categories on CoinGecko in the
+     * last 24 hours, determined by search volume.
+     *
+     * @returns {@link TrendingResponse} with arrays of trending coins, NFTs, and
+     *   categories.
+     *
+     * @example
+     * ```ts
+     * const { coins } = await global.trending();
+     * coins.forEach(({ item }) => console.log(item.name));
+     * ```
+     */
+    trending(): Promise<TrendingResponse>;
+    /**
+     * Returns BTC exchange rates against fiat currencies, crypto assets, and
+     * commodities.
+     *
+     * @returns {@link ExchangeRatesResponse} mapping currency codes to rate data.
+     *
+     * @example
+     * ```ts
+     * const { rates } = await global.exchangeRates();
+     * console.log(rates['usd']?.value); // BTC price in USD
+     * ```
+     */
+    exchangeRates(): Promise<ExchangeRatesResponse>;
+    /**
+     * Returns a list of all asset platforms (blockchain networks) supported by
+     * CoinGecko.
+     *
+     * @param params - Optional filter parameters (e.g. `filter: 'nft'`).
+     * @returns Array of {@link AssetPlatform} objects.
+     *
+     * @example
+     * ```ts
+     * const platforms = await global.assetPlatforms({ filter: 'nft' });
+     * ```
+     */
+    assetPlatforms(params?: AssetPlatformsParams): Promise<AssetPlatform[]>;
+    /**
+     * Returns a Uniswap-compatible token list for all tokens on a given asset
+     * platform.
+     *
+     * @param platformId - Asset platform ID (e.g. `"ethereum"`).
+     * @returns Token list object in the standard Uniswap token list format.
+     *   The exact shape depends on the platform; typed as `unknown` for
+     *   flexibility.
+     *
+     * @example
+     * ```ts
+     * const list = await global.tokenLists('ethereum');
+     * ```
+     */
+    tokenLists(platformId: string): Promise<unknown>;
+}
+
+/**
+ * @module endpoints/treasury
+ * Endpoint methods for CoinGecko Public Treasury API paths.
+ *
+ * Covers: /entities/list, /companies/public_treasury/{coinId},
+ * /public_treasury/{entityId}, /public_treasury/{entityId}/{coinId}/holding_chart,
+ * /public_treasury/{entityId}/transaction_history.
+ */
+
+/**
+ * Endpoint group for CoinGecko Public Treasury APIs.
+ *
+ * Obtain an instance via the SDK's top-level entry point; do not
+ * instantiate directly.
+ *
+ * @example
+ * ```ts
+ * const treasury = new TreasuryEndpoints(client);
+ * const entities = await treasury.entitiesList();
+ * ```
+ */
+declare class TreasuryEndpoints {
+    private readonly client;
+    constructor(client: CoinGeckoClient);
+    /**
+     * Returns a list of all public entities (companies and governments) tracked
+     * in CoinGecko's public treasury database.
+     *
+     * @returns Array of {@link Entity} objects with `id`, `name`, `symbol`, and
+     *   `country`.
+     *
+     * @example
+     * ```ts
+     * const entities = await treasury.entitiesList();
+     * entities.forEach(e => console.log(e.id, e.name));
+     * ```
+     */
+    entitiesList(): Promise<Entity[]>;
+    /**
+     * Returns public company Bitcoin or Ethereum treasury holdings, including
+     * aggregate totals and per-company breakdowns.
+     *
+     * @param coinId - Coin API ID to query holdings for.
+     *   Currently supported values: `"bitcoin"`, `"ethereum"`.
+     * @returns {@link CompanyTreasuryResponse} with aggregate totals and a
+     *   `companies` array.
+     *
+     * @example
+     * ```ts
+     * const holdings = await treasury.companyHoldings('bitcoin');
+     * console.log(holdings.total_holdings);
+     * holdings.companies.forEach(c => console.log(c.name, c.total_holdings));
+     * ```
+     */
+    companyHoldings(coinId: string): Promise<CompanyTreasuryResponse>;
+    /**
+     * Returns the full treasury profile for a single public entity, including
+     * all cryptocurrency holdings and financial metrics.
+     *
+     * @param entityId - Entity API ID (e.g. `"strategy"`, `"tesla"`). Use
+     *   {@link entitiesList} to discover valid IDs.
+     * @returns {@link PublicTreasuryEntity} with holdings, valuation, and PnL.
+     *
+     * @example
+     * ```ts
+     * const profile = await treasury.entityHoldings('strategy');
+     * console.log(profile.total_treasury_value_usd);
+     * profile.holdings?.forEach(h => console.log(h.coin_id, h.amount));
+     * ```
+     */
+    entityHoldings(entityId: string): Promise<PublicTreasuryEntity>;
+    /**
+     * Returns historical holding amount and USD value chart data for a specific
+     * coin in an entity's treasury.
+     *
+     * @param entityId - Entity API ID (e.g. `"strategy"`).
+     * @param coinId   - Coin API ID (e.g. `"bitcoin"`).
+     * @param params   - Required query parameters, including `days`.
+     * @returns {@link TreasuryHoldingChartResponse} with `holdings` and
+     *   `holding_value_in_usd` time series.
+     *
+     * @example
+     * ```ts
+     * const chart = await treasury.entityHoldingChart('strategy', 'bitcoin', {
+     *   days: '365',
+     * });
+     * chart.holdings?.forEach(([ts, amount]) => console.log(ts, amount));
+     * ```
+     */
+    entityHoldingChart(entityId: string, coinId: string, params: TreasuryHoldingChartParams): Promise<TreasuryHoldingChartResponse>;
+    /**
+     * Returns the paginated transaction history for a public treasury entity,
+     * including buy/sell events with price and value data.
+     *
+     * @param entityId - Entity API ID (e.g. `"strategy"`).
+     * @param params   - Optional pagination and coin filter parameters.
+     * @returns {@link TreasuryTransactionHistoryResponse} with a `data` array of
+     *   {@link TreasuryTransaction} records.
+     *
+     * @example
+     * ```ts
+     * const history = await treasury.entityTransactions('strategy', {
+     *   coin_ids: 'bitcoin',
+     *   per_page: 50,
+     * });
+     * history.data?.forEach(tx => console.log(tx.date, tx.transaction_type, tx.amount));
+     * ```
+     */
+    entityTransactions(entityId: string, params?: TreasuryTransactionHistoryParams): Promise<TreasuryTransactionHistoryResponse>;
+}
+
+/**
+ * @module errors
+ * Custom error types for the CoinGecko SDK.
+ */
+/**
+ * Thrown whenever the CoinGecko API returns a non-2xx HTTP status code, or
+ * when a network-level failure occurs during a request.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.get('/coins/does-not-exist');
+ * } catch (err) {
+ *   if (err instanceof CoinGeckoError) {
+ *     console.error(err.status, err.url, err.data);
+ *   }
+ * }
+ * ```
+ */
+declare class CoinGeckoError extends Error {
+    /**
+     * The HTTP status code returned by the API, or `0` for network-level
+     * failures (e.g. timeout, DNS error).
+     */
+    readonly status: number;
+    /**
+     * The full URL that was requested when the error occurred.
+     */
+    readonly url: string;
+    /**
+     * The response body parsed as JSON if possible, otherwise the raw text.
+     * `undefined` when the error is network-level and no response was received.
+     */
+    readonly data: unknown;
+    /**
+     * @param message - Human-readable error description.
+     * @param status  - HTTP status code (use `0` for network errors).
+     * @param url     - URL that triggered the error.
+     * @param data    - Parsed response body, if available.
+     */
+    constructor(message: string, status: number, url: string, data?: unknown);
+}
+
+/**
+ * @module endpoints/meta
+ * Endpoint methods for CoinGecko API meta and connectivity checks.
+ *
+ * Covers: /ping, /key (Analyst+).
+ */
+
+/**
+ * Endpoint group for CoinGecko meta/utility APIs.
+ *
+ * Obtain an instance via the SDK's top-level entry point; do not
+ * instantiate directly.
+ *
+ * @example
+ * ```ts
+ * const meta = new MetaEndpoints(client);
+ * const status = await meta.ping();
+ * console.log(status.gecko_says);
+ * ```
+ */
+declare class MetaEndpoints {
+    private readonly client;
+    constructor(client: CoinGeckoClient);
+    /**
+     * Checks the API server status. Use this as a lightweight connectivity test
+     * before making heavier requests.
+     *
+     * @returns {@link PingResponse} containing a `gecko_says` status string
+     *   (e.g. `"(V3) To the Moon!"`).
+     *
+     * @example
+     * ```ts
+     * const { gecko_says } = await meta.ping();
+     * console.log(gecko_says); // "(V3) To the Moon!"
+     * ```
+     */
+    ping(): Promise<PingResponse>;
+    /**
+     * Returns usage statistics and plan information for the current Pro API key.
+     *
+     * @returns {@link ApiUsageResponse} with plan name, rate limit, monthly
+     *   credit usage, and remaining credits.
+     *
+     * @remarks Requires a valid **Pro API key** (Analyst+ plan). Returns 401 for
+     *   free-tier or unauthenticated requests.
+     *
+     * @example
+     * ```ts
+     * const usage = await meta.apiUsage();
+     * console.log(usage.plan);                             // "Analyst"
+     * console.log(usage.current_remaining_monthly_calls); // remaining credits
+     * ```
+     */
+    apiUsage(): Promise<ApiUsageResponse>;
+}
+
+/**
+ * Main entry point for the CoinGecko Pro SDK.
+ *
+ * Instantiate once and access every API group through its dedicated namespace.
+ * The underlying HTTP client handles caching, rate limiting, retries, and
+ * timeout management automatically.
+ *
+ * @example
+ * ```typescript
+ * import { CoinGecko } from 'coingecko-pro';
+ *
+ * // Pro tier (higher rate limits, Pro-only endpoints)
+ * const cg = new CoinGecko({ apiKey: 'CG-xxx' });
+ *
+ * // Free tier
+ * const cg = new CoinGecko();
+ *
+ * // With full configuration
+ * const cg = new CoinGecko({
+ *   apiKey: process.env.CG_API_KEY,
+ *   cacheTtl: 60_000,
+ *   maxRetries: 5,
+ *   rateLimit: 500,
+ *   timeout: 30_000,
+ *   onError: (url, err) => console.error(`[CoinGecko] ${url}`, err.message),
+ * });
+ * ```
+ */
+declare class CoinGecko {
+    /** Coin prices, market data, charts, OHLC, supply, categories, and contract lookups. */
+    readonly coins: CoinsEndpoints;
+    /** Exchange listings, details, tickers, and volume charts. */
+    readonly exchanges: ExchangesEndpoints;
+    /** Derivatives tickers and exchange data. */
+    readonly derivatives: DerivativesEndpoints;
+    /** NFT collections, market data, charts, and tickers. */
+    readonly nfts: NftsEndpoints;
+    /** On-chain DEX data (GeckoTerminal): pools, tokens, trades, OHLCV, top traders/holders. */
+    readonly onchain: OnchainEndpoints;
+    /** Global market data, search, trending, exchange rates, and asset platforms. */
+    readonly global: GlobalEndpoints;
+    /** Public treasury holdings, charts, and transaction history. */
+    readonly treasury: TreasuryEndpoints;
+    private readonly meta;
+    /**
+     * Creates a new CoinGecko SDK instance.
+     *
+     * @param config - Optional configuration for the underlying HTTP client.
+     *   See {@link CoinGeckoClientConfig} for all available options.
+     */
+    constructor(config?: CoinGeckoClientConfig);
+    /**
+     * Checks the CoinGecko API server status.
+     *
+     * Use this as a lightweight connectivity and authentication test.
+     *
+     * @returns Object containing the server status message
+     *   (`{ gecko_says: "(V3) To the Moon!" }`).
+     *
+     * @example
+     * ```typescript
+     * const { gecko_says } = await cg.ping();
+     * console.log(gecko_says); // "(V3) To the Moon!"
+     * ```
+     */
+    ping(): Promise<PingResponse>;
+    /**
+     * Returns API key usage statistics and plan information.
+     *
+     * @remarks Requires a valid **Pro API key** (Analyst+ plan). Returns 401 on
+     *   free-tier or unauthenticated requests.
+     *
+     * @returns Usage data including plan name, rate limits, and remaining credits.
+     *
+     * @example
+     * ```typescript
+     * const usage = await cg.apiUsage();
+     * console.log(usage.plan, usage.current_remaining_monthly_calls);
+     * ```
+     */
+    apiUsage(): Promise<ApiUsageResponse>;
+}
+
+export { type ApiUsageResponse, type AssetPlatform, type AssetPlatformsParams, type CategoriesParams, type Category, type CategoryDetail, type CategoryListEntry, type CoinCommunityData, type CoinDetail, type CoinDetailParams, type CoinDeveloperData, CoinGecko, CoinGeckoClient, type CoinGeckoClientConfig, CoinGeckoError, type CoinHistoricalData, type CoinHistoryParams, type CoinLinks, type CoinListEntry, type CoinMarketData, type CoinTicker, type CoinTickerParams, type CoinTickersResponse, CoinsEndpoints, type CoinsListParams, type CoinsMarketOrder, type CoinsMarketsParams, type CompanyTreasuryResponse, type CurrencyDateMap, type CurrencyMap, type DEX, type DerivativeExchange, type DerivativeExchangeDetail, type DerivativeTicker, DerivativesEndpoints, type DerivativesExchangeByIdParams, type DerivativesExchangeOrder, type DerivativesExchangesParams, type DexAttributes, type DexListResponse, type Entity, type EntityHolding, type Exchange, type ExchangeDetail, type ExchangeListEntry, type ExchangeRate, type ExchangeRateEntry, type ExchangeRatesResponse, type ExchangeTicker, type ExchangeTickerOrder, type ExchangeTickersParams, type ExchangeTickersResponse, ExchangesEndpoints, type GlobalData, type GlobalDataPayload, type GlobalDefiData, type GlobalDefiPayload, GlobalEndpoints, type GlobalMarketCapChartParams, type GlobalMarketCapChartResponse, type GovernmentTreasuryResponse, type GtScoreDetails, type HolderChartPoint, type HolderChartResponse, type HolderDistribution, type HoldingChartPoint, type HoldingTimeframeChange, type IdNamePair, type ImageUrls, type JsonApiListResponse, type JsonApiResource, type JsonApiSingleResponse, type Locale, type MarketChartParams, type MarketChartRangeParams, type MarketChartResponse, type MarketCoin, type MarketDataPoint, type MegafilterParams, MetaEndpoints, type Network, type NetworkAttributes, type NetworksListResponse, type NewCoin, type NftCollection, type NftDualValue, type NftExplorerLink, type NftLinks, type NftListEntry, type NftMarketChart, type NftMarketChartParams, type NftMarketsParams, type NftTicker, type NftTickersResponse, NftsEndpoints, type OHLCV, type OhlcDataPoint, type OhlcParams, type OhlcRangeParams, type OhlcvParams, type OhlcvResponse, type OhlcvTokenMeta, type OnchainCategoriesResponse, type OnchainCategory, OnchainEndpoints, type PaginationParams, type PingResponse, type PlatformDetail, type Pool, type PoolAttributes, type PoolDetail, type PoolInfo, type PoolTimeframeStringMap, type PoolTransactionWindow, type PoolTransactions, type PublicTreasuryEntity, type RoiData, type SearchCategory, type SearchCoin, type SearchExchange, type SearchNft, type SearchResponse, type SimplePriceParams, type SimplePriceResponse, type SimpleTokenPriceParams, type SupplyChartParams, type SupplyChartRangeParams, type SupplyChartResponse, type TickerMarket, type TickerOrder, type TokenAttributes, type TokenDetail, type TokenDetailResponse, type TokenHolders, type TokenInfo, type TokenInfoAttributes, type TokenInfoResponse, type TopGainersLosersParams, type TopHolder, type TopMoverCoin, type TopMoversResponse, type TopTrader, type Trade, type TradesResponse, TreasuryEndpoints, type TreasuryHolding, type TreasuryHoldingChartParams, type TreasuryHoldingChartResponse, type TreasuryTransaction, type TreasuryTransactionHistoryParams, type TreasuryTransactionHistoryResponse, type TrendingCategory, type TrendingCoin, type TrendingNft, type TrendingResponse, type VolumeChartParams, type VolumeChartPoint, type VolumeChartRangeParams, type VolumeChartResponse, type VsCurrency };