{"id":"bf9bd518-6ee3-4b68-9254-5e00012fb2b8","shortId":"Akjs26","kind":"skill","title":"coingecko-cli","tagline":"This skill should be used when the user asks for crypto prices, market data, market cap, trending coins, historical or OHLC data, top gainers/losers, coin search, or mentions CoinGecko, the `cg` CLI, or the CoinGecko CLI.","description":"# CoinGecko CLI\n\n## Overview\n\nQuery cryptocurrency market data using the official CoinGecko CLI (`cg`). The CLI wraps the CoinGecko V3 API with structured JSON output, a dry-run mode, and a self-describing command catalog — designed to be driven by agents.\n\n**Key capabilities:**\n\n- Current prices by coin ID or symbol (`cg price`)\n- Top coins by market cap with filters and CSV export (`cg markets`)\n- Coin search with fuzzy matching (`cg search`)\n- Trending coins, NFTs, and categories (`cg trending`)\n- Historical price snapshots, time series, and OHLC (`cg history`)\n- Top gainers/losers over configurable durations (`cg top-gainers-losers`, paid)\n\n**Out of scope** — `cg` does not support contract-address price lookups, global market stats (total market cap, BTC/ETH dominance), NFT detail endpoints, GeckoTerminal on-chain DEX queries, or token logo metadata. Fall back to `WebFetch` against [docs.coingecko.com/llms.txt](https://docs.coingecko.com/llms.txt) for those.\n\n## Prerequisites\n\nVerify the CLI is installed:\n\n```bash\ncommand -v cg || { echo \"cg not on PATH; install via: brew install coingecko/coingecko-cli/cg\"; exit 1; }\n```\n\nCheck authentication and tier without running interactive setup:\n\n```bash\ncg status -o json\n```\n\nThe CLI reads `CG_API_KEY` and `CG_API_TIER` (`demo` or `paid`) from the environment. If `cg status` shows no key, **ask the user** before invoking `cg auth` — that command is interactive and writes config to disk.\n\n### Tier Matrix\n\n| Tier        | Rate Limit       | Monthly Cap | History | Paid-Only Commands   |\n| ----------- | ---------------- | ----------- | ------- | -------------------- |\n| Demo (free) | ~30 req/min      | ~10,000     | 1 year  | —                    |\n| Analyst     | ~500 req/min     | ~500,000    | Deeper  | `top-gainers-losers` |\n| Lite / Pro  | 500–1000 req/min | 1M–3M       | Deeper  | `top-gainers-losers` |\n\nDetect feature gating up front by reading the `paid_only` field in `cg commands -o json`.\n\n## Output Conventions\n\n- **Always pass `-o json`** for any output that needs to be parsed by the agent. The default `table` format is for humans.\n- **Use `--dry-run`** to preview the underlying API request as JSON without executing it. Useful when validating an unfamiliar flag combination before spending a quota.\n- **Use `--export <file.csv>`** only when the user explicitly asks for CSV (`cg markets`, `cg history`, `cg top-gainers-losers` support this).\n\n## Coin ID Resolution\n\nCoinGecko identifies coins by string ID (e.g. `bitcoin`, `ethereum`), not symbol. Many IDs diverge from the coin's common name.\n\n**Resolution order:**\n\n1. **Known coin** — use the table below.\n2. **Symbol** — `cg price --symbols btc,eth ...` works but symbols are non-unique. Only the top-market-cap coin per symbol is returned.\n3. **Unknown / ambiguous** — `cg search <term> -o json` to resolve the ID first, then re-issue the real query.\n\n### Common Coin IDs\n\n| Coin        | ID                        | Symbol |\n| ----------- | ------------------------- | ------ |\n| Bitcoin     | `bitcoin`                 | BTC    |\n| Ethereum    | `ethereum`                | ETH    |\n| Solana      | `solana`                  | SOL    |\n| BNB         | `binancecoin`             | BNB    |\n| XRP         | `ripple`                  | XRP    |\n| Cardano     | `cardano`                 | ADA    |\n| Dogecoin    | `dogecoin`                | DOGE   |\n| Chainlink   | `chainlink`               | LINK   |\n| Avalanche   | `avalanche-2`             | AVAX   |\n| Polygon     | `polygon-ecosystem-token` | POL    |\n| Uniswap     | `uniswap`                 | UNI    |\n| Aave        | `aave`                    | AAVE   |\n| Maker       | `maker`                   | MKR    |\n| USDC        | `usd-coin`                | USDC   |\n| USDT        | `tether`                  | USDT   |\n| DAI         | `dai`                     | DAI    |\n| Wrapped BTC | `wrapped-bitcoin`         | WBTC   |\n\n## Core Commands\n\n### Price\n\n```bash\ncg price --ids bitcoin,ethereum --vs usd -o json\ncg price --symbols btc,eth --vs eur -o json\n```\n\nReturns `{ \"<id>\": { \"<currency>\": <price>, \"<currency>_24h_change\": <pct> } }`.\n\n### Markets\n\n```bash\n# Top 50 by market cap in USD\ncg markets --total 50 --vs usd -o json\n\n# Layer-1 category, sorted by volume, exported to CSV\ncg markets --category layer-1 --order volume_desc --export l1.csv\n```\n\n`--order` enum: `market_cap_desc` (default), `market_cap_asc`, `volume_desc`, `volume_asc`, `id_asc`, `id_desc`. Category IDs come from `cg commands -o json` or [/coins/categories/list](https://docs.coingecko.com/reference/coins-categories-list).\n\n### Search\n\n```bash\ncg search ethereum --limit 5 -o json\n```\n\nReturns an array of `{ id, name, symbol, market_cap_rank }`. Use this first whenever the user gives only a name or symbol.\n\n### Trending\n\n```bash\ncg trending -o json\n```\n\nReturns trending `coins`, `nfts`, and `categories` from the last 24h. `--show-max coins,nfts,categories` increases the per-section limit (paid only).\n\n### History\n\n`cg history <coin>` has three mutually exclusive query modes:\n\n```bash\n# Snapshot on a single date\ncg history bitcoin --date 2024-01-01 -o json\n\n# Last N days, auto-granularity\ncg history ethereum --days 30 -o json\n\n# Explicit date range; --to covers the full day up to 23:59:59 UTC\ncg history solana --from 2024-01-01 --to 2024-03-01 -o json\n```\n\nModifiers:\n\n- `--ohlc` — switch from price series to candlesticks. In `--days` mode, only `1, 7, 14, 30, 90, 180, 365, max` are accepted.\n- `--interval daily|hourly` — override auto-granularity for `--days` or `--from/--to`. Large ranges auto-batch into multiple API requests.\n- `--vs <currency>` — quote currency (default `usd`).\n- `--export <file.csv>` — write to CSV.\n\nReturned JSON in price mode: `{ \"prices\": [[ts_ms, price], ...], \"market_caps\": [...], \"total_volumes\": [...] }`. In OHLC mode the response is a bare array of `[ts_ms, open, high, low, close]` tuples.\n\n### Top Gainers / Losers (paid)\n\n```bash\ncg top-gainers-losers --duration 24h --top-coins 1000 -o json\ncg top-gainers-losers --losers --duration 7d --price-change-percentage 1h,7d,30d -o json\n```\n\n`--duration` enum: `1h, 24h, 7d, 14d, 30d, 60d, 1y`. `--top-coins` enum: `300, 500, 1000, all`. Returns 401 on demo tier — check `paid_only` via `cg commands` before calling.\n\n## Output Formatting\n\nDefault to a Markdown table when presenting results to the user. Honour explicit format requests (JSON, CSV, plain text).\n\n**Number formatting:**\n\n- Prices > $1 → 2 decimals (`$67,187.34`)\n- Prices $0.01 – $1 → 4 decimals (`$0.4523`)\n- Prices < $0.01 → 6+ decimals (`$0.000001234`)\n- Market caps → abbreviated (`$1.32T`, `$415.2B`, `$8.5M`)\n- Percentages → signed, 2 decimals (`+3.64%`, `-1.23%`)\n\n## Self-Discovery\n\nWhen the inline examples don't cover what's needed, query the CLI's own machine-readable catalog:\n\n```bash\ncg commands -o json\n```\n\nEach entry includes `name`, `description`, `examples`, `flags` (with `type`, `default`, `enum`), `output_formats`, `api_endpoint`, `oas_operation_id`, `requires_auth`, and `paid_only`. Use it to detect tier gating before issuing a command, or to find the exact enum values for a flag.\n\nFor one-off flag lookups:\n\n```bash\ncg <subcommand> --help\n```\n\n## Rate Limits & Errors\n\n- **HTTP 429** — back off briefly and retry; batch coin IDs into single calls (`--ids a,b,c`) wherever the command allows.\n- **Missing / invalid key** — `cg status -o json` surfaces it. Prompt the user; do not run `cg auth` non-interactively.\n- **Paid-only command on demo tier** — detect via the `paid_only` field in `cg commands -o json` before invoking. The CLI will otherwise return an API error.\n\n## Additional Resources\n\n- **CLI repo:** <https://github.com/coingecko/coingecko-cli>\n- **AI agent guide:** <https://docs.coingecko.com/docs/ai-agent-hub/cli>\n- **AI-friendly API docs:** <https://docs.coingecko.com/llms.txt> — fetch via `WebFetch` for endpoints `cg` does not expose (contract-address prices, NFT details, GeckoTerminal on-chain DEX data).","tags":["coingecko","cli","agent","skills","paulrberg","agent-skills","ai-agents"],"capabilities":["skill","source-paulrberg","skill-coingecko-cli","topic-agent-skills","topic-ai-agents"],"categories":["agent-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/PaulRBerg/agent-skills/coingecko-cli","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add PaulRBerg/agent-skills","source_repo":"https://github.com/PaulRBerg/agent-skills","install_from":"skills.sh"}},"qualityScore":"0.478","qualityRationale":"deterministic score 0.48 from registry signals: · indexed on github topic:agent-skills · 56 github stars · SKILL.md body (8,004 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:57:35.957Z","embedding":null,"createdAt":"2026-05-12T12:57:55.969Z","updatedAt":"2026-05-18T18:57:35.957Z","lastSeenAt":"2026-05-18T18:57:35.957Z","tsv":"'+3.64':942 '-01':698,699,734,735,739 '-03':738 '-1':569,581 '-1.23':943 '-2':492 '/coingecko/coingecko-cli':1101 '/coins/categories/list':613 '/docs/ai-agent-hub/cli':1107 '/llms.txt':1115 '/llms.txt](https://docs.coingecko.com/llms.txt)':179 '/reference/coins-categories-list).':616 '0.000001234':928 '0.01':919,925 '0.4523':923 '000':272,279 '1':203,273,409,754,913,920 '1.32':932 '10':271 '1000':288,839,874 '14':756 '14d':864 '180':759 '187.34':917 '1h':854,861 '1m':290 '1y':867 '2':416,914,940 '2024':697,733,737 '23':725 '24h':549,663,835,862 '3':441 '30':269,712,757 '300':872 '30d':856,865 '365':760 '3m':291 '4':921 '401':877 '415.2':934 '429':1027 '5':623 '50':554,563 '500':276,278,287,873 '59':726,727 '6':926 '60d':866 '67':916 '7':755 '7d':849,855,863 '8.5':936 '90':758 'aav':503,504,505 'abbrevi':931 'accept':763 'ada':483 'addit':1095 'address':148,1127 'agent':81,329,1103 'ai':1102,1109 'ai-friend':1108 'allow':1046 'alway':315 'ambigu':443 'analyst':275 'api':59,221,225,345,783,984,1093,1111 'array':628,815 'asc':595,599,601 'ask':12,239,370 'auth':245,990,1063 'authent':205 'auto':706,769,779 'auto-batch':778 'auto-granular':705,768 'avalanch':490,491 'avax':493 'b':935,1041 'back':173,1028 'bare':814 'bash':188,212,529,552,618,649,687,828,966,1020 'batch':780,1033 'binancecoin':476 'bitcoin':394,466,467,524,533,695 'bnb':475,477 'brew':199 'briefli':1030 'btc':421,468,521,542 'btc/eth':157 'c':1042 'call':888,1038 'candlestick':749 'cap':19,97,156,261,435,557,590,594,634,804,930 'capabl':83 'cardano':481,482 'catalog':75,965 'categori':116,570,579,604,659,669 'cg':34,52,91,103,110,117,126,133,142,191,193,213,220,224,234,244,309,373,375,377,418,444,530,539,560,577,608,619,650,679,693,708,729,829,842,885,967,1021,1050,1062,1081,1121 'chain':165,1134 'chainlink':487,488 'chang':550,852 'check':204,881 'cli':3,35,39,41,51,54,185,218,959,1088,1097 'close':822 'coin':21,28,87,94,105,113,384,389,403,411,436,461,463,512,656,667,838,870,1034 'coingecko':2,32,38,40,50,57,387 'coingecko-c':1 'coingecko/coingecko-cli/cg':201 'combin':358 'come':606 'command':74,189,247,266,310,527,609,886,968,1003,1045,1070,1082 'common':405,460 'config':252 'configur':131 'contract':147,1126 'contract-address':146,1125 'convent':314 'core':526 'cover':719,953 'crypto':14 'cryptocurr':44 'csv':101,372,576,793,907 'currenc':787 'current':84 'dai':517,518,519 'daili':765 'data':17,25,46,1136 'date':692,696,716 'day':704,711,722,751,772 'decim':915,922,927,941 'deeper':280,292 'default':331,592,788,891,980 'demo':227,267,879,1072 'desc':584,591,597,603 'describ':73 'descript':975 'design':76 'detail':160,1130 'detect':297,997,1074 'dex':166,1135 'discoveri':946 'disk':254 'diverg':400 'doc':1112 'docs.coingecko.com':178,615,1106,1114 'docs.coingecko.com/docs/ai-agent-hub/cli':1105 'docs.coingecko.com/llms.txt':1113 'docs.coingecko.com/llms.txt](https://docs.coingecko.com/llms.txt)':177 'docs.coingecko.com/reference/coins-categories-list).':614 'doge':486 'dogecoin':484,485 'domin':158 'dri':66,339 'driven':79 'dry-run':65,338 'durat':132,834,848,859 'e.g':393 'echo':192 'ecosystem':497 'endpoint':161,985,1120 'entri':972 'enum':588,860,871,981,1009 'environ':232 'error':1025,1094 'eth':422,471,543 'ethereum':395,469,470,534,621,710 'eur':545 'exact':1008 'exampl':950,976 'exclus':684 'execut':350 'exit':202 'explicit':369,715,903 'export':102,364,574,585,790 'expos':1124 'fall':172 'featur':298 'fetch':1116 'field':307,1079 'filter':99 'find':1006 'first':452,638 'flag':357,977,1013,1018 'format':333,890,904,911,983 'free':268 'friend':1110 'front':301 'full':721 'fuzzi':108 'gainer':136,283,295,380,825,832,845 'gainers/losers':27,129 'gate':299,999 'geckotermin':162,1131 'github.com':1100 'github.com/coingecko/coingecko-cli':1099 'give':642 'global':151 'granular':707,770 'guid':1104 'help':1022 'high':820 'histor':22,119 'histori':127,262,376,678,680,694,709,730 'honour':902 'hour':766 'http':1026 'human':336 'id':88,385,392,399,451,462,464,532,600,602,605,630,988,1035,1039 'identifi':388 'includ':973 'increas':670 'inlin':949 'instal':187,197,200 'interact':210,249,1066 'interv':764 'invalid':1048 'invok':243,1086 'issu':456,1001 'json':62,216,312,318,348,447,538,547,567,611,625,653,701,714,741,795,841,858,906,970,1053,1084 'key':82,222,238,1049 'known':410 'l1.csv':586 'larg':776 'last':662,702 'layer':568,580 'limit':259,622,675,1024 'link':489 'lite':285 'logo':170 'lookup':150,1019 'loser':137,284,296,381,826,833,846,847 'low':821 'm':937 'machin':963 'machine-read':962 'maker':506,507 'mani':398 'markdown':894 'market':16,18,45,96,104,152,155,374,434,551,556,561,578,589,593,633,803,929 'match':109 'matrix':256 'max':666,761 'mention':31 'metadata':171 'miss':1047 'mkr':508 'mode':68,686,752,798,809 'modifi':742 'month':260 'ms':801,818 'multipl':782 'mutual':683 'n':703 'name':406,631,645,974 'need':323,956 'nft':159,1129 'nfts':114,657,668 'non':428,1065 'non-interact':1064 'non-uniqu':427 'number':910 'o':215,311,317,446,537,546,566,610,624,652,700,713,740,840,857,969,1052,1083 'oa':986 'offici':49 'ohlc':24,125,743,808 'on-chain':163,1132 'one':1016 'one-off':1015 'open':819 'oper':987 'order':408,582,587 'otherwis':1090 'output':63,313,321,889,982 'overrid':767 'overview':42 'paid':138,229,264,305,676,827,882,992,1068,1077 'paid-on':263,1067 'pars':326 'pass':316 'path':196 'per':437,673 'per-sect':672 'percentag':853,938 'plain':908 'pol':499 'polygon':494,496 'polygon-ecosystem-token':495 'prerequisit':182 'present':897 'preview':342 'price':15,85,92,120,149,419,528,531,540,746,797,799,802,851,912,918,924,1128 'price-change-percentag':850 'pro':286 'prompt':1056 'queri':43,167,459,685,957 'quot':786 'quota':362 'rang':717,777 'rank':635 'rate':258,1023 're':455 're-issu':454 'read':219,303 'readabl':964 'real':458 'repo':1098 'req/min':270,277,289 'request':346,784,905 'requir':989 'resolut':386,407 'resolv':449 'resourc':1096 'respons':811 'result':898 'retri':1032 'return':440,548,626,654,794,876,1091 'rippl':479 'run':67,209,340,1061 'scope':141 'search':29,106,111,445,617,620 'section':674 'self':72,945 'self-describ':71 'self-discoveri':944 'seri':123,747 'setup':211 'show':236,665 'show-max':664 'sign':939 'singl':691,1037 'skill':5 'skill-coingecko-cli' 'snapshot':121,688 'sol':474 'solana':472,473,731 'sort':571 'source-paulrberg' 'spend':360 'stat':153 'status':214,235,1051 'string':391 'structur':61 'support':145,382 'surfac':1054 'switch':744 'symbol':90,397,417,420,425,438,465,541,632,647 'tabl':332,414,895 'tether':515 'text':909 'three':682 'tier':207,226,255,257,880,998,1073 'time':122 'token':169,498 'top':26,93,128,135,282,294,379,433,553,824,831,837,844,869 'top-coin':836,868 'top-gainers-los':134,281,293,378,830,843 'top-market-cap':432 'topic-agent-skills' 'topic-ai-agents' 'total':154,562,805 'trend':20,112,118,648,651,655 'ts':800,817 'tupl':823 'type':979 'under':344 'unfamiliar':356 'uni':502 'uniqu':429 'uniswap':500,501 'unknown':442 'usd':511,536,559,565,789 'usd-coin':510 'usdc':509,513 'usdt':514,516 'use':8,47,337,352,363,412,636,994 'user':11,241,368,641,901,1058 'utc':728 'v':190 'v3':58 'valid':354 'valu':1010 'verifi':183 'via':198,884,1075,1117 'volum':573,583,596,598,806 'vs':535,544,564,785 'wbtc':525 'webfetch':175,1118 'whenev':639 'wherev':1043 'without':208,349 'work':423 'wrap':55,520,523 'wrapped-bitcoin':522 'write':251,791 'xrp':478,480 'year':274","prices":[{"id":"c32ebc2f-3520-4d14-b3dd-a21a385578eb","listingId":"bf9bd518-6ee3-4b68-9254-5e00012fb2b8","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"PaulRBerg","category":"agent-skills","install_from":"skills.sh"},"createdAt":"2026-05-12T12:57:55.969Z"}],"sources":[{"listingId":"bf9bd518-6ee3-4b68-9254-5e00012fb2b8","source":"github","sourceId":"PaulRBerg/agent-skills/coingecko-cli","sourceUrl":"https://github.com/PaulRBerg/agent-skills/tree/main/skills/coingecko-cli","isPrimary":false,"firstSeenAt":"2026-05-12T12:57:55.969Z","lastSeenAt":"2026-05-18T18:57:35.957Z"}],"details":{"listingId":"bf9bd518-6ee3-4b68-9254-5e00012fb2b8","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"PaulRBerg","slug":"coingecko-cli","github":{"repo":"PaulRBerg/agent-skills","stars":56,"topics":["agent-skills","ai-agents"],"license":"mit","html_url":"https://github.com/PaulRBerg/agent-skills","pushed_at":"2026-05-17T10:33:19Z","description":"PRB's collection of agent skills","skill_md_sha":"306d6aab15b7b25cce5ee72b6e1f2d4f0614b2ff","skill_md_path":"skills/coingecko-cli/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/PaulRBerg/agent-skills/tree/main/skills/coingecko-cli"},"layout":"multi","source":"github","category":"agent-skills","frontmatter":{"name":"coingecko-cli","description":"This skill should be used when the user asks for crypto prices, market data, market cap, trending coins, historical or OHLC data, top gainers/losers, coin search, or mentions CoinGecko, the `cg` CLI, or the CoinGecko CLI."},"skills_sh_url":"https://skills.sh/PaulRBerg/agent-skills/coingecko-cli"},"updatedAt":"2026-05-18T18:57:35.957Z"}}