@jackwener/opencli 1.7.12 → 1.7.14

package/clis/coingecko/categories.js

@@ -0,0 +1,75 @@
+// coingecko categories — top crypto categories by aggregated market cap.
+//
+// Hits the public `/api/v3/coins/categories` endpoint. Useful for spotting
+// which sectors (DeFi, L1, gaming, RWAs, …) are leading the market.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const ORDER_OPTIONS = ['market_cap_desc', 'market_cap_asc', 'name_desc', 'name_asc', 'market_cap_change_24h_desc', 'market_cap_change_24h_asc'];
+
+cli({
+    site: 'coingecko',
+    name: 'categories',
+    access: 'read',
+    description: 'Crypto categories ranked by aggregated market cap',
+    domain: 'api.coingecko.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'sort', default: 'market_cap_desc', help: `Sort order (${ORDER_OPTIONS.join(' / ')})` },
+        { name: 'limit', type: 'int', default: 20, help: 'Number of categories (1-100; CoinGecko returns ~120 max)' },
+    ],
+    columns: ['rank', 'id', 'name', 'marketCap', 'volume24h', 'marketCapChange24hPct', 'top3Coins'],
+    func: async (args) => {
+        const sort = String(args.sort ?? 'market_cap_desc').trim().toLowerCase();
+        if (!ORDER_OPTIONS.includes(sort)) {
+            throw new ArgumentError(
+                `coingecko sort "${args.sort}" is not supported`,
+                `Supported sorts: ${ORDER_OPTIONS.join(', ')}`,
+            );
+        }
+        const limit = Number(args.limit ?? 20);
+        if (!Number.isInteger(limit) || limit <= 0) {
+            throw new ArgumentError('coingecko limit must be a positive integer');
+        }
+        if (limit > 100) {
+            throw new ArgumentError('coingecko limit must be <= 100');
+        }
+        const url = `https://api.coingecko.com/api/v3/coins/categories?order=${encodeURIComponent(sort)}`;
+        let resp;
+        try {
+            resp = await fetch(url, { headers: { 'User-Agent': 'Mozilla/5.0' } });
+        }
+        catch (err) {
+            throw new CommandExecutionError(`coingecko categories request failed: ${err?.message ?? err}`);
+        }
+        if (resp.status === 429) {
+            throw new CommandExecutionError(
+                'coingecko returned HTTP 429 (rate limited)',
+                'Free tier allows ~30 calls/min. Wait and retry.',
+            );
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`coingecko categories returned HTTP ${resp.status}`);
+        }
+        let data;
+        try {
+            data = await resp.json();
+        }
+        catch (err) {
+            throw new CommandExecutionError(`coingecko categories returned malformed JSON: ${err?.message ?? err}`);
+        }
+        if (!Array.isArray(data) || !data.length) {
+            throw new EmptyResultError('coingecko categories', 'CoinGecko returned no category data.');
+        }
+        return data.slice(0, limit).map((cat, i) => ({
+            rank: i + 1,
+            id: String(cat.id ?? ''),
+            name: String(cat.name ?? ''),
+            marketCap: cat.market_cap != null ? Number(cat.market_cap) : null,
+            volume24h: cat.volume_24h != null ? Number(cat.volume_24h) : null,
+            marketCapChange24hPct: cat.market_cap_change_24h != null ? Number(cat.market_cap_change_24h) : null,
+            top3Coins: Array.isArray(cat.top_3_coins_id) ? cat.top_3_coins_id.join(', ') : '',
+        }));
+    },
+});

package/clis/coingecko/coin.js

@@ -0,0 +1,107 @@
+// coingecko coin — fetch a single cryptocurrency's market detail by id.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    ArgumentError,
+    CommandExecutionError,
+    EmptyResultError,
+} from '@jackwener/opencli/errors';
+
+cli({
+    site: 'coingecko',
+    name: 'coin',
+    access: 'read',
+    description: 'Fetch a single cryptocurrency\'s market data by CoinGecko id (e.g. bitcoin, ethereum).',
+    domain: 'api.coingecko.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', positional: true, required: true, type: 'string', help: 'CoinGecko coin id (lowercase, e.g. bitcoin / ethereum / solana).' },
+        { name: 'currency', type: 'string', default: 'usd', help: 'Quote currency (usd, cny, eur, jpy, ...).' },
+    ],
+    columns: [
+        'id', 'symbol', 'name', 'rank', 'price', 'marketCap', 'volume24h',
+        'change24hPct', 'change7dPct', 'change30dPct', 'ath', 'athDate', 'atl', 'atlDate',
+        'circulatingSupply', 'totalSupply', 'maxSupply', 'genesisDate', 'homepage',
+    ],
+    func: async (args) => {
+        const id = String(args.id ?? '').trim().toLowerCase();
+        if (!id) {
+            throw new ArgumentError('coingecko coin id cannot be empty', 'Example: opencli coingecko coin bitcoin');
+        }
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) {
+            throw new ArgumentError(`coingecko coin id must look like a CoinGecko slug (got "${args.id}")`);
+        }
+        const currency = String(args.currency ?? 'usd').trim().toLowerCase();
+        if (!/^[a-z0-9-]{2,20}$/.test(currency)) {
+            throw new ArgumentError(`coingecko currency must look like a currency slug (got "${args.currency}")`);
+        }
+
+        const url = new URL(`https://api.coingecko.com/api/v3/coins/${id}`);
+        url.searchParams.set('localization', 'false');
+        url.searchParams.set('tickers', 'false');
+        url.searchParams.set('market_data', 'true');
+        url.searchParams.set('community_data', 'false');
+        url.searchParams.set('developer_data', 'false');
+        url.searchParams.set('sparkline', 'false');
+
+        let resp;
+        try {
+            resp = await fetch(url, { headers: { 'User-Agent': 'Mozilla/5.0' } });
+        } catch (error) {
+            throw new CommandExecutionError(`coingecko coin request failed: ${error?.message || error}`);
+        }
+        if (resp.status === 404) {
+            throw new EmptyResultError('coingecko coin', `coingecko has no coin with id "${id}".`);
+        }
+        if (resp.status === 429) {
+            throw new CommandExecutionError('coingecko returned HTTP 429 (rate limited)', 'Free tier allows ~30 calls/min. Wait and retry.');
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`coingecko coin failed: HTTP ${resp.status}`);
+        }
+        let data;
+        try {
+            data = await resp.json();
+        } catch (error) {
+            throw new CommandExecutionError(`coingecko returned malformed JSON: ${error?.message || error}`);
+        }
+        if (data?.error) {
+            throw new CommandExecutionError(`coingecko returned error: ${data.error}`);
+        }
+
+        const md = data.market_data || {};
+        const pick = (obj, key) => (obj && obj[key] != null ? obj[key] : null);
+        const isoFromMaybe = (s) => (s ? String(s).slice(0, 10) : '');
+        const price = pick(md.current_price, currency);
+        const marketCap = pick(md.market_cap, currency);
+        const volume24h = pick(md.total_volume, currency);
+        if (price == null && marketCap == null && volume24h == null) {
+            throw new CommandExecutionError(
+                `coingecko returned no market data for currency "${currency}"`,
+                'Use a CoinGecko-supported quote currency such as usd, cny, eur, or jpy.',
+            );
+        }
+
+        return [{
+            id: data.id || id,
+            symbol: String(data.symbol || '').toUpperCase(),
+            name: data.name || '',
+            rank: data.market_cap_rank ?? null,
+            price,
+            marketCap,
+            volume24h,
+            change24hPct: md.price_change_percentage_24h ?? null,
+            change7dPct: md.price_change_percentage_7d ?? null,
+            change30dPct: md.price_change_percentage_30d ?? null,
+            ath: pick(md.ath, currency),
+            athDate: isoFromMaybe(pick(md.ath_date, currency)),
+            atl: pick(md.atl, currency),
+            atlDate: isoFromMaybe(pick(md.atl_date, currency)),
+            circulatingSupply: md.circulating_supply ?? null,
+            totalSupply: md.total_supply ?? null,
+            maxSupply: md.max_supply ?? null,
+            genesisDate: data.genesis_date || '',
+            homepage: Array.isArray(data.links?.homepage) ? (data.links.homepage.find(Boolean) || '') : '',
+        }];
+    },
+});

package/clis/coingecko/coingecko.test.js

@@ -0,0 +1,109 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './coin.js';
+import './trending.js';
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+
+describe('coingecko coin adapter', () => {
+    const cmd = getRegistry().get('coingecko/coin');
+
+    it('rejects invalid id and currency before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(cmd.func({ id: '../btc', currency: 'usd' }))
+            .rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ id: 'bitcoin', currency: '$$$' }))
+            .rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('fails fast when the requested currency has no market fields', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(
+            new Response(JSON.stringify({
+                id: 'bitcoin',
+                symbol: 'btc',
+                name: 'Bitcoin',
+                market_data: {
+                    current_price: { usd: 1 },
+                    market_cap: { usd: 2 },
+                    total_volume: { usd: 3 },
+                },
+            }), { status: 200 }),
+        ));
+
+        await expect(cmd.func({ id: 'bitcoin', currency: 'zzz' }))
+            .rejects.toThrow(CommandExecutionError);
+    });
+
+    it('returns selected currency market data', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(
+            new Response(JSON.stringify({
+                id: 'bitcoin',
+                symbol: 'btc',
+                name: 'Bitcoin',
+                market_cap_rank: 1,
+                genesis_date: '2009-01-03',
+                links: { homepage: ['https://bitcoin.org', ''] },
+                market_data: {
+                    current_price: { cny: 7 },
+                    market_cap: { cny: 8 },
+                    total_volume: { cny: 9 },
+                    price_change_percentage_24h: 1.23,
+                    ath: { cny: 10 },
+                    ath_date: { cny: '2024-01-02T00:00:00Z' },
+                    atl: { cny: 1 },
+                    atl_date: { cny: '2015-01-14T00:00:00Z' },
+                    circulating_supply: 19,
+                },
+            }), { status: 200 }),
+        ));
+
+        const rows = await cmd.func({ id: 'bitcoin', currency: 'cny' });
+
+        expect(rows).toEqual([expect.objectContaining({
+            id: 'bitcoin',
+            symbol: 'BTC',
+            rank: 1,
+            price: 7,
+            marketCap: 8,
+            volume24h: 9,
+            athDate: '2024-01-02',
+            homepage: 'https://bitcoin.org',
+        })]);
+    });
+
+    it('maps 404 to EmptyResultError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(
+            new Response(JSON.stringify({ error: 'not found' }), { status: 404 }),
+        ));
+
+        await expect(cmd.func({ id: 'missing', currency: 'usd' }))
+            .rejects.toThrow(EmptyResultError);
+    });
+});
+
+describe('coingecko trending adapter', () => {
+    const cmd = getRegistry().get('coingecko/trending');
+
+    it('returns ids that round-trip into coingecko coin <id>', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(
+            new Response(JSON.stringify({
+                coins: [{ item: { id: 'bitcoin', symbol: 'btc', name: 'Bitcoin', market_cap_rank: 1, price_btc: 1, thumb: 'thumb.png' } }],
+            }), { status: 200 }),
+        ));
+
+        const rows = await cmd.func({});
+
+        expect(rows).toEqual([expect.objectContaining({
+            id: 'bitcoin',
+            symbol: 'BTC',
+            marketCapRank: 1,
+        })]);
+    });
+});

package/clis/coingecko/derivatives.js

@@ -0,0 +1,84 @@
+// coingecko derivatives — perpetual / futures tickers across crypto exchanges.
+//
+// Hits the public `/api/v3/derivatives` endpoint (no auth, free tier). Each
+// row is one exchange-symbol combo: market, contract type, mark price, 24h
+// %, basis vs index, funding rate, open interest (USD), 24h volume.
+//
+// CoinGecko sorts the response by 24h volume desc, so `rank` mirrors the
+// listing order with no client-side reshuffling.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const ENDPOINT = 'https://api.coingecko.com/api/v3/derivatives';
+
+cli({
+    site: 'coingecko',
+    name: 'derivatives',
+    access: 'read',
+    description: 'Top crypto derivative (perpetual / futures) markets by 24h volume',
+    domain: 'api.coingecko.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: 'Max rows to return (1-500; CoinGecko returns one large page).' },
+        { name: 'symbol', type: 'string', required: false, help: 'Optional symbol substring filter (e.g. "BTC", "ETHUSDT").' },
+    ],
+    columns: ['rank', 'market', 'symbol', 'indexId', 'contractType', 'price', 'change24hPct', 'fundingRate', 'openInterestUsd', 'volume24hUsd', 'expired'],
+    func: async (args) => {
+        const limit = Number(args.limit ?? 20);
+        if (!Number.isInteger(limit) || limit <= 0) {
+            throw new ArgumentError('coingecko derivatives limit must be a positive integer');
+        }
+        if (limit > 500) {
+            throw new ArgumentError('coingecko derivatives limit must be <= 500');
+        }
+        const filter = args.symbol == null ? '' : String(args.symbol).trim().toUpperCase();
+        let resp;
+        try {
+            resp = await fetch(ENDPOINT, { headers: { 'User-Agent': 'Mozilla/5.0' } });
+        }
+        catch (err) {
+            throw new CommandExecutionError(`coingecko derivatives request failed: ${err?.message ?? err}`);
+        }
+        if (resp.status === 429) {
+            throw new CommandExecutionError(
+                'coingecko derivatives returned HTTP 429 (rate limited)',
+                'Free tier allows ~30 calls/min. Wait and retry.',
+            );
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`coingecko derivatives returned HTTP ${resp.status}`);
+        }
+        let data;
+        try {
+            data = await resp.json();
+        }
+        catch (err) {
+            throw new CommandExecutionError(`coingecko derivatives returned malformed JSON: ${err?.message ?? err}`);
+        }
+        if (!Array.isArray(data) || !data.length) {
+            throw new EmptyResultError('coingecko derivatives', 'CoinGecko returned no derivative tickers.');
+        }
+        let rows = data;
+        if (filter) {
+            rows = data.filter((d) => String(d.symbol ?? '').toUpperCase().includes(filter)
+                || String(d.index_id ?? '').toUpperCase().includes(filter));
+            if (!rows.length) {
+                throw new EmptyResultError('coingecko derivatives', `No derivative tickers matched symbol="${filter}".`);
+            }
+        }
+        return rows.slice(0, limit).map((d, i) => ({
+            rank: i + 1,
+            market: String(d.market ?? ''),
+            symbol: String(d.symbol ?? ''),
+            indexId: String(d.index_id ?? ''),
+            contractType: String(d.contract_type ?? ''),
+            price: d.price != null ? Number(d.price) : null,
+            change24hPct: d.price_percentage_change_24h != null ? Number(d.price_percentage_change_24h) : null,
+            fundingRate: d.funding_rate != null ? Number(d.funding_rate) : null,
+            openInterestUsd: d.open_interest != null ? Number(d.open_interest) : null,
+            volume24hUsd: d.volume_24h != null ? Number(d.volume_24h) : null,
+            expired: d.expired_at ? String(d.expired_at) : '',
+        }));
+    },
+});

package/clis/coingecko/exchanges.js

@@ -0,0 +1,74 @@
+// coingecko exchanges — top crypto exchanges by 24h BTC trading volume.
+//
+// Hits the public `/api/v3/exchanges` endpoint. Returns the columns most
+// useful for an agent: trust score, 24h BTC volume, country, year founded,
+// canonical URL.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+cli({
+    site: 'coingecko',
+    name: 'exchanges',
+    access: 'read',
+    description: 'Top crypto exchanges by 24h BTC trading volume',
+    domain: 'api.coingecko.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: 'Number of exchanges (1-250, CoinGecko per_page upper bound)' },
+        { name: 'page', type: 'int', default: 1, help: 'Page number (1-based)' },
+    ],
+    columns: ['rank', 'id', 'name', 'trustScore', 'volume24hBtc', 'country', 'yearEstablished', 'url'],
+    func: async (args) => {
+        const limit = Number(args.limit ?? 20);
+        if (!Number.isInteger(limit) || limit <= 0) {
+            throw new ArgumentError('coingecko limit must be a positive integer');
+        }
+        if (limit > 250) {
+            throw new ArgumentError('coingecko limit must be <= 250 (per_page upper bound)');
+        }
+        const page = Number(args.page ?? 1);
+        if (!Number.isInteger(page) || page <= 0) {
+            throw new ArgumentError('coingecko page must be a positive integer');
+        }
+        const url = new URL('https://api.coingecko.com/api/v3/exchanges');
+        url.searchParams.set('per_page', String(limit));
+        url.searchParams.set('page', String(page));
+        let resp;
+        try {
+            resp = await fetch(url, { headers: { 'User-Agent': 'Mozilla/5.0' } });
+        }
+        catch (err) {
+            throw new CommandExecutionError(`coingecko exchanges request failed: ${err?.message ?? err}`);
+        }
+        if (resp.status === 429) {
+            throw new CommandExecutionError(
+                'coingecko returned HTTP 429 (rate limited)',
+                'Free tier allows ~30 calls/min. Wait and retry.',
+            );
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`coingecko exchanges returned HTTP ${resp.status}`);
+        }
+        let data;
+        try {
+            data = await resp.json();
+        }
+        catch (err) {
+            throw new CommandExecutionError(`coingecko exchanges returned malformed JSON: ${err?.message ?? err}`);
+        }
+        if (!Array.isArray(data) || !data.length) {
+            throw new EmptyResultError('coingecko exchanges', 'CoinGecko returned no exchange data.');
+        }
+        return data.map((ex, i) => ({
+            rank: (page - 1) * limit + i + 1,
+            id: String(ex.id ?? ''),
+            name: String(ex.name ?? ''),
+            trustScore: ex.trust_score != null ? Number(ex.trust_score) : null,
+            volume24hBtc: ex.trade_volume_24h_btc != null ? Number(ex.trade_volume_24h_btc) : null,
+            country: String(ex.country ?? ''),
+            yearEstablished: ex.year_established != null ? Number(ex.year_established) : null,
+            url: String(ex.url ?? ''),
+        }));
+    },
+});

package/clis/coingecko/global.js

@@ -0,0 +1,71 @@
+// coingecko global — total crypto market cap, volume, BTC/ETH dominance,
+// active currencies, ICO counts, in a single row.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+
+cli({
+    site: 'coingecko',
+    name: 'global',
+    access: 'read',
+    description: 'Aggregate crypto market stats: total market cap, volume, dominance',
+    domain: 'api.coingecko.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'currency', type: 'string', default: 'usd', help: 'Quote currency for total market cap / volume (usd, cny, eur, jpy, ...)' },
+    ],
+    columns: ['currency', 'totalMarketCap', 'totalVolume24h', 'marketCapChange24hPct', 'btcDominancePct', 'ethDominancePct', 'activeCryptocurrencies', 'markets', 'ongoingIcos', 'updatedAt'],
+    func: async (args) => {
+        const currency = String(args.currency ?? 'usd').trim().toLowerCase();
+        if (!/^[a-z0-9-]{2,20}$/.test(currency)) {
+            throw new ArgumentError(`coingecko currency must look like a currency slug (got "${args.currency}")`);
+        }
+        let resp;
+        try {
+            resp = await fetch('https://api.coingecko.com/api/v3/global', { headers: { 'User-Agent': 'Mozilla/5.0' } });
+        }
+        catch (err) {
+            throw new CommandExecutionError(`coingecko global request failed: ${err?.message ?? err}`);
+        }
+        if (resp.status === 429) {
+            throw new CommandExecutionError(
+                'coingecko returned HTTP 429 (rate limited)',
+                'Free tier allows ~30 calls/min. Wait and retry.',
+            );
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`coingecko global returned HTTP ${resp.status}`);
+        }
+        let body;
+        try {
+            body = await resp.json();
+        }
+        catch (err) {
+            throw new CommandExecutionError(`coingecko global returned malformed JSON: ${err?.message ?? err}`);
+        }
+        const data = body?.data;
+        if (!data) {
+            throw new CommandExecutionError('coingecko global returned no data envelope');
+        }
+        const totalMarketCap = data?.total_market_cap?.[currency];
+        const totalVolume = data?.total_volume?.[currency];
+        if (totalMarketCap == null && totalVolume == null) {
+            throw new ArgumentError(
+                `coingecko has no market totals for currency "${currency}"`,
+                'Use a CoinGecko-supported quote currency such as usd, cny, eur, or jpy.',
+            );
+        }
+        return [{
+            currency: currency.toUpperCase(),
+            totalMarketCap: totalMarketCap != null ? Number(totalMarketCap) : null,
+            totalVolume24h: totalVolume != null ? Number(totalVolume) : null,
+            marketCapChange24hPct: data.market_cap_change_percentage_24h_usd != null ? Number(data.market_cap_change_percentage_24h_usd) : null,
+            btcDominancePct: data?.market_cap_percentage?.btc != null ? Number(data.market_cap_percentage.btc) : null,
+            ethDominancePct: data?.market_cap_percentage?.eth != null ? Number(data.market_cap_percentage.eth) : null,
+            activeCryptocurrencies: data.active_cryptocurrencies != null ? Number(data.active_cryptocurrencies) : null,
+            markets: data.markets != null ? Number(data.markets) : null,
+            ongoingIcos: data.ongoing_icos != null ? Number(data.ongoing_icos) : null,
+            updatedAt: data.updated_at ? new Date(data.updated_at * 1000).toISOString() : '',
+        }];
+    },
+});

package/clis/coingecko/top.js

@@ -0,0 +1,64 @@
+// coingecko top — top coins by market cap.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+cli({
+  site: 'coingecko',
+  name: 'top',
+  access: 'read',
+  description: '按市值排序的加密货币行情（默认 USD）',
+  domain: 'api.coingecko.com',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: 'currency', type: 'string', default: 'usd', help: '计价币种 (usd / cny / eur / jpy ...)' },
+    { name: 'limit',    type: 'int',    default: 10,    help: '返回数量（默认 10，最多 250）' },
+  ],
+  columns: ['rank', 'symbol', 'name', 'price', 'change24hPct', 'marketCap', 'volume24h', 'high24h', 'low24h'],
+  func: async (args) => {
+    const currency = String(args.currency ?? 'usd').toLowerCase();
+    const limit = Number(args.limit ?? 10);
+    if (!Number.isInteger(limit) || limit <= 0) {
+      throw new ArgumentError('limit must be a positive integer');
+    }
+    if (limit > 250) {
+      throw new ArgumentError('limit must be <= 250 (CoinGecko per_page upper bound)');
+    }
+
+    const url = new URL('https://api.coingecko.com/api/v3/coins/markets');
+    url.searchParams.set('vs_currency', currency);
+    url.searchParams.set('order', 'market_cap_desc');
+    url.searchParams.set('per_page', String(limit));
+    url.searchParams.set('page', '1');
+    url.searchParams.set('sparkline', 'false');
+
+    let resp;
+    try {
+      resp = await fetch(url, { headers: { 'User-Agent': 'Mozilla/5.0' } });
+    } catch (error) {
+      throw new CommandExecutionError(`coingecko top request failed: ${error?.message || error}`);
+    }
+    if (!resp.ok) throw new CommandExecutionError(`coingecko top failed: HTTP ${resp.status}`);
+    let data;
+    try {
+      data = await resp.json();
+    } catch (error) {
+      throw new CommandExecutionError(`coingecko returned malformed JSON: ${error?.message || error}`);
+    }
+    if (data?.error) throw new CommandExecutionError(`coingecko returned error: ${data.error}`);
+    if (!Array.isArray(data)) throw new CommandExecutionError('coingecko returned an unexpected response');
+    if (data.length === 0) throw new EmptyResultError('coingecko top', 'coingecko returned no market data');
+
+    return data.map((c) => ({
+      rank: c.market_cap_rank,
+      symbol: String(c.symbol ?? '').toUpperCase(),
+      name: c.name,
+      price: c.current_price,
+      change24hPct: c.price_change_percentage_24h,
+      marketCap: c.market_cap,
+      volume24h: c.total_volume,
+      high24h: c.high_24h,
+      low24h: c.low_24h,
+    }));
+  },
+});

package/clis/coingecko/trending.js

@@ -0,0 +1,55 @@
+// coingecko trending — top trending coins on CoinGecko (by user search activity).
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    CommandExecutionError,
+    EmptyResultError,
+} from '@jackwener/opencli/errors';
+
+cli({
+    site: 'coingecko',
+    name: 'trending',
+    access: 'read',
+    description: 'Top trending cryptocurrencies on CoinGecko in the last 24h (search-volume based).',
+    domain: 'api.coingecko.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [],
+    columns: ['rank', 'id', 'symbol', 'name', 'marketCapRank', 'priceBtc', 'thumb'],
+    func: async () => {
+        const url = 'https://api.coingecko.com/api/v3/search/trending';
+        let resp;
+        try {
+            resp = await fetch(url, { headers: { 'User-Agent': 'Mozilla/5.0' } });
+        } catch (error) {
+            throw new CommandExecutionError(`coingecko trending request failed: ${error?.message || error}`);
+        }
+        if (resp.status === 429) {
+            throw new CommandExecutionError('coingecko returned HTTP 429 (rate limited)', 'Wait and retry.');
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`coingecko trending failed: HTTP ${resp.status}`);
+        }
+        let data;
+        try {
+            data = await resp.json();
+        } catch (error) {
+            throw new CommandExecutionError(`coingecko returned malformed JSON: ${error?.message || error}`);
+        }
+        const coins = Array.isArray(data?.coins) ? data.coins : [];
+        if (coins.length === 0) {
+            throw new EmptyResultError('coingecko trending', 'coingecko returned no trending coins.');
+        }
+        return coins.map((entry, i) => {
+            const c = entry?.item || {};
+            return {
+                rank: i + 1,
+                id: c.id || '',
+                symbol: String(c.symbol || '').toUpperCase(),
+                name: c.name || '',
+                marketCapRank: c.market_cap_rank ?? null,
+                priceBtc: c.price_btc ?? null,
+                thumb: c.thumb || c.small || c.large || '',
+            };
+        });
+    },
+});