OpenCLI CoinGecko 适配器实战指南在终端零鉴权获取加密货币市场数据【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI导读本文围绕 OpenCLI 项目中的 CoinGecko 适配器docs/adapters/browser/coingecko.md展开系统讲解如何通过opencli coingecko系列命令在终端中直接获取加密货币行情、热门币种、交易所、板块分类、衍生品与全网市值等市场数据。读完本文你将掌握全部 7 个命令的用法与参数细节、输出列语义、底层实现原理与错误处理边界能够把 CoinGecko 数据直接接入你的脚本或 Agent 工作流——全程无需 API Key、无需登录浏览器。适配器概览Public 策略下的免鉴权数据通道CoinGecko 适配器是 OpenCLI 中典型的Public公开策略适配器运行模式为 Public目标域名为api.coingecko.com。它的核心特征是从源码结构看非常明确见 clis/coingecko 下各命令文件无需浏览器所有命令均声明browser: false不依赖浏览器自动化直接通过fetch调用 CoinGecko 公共市场数据端点无需鉴权请求仅携带User-Agent: Mozilla/5.0头不附加任何 API KeyAgent 友好每个命令通过cli()注册器声明site、access: read、参数、输出列与处理函数输出统一为结构化行数据天然适合被 LLM Agent 消费。在 OpenCLI 中这类适配器与需要登录态/浏览器自动化的适配器形成互补公共数据走 Public 策略私域数据才走登录态策略从而在“速度”与“覆盖面”之间取得平衡。命令总览CommandDescriptionopencli coingecko topTop coins by market capopencli coingecko coin idSingle coins market detail (price / supply / ATH / homepage)opencli coingecko trendingTop trending coins on CoinGecko in the last 24hopencli coingecko exchangesTop exchanges ranked by trust score / 24h BTC volumeopencli coingecko categoriesCrypto sector categories (DeFi / Layer1 / Memes / …) with market capopencli coingecko derivativesTop crypto derivative (perpetual / futures) markets by 24h volumeopencli coingecko globalAggregate market totals: total cap, volume, BTC/ETH dominance快速开始用法示例以下示例覆盖全部命令的核心用法可直接在终端复制运行来自原文档并补充了参数说明# Top 10 coins in USD (default) opencli coingecko top # Top 5 coins priced in CNY opencli coingecko top --currency cny --limit 5 # Top 50 coins in EUR opencli coingecko top --currency eur --limit 50 # Single coin detail (slug from top or coingecko URL) opencli coingecko coin bitcoin opencli coingecko coin ethereum --currency cny # Trending in the last 24h (search-volume based) opencli coingecko trending # Top exchanges (trust score, 24h BTC volume) opencli coingecko exchanges --limit 20 # Crypto sector categories (default sort: market_cap_desc) opencli coingecko categories --limit 10 opencli coingecko categories --sort market_cap_change_24h_desc --limit 10 # Top derivative tickers (perpetuals futures, sorted by 24h USD volume) opencli coingecko derivatives --limit 20 # Filter derivatives by symbol substring (BTC pairs only) opencli coingecko derivatives --symbol BTC --limit 10 # Aggregate market totals (BTC dominance, total cap, etc.) opencli coingecko global opencli coingecko global --currency cny # JSON output opencli coingecko top -f json最后一行展示了 OpenCLI 通用的-f json输出开关默认输出为表格对应各命令声明的columns切换到 JSON 后即可将数据直接喂给脚本或下游 Agent 流程。逐命令详解参数、输出列与底层实现以下结合各命令源码clis/coingecko逐条讲解参数语义、取值范围与实现原理。top— 按市值排名的行情榜单OptionDescription--currencyQuote currencyusd/cny/eur/jpy/ etc.默认usd--limitNumber of coins to return1–250默认10实现要点见 clis/coingecko/top.js调用 CoinGecko/api/v3/coins/markets端点固定以market_cap_desc排序、page1、sparklinefalse--limit直接映射到 API 的per_page参数上限 250 正是 CoinGecko 的per_page上界超限会被ArgumentError提前拒绝不会静默截断输出列rank, symbol, name, price, change24hPct, marketCap, volume24h, high24h, low24h其中rank取自market_cap_ranksymbol统一转为大写。coin— 单币种深度行情OptionDescriptionidpositionalCoinGecko coin slug小写例如bitcoin、ethereum、solana--currencyQuote currency默认usd实现要点见 clis/coingecko/coin.js请求前双重校验id必须匹配 slug 正则^[a-z0-9][a-z0-9-]*$currency必须匹配^[a-z0-9-]{2,20}$非法输入直接抛ArgumentError不会发起任何网络请求测试 clis/coingecko/coingecko.test.js 专门验证了这一点调用/api/v3/coins/{id}端点并通过localizationfalse、tickersfalse、community_datafalse、developer_datafalse、sparklinefalse精简响应体只保留市场数据404 映射不存在的 slug 会被映射为EmptyResultError方便调用方区分“查无此币”与“网络故障”fail-fast 语义如果所选currency下current_price、market_cap、total_volume三者都为空立即抛CommandExecutionError提示改用 CoinGecko 支持的报价币种而不是返回一行空数据ATH/ATL 日期通过String(s).slice(0, 10)裁剪为YYYY-MM-DDhomepage取links.homepage数组中第一个非空项输出列id, symbol, name, rank, price, marketCap, volume24h, change24hPct, change7dPct, change30dPct, ath, athDate, atl, atlDate, circulatingSupply, totalSupply, maxSupply, genesisDate, homepage。trending— 24 小时热门币种No arguments— returns the current top-7 trending list.实现要点见 clis/coingecko/trending.js调用/api/v3/search/trending端点数据基于 CoinGecko 站内近 24 小时搜索热度并非市值排序输出列rank, id, symbol, name, marketCapRank, priceBtc, thumb其中priceBtc为以 BTC 计价的价格thumb为币种缩略图 URL从测试可见trending返回的id可以与coin id无缝衔接round-trip是“发现热点 → 深挖详情”链路的理想入口。exchanges— 交易所信任度与成交量排行OptionDescription--limitNumber of exchanges to return1–250默认20实现要点见 clis/coingecko/exchanges.js调用/api/v3/exchanges端点limit同样受 CoinGeckoper_page上界 250 约束从源码结构看该命令还额外支持--page默认 11-based用于翻页rank按(page - 1) * limit i 1计算可组合出“前 500 所交易所”的分页遍历输出列rank, id, name, trustScore, volume24hBtc, country, yearEstablished, url——trustScore是 CoinGecko 的交易所信任分volume24hBtc为 24h BTC 计价交易量适合做交易所基本面筛选。categories— 板块/赛道市值排行OptionDescription--sortOne ofmarket_cap_desc默认、market_cap_asc、name_desc、name_asc、market_cap_change_24h_desc、market_cap_change_24h_asc--limitNumber of categories to return1–100默认20实现要点见 clis/coingecko/categories.js调用/api/v3/coins/categories端点可识别 DeFi、Layer1、Memes、Gaming、RWA 等板块的资金动向sort 白名单校验--sort必须命中源码中固定的ORDER_OPTIONS数组否则抛ArgumentError并列出全部合法取值limit 上限 100源码注释说明 CoinGecko 该端点最多返回约 120 个类别适配器将其截断到 100超出即报错top3Coins列由响应的top_3_coins_id数组 join 成逗号分隔字符串输出列rank, id, name, marketCap, volume24h, marketCapChange24hPct, top3Coins。derivatives— 永续/交割合约行情OptionDescription--limitMax rows to return1–500默认20--symbolOptional symbol substring filtere.g.BTC、ETHUSDT——also matches theindex_idfield实现要点见 clis/coingecko/derivatives.js调用/api/v3/derivatives端点CoinGecko 按 24h 成交量降序返回一页大列表因此rank直接反映原始顺序客户端不做重排limit 上限放宽到 500与其他命令不同因为该端点单页即可返回大量行symbol 过滤是本地子串匹配对symbol与index_id两个字段做大小写不敏感的子串包含判断过滤前统一转大写没有匹配结果时抛EmptyResultError并提示匹配的过滤词输出列rank, market, symbol, indexId, contractType, price, change24hPct, fundingRate, openInterestUsd, volume24hUsd, expired——fundingRate资金费率与openInterestUsd未平仓合约额是衍生品分析的关键字段expired为交割时间字符串。global— 全网宏观数据OptionDescription--currencyQuote currency for total market cap / volume默认usd实现要点见 clis/coingecko/global.js调用/api/v3/global端点响应外层为data信封envelope源码会显式校验该信封存在从total_market_cap[currency]与total_volume[currency]中按所选币种取值若两者皆空则抛ArgumentError提示使用受支持的报价币种updatedAt将 Unix 秒级时间戳转换为 ISO 8601 字符串输出列currency, totalMarketCap, totalVolume24h, marketCapChange24hPct, btcDominancePct, ethDominancePct, activeCryptocurrencies, markets, ongoingIcos, updatedAt适合作为宏观行情快照。参数校验与错误处理源码级边界行为CoinGecko 适配器在错误处理上非常规整从各命令源码可以归纳出统一的行为模式场景抛出异常说明--limit非正整数 / 超上限250、100、500 按命令不同ArgumentError提前拦截无静默 clamp--sort非法取值ArgumentError附全部合法取值id/currency格式非法ArgumentError校验先于网络请求币种无对应市场数据CommandExecutionErrorcoin / global 均 fail-fast币种不存在HTTP 404EmptyResultErrorcoin 命令专用映射过滤后无匹配derivativesEmptyResultError提示所用过滤词HTTP 429 限流CommandExecutionError提示等待重试网络错误 / 非 2xx / JSON 解析失败CommandExecutionError统一包装错误信息特别的**--limit的“不静默截断”**是设计亮点文档与源码均强调超过 CoinGeckoper_page上界时直接以ArgumentError报错而不是悄悄返回被截断的数据避免 Agent 拿到“看似正确实则缺失”的结果。测试验证适配器行为的可执行证据clis/coingecko/coingecko.test.js 使用 Vitest 对coin与trending两个命令做了行为级验证可作为理解实现语义的参考非法输入不触网id../btc、currency$$$均在被ArgumentError拒绝且断言fetch未被调用货币无市场字段 fail-fastmock 响应只含usd字段时请求currencyzzz会抛CommandExecutionError多币种映射正确currencycny时价格、市值、ATH 等均取对应币种值athDate被裁剪为2024-01-02homepage取首个有效链接404 映射coin missing的 404 响应被转为EmptyResultErrortrending 与 coin 的联动trending 返回的id可被coin id直接消费验证了“热点 → 详情”闭环的可行性。如需运行该测试套件可在仓库根目录执行bun test clis/coingecko/coingecko.test.js仓库同时提供bun.lock与package-lock.json详见 TESTING.md。注意事项与使用限制最后汇总适配器的几条使用前提与限制见原文档 Notes 及源码佐证公开接口有速率限制免费档约 30 次/分钟源码在多个 429 分支中注明~30 calls/min。遇到瞬时HTTP 429时短暂等待后重试即可适配器会以CommandExecutionError明确提示限流而非静默失败所有数值均以所选--currency计价coin在 CoinGecko 未返回该币种的市场字段时会快速失败而不是输出残缺数据change24hPct是原始百分比例如2.34表示2.34%不是小数分数读取输出时不要误除 100--limit前置校验非正整数或超过 CoinGeckoper_page上界各命令依次为 250 / 250 / 100 / 500都会抛ArgumentError不存在静默截断调用方应在上游做参数约束。延伸阅读适配器官方文档docs/adapters/browser/coingecko.md全部命令实现clis/coingeckotop.js/coin.js/trending.js/exchanges.js/categories.js/derivatives.js/global.js行为测试clis/coingecko/coingecko.test.js适配器文档索引docs/adapters 与 docs/index.md项目测试总览TESTING.md若你需要将行情数据接入自动化流程推荐组合为trending发现热点 →coin id深挖单币 →global --currency cny抓宏观快照全程表格或-f json输出均可无需任何鉴权配置。【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考