coingecko-openapi-skill

用途

本技能用于通过 uxc 与精选 OpenAPI schema 操作 CoinGecko 市场数据和 GeckoTerminal 链上 DEX 相关接口，重点是一个以只读市场数据为主的接口面。可复用的执行、认证与错误处理指导来自 uxc 技能。

主要能力

API 存活检查（get:/ping）
现货价格查询（get:/simple/price）
资产 ID 发现（get:/coins/list）
市场筛选读取（get:/coins/markets）
热门查询（get:/search/trending）
GeckoTerminal 网络发现（get:/onchain/networks）
链上代币价格查询（get:/onchain/simple/networks/{network}/token_price/{addresses}）
热门池读取（get:/onchain/networks/trending_pools）

不覆盖：所选 v1 范围之外的付费或企业专属方法族、历史图表或 OHLC 家族、投资组合、NFT、链上交易执行，以及完整的 CoinGecko 或 GeckoTerminal API。

前置条件

已安装 uxc 并可在 PATH 中使用。
可访问 https://api.coingecko.com/api/v3。
可访问精选 OpenAPI schema 地址：https://raw.githubusercontent.com/holon-run/uxc/main/skills/coingecko-openapi-skill/references/coingecko-market.openapi.json。
一个 CoinGecko Demo API Key。

使用方式

认证配置（Demo）

默认主机使用 CoinGecko Demo 认证头 x-cg-demo-api-key。配置一个 API Key 凭据并绑定到 api.coingecko.com/api/v3：

uxc auth credential set coingecko-demo \
  --auth-type api_key \
  --api-key-header x-cg-demo-api-key \
  --secret-env COINGECKO_DEMO_API_KEY

uxc auth binding add \
  --id coingecko-demo \
  --host api.coingecko.com \
  --path-prefix /api/v3 \
  --scheme https \
  --credential coingecko-demo \
  --priority 100

认证出现问题时验证活动映射：

uxc auth binding match https://api.coingecko.com/api/v3

Pro 主机覆盖

如拥有 Pro 计划，保留同一精选 schema，并创建单独的凭据、绑定与链接：

uxc auth credential set coingecko-pro \
  --auth-type api_key \
  --api-key-header x-cg-pro-api-key \
  --secret-env COINGECKO_PRO_API_KEY

uxc auth binding add \
  --id coingecko-pro \
  --host pro-api.coingecko.com \
  --path-prefix /api/v3 \
  --scheme https \
  --credential coingecko-pro \
  --priority 100

uxc link coingecko-pro-openapi-cli https://pro-api.coingecko.com/api/v3 \
  --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/coingecko-openapi-skill/references/coingecko-market.openapi.json

核心工作流

默认检查固定链接命令是否存在：

command -v coingecko-openapi-cli

如缺失则创建：

uxc link coingecko-openapi-cli https://api.coingecko.com/api/v3 --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/coingecko-openapi-skill/references/coingecko-market.openapi.json
coingecko-openapi-cli -h

先检查操作 schema：

coingecko-openapi-cli get:/simple/price -h
coingecko-openapi-cli get:/coins/markets -h
coingecko-openapi-cli get:/onchain/simple/networks/{network}/token_price/{addresses} -h

优先进行范围较窄的读取验证，再扩展到更广的读取：

coingecko-openapi-cli get:/ping
coingecko-openapi-cli get:/coins/list include_platform=false
coingecko-openapi-cli get:/onchain/networks

使用键值参数执行：

coingecko-openapi-cli get:/simple/price ids=bitcoin,ethereum vs_currencies=usd
coingecko-openapi-cli get:/coins/markets vs_currency=usd ids=bitcoin,ethereum order=market_cap_desc per_page=10 page=1
coingecko-openapi-cli get:/onchain/simple/networks/{network}/token_price/{addresses} network=eth addresses=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

coingecko-openapi-cli <operation> ... 等价于 uxc https://api.coingecko.com/api/v3 --schema-url <coingecko_openapi_schema> <operation> ...。

适用场景

适用于需要以只读方式获取 CoinGecko 市场数据（价格、资产列表、市场筛选、热门）或 GeckoTerminal 链上网络与代币价格、热门池信息的自动化流程，并要求通过环境变量管理 API Key、限制调用范围为 v1 schema 的场景。

限制与注意事项

保持自动化使用 JSON 输出封装，不要使用 --text。
优先解析稳定字段：ok、kind、protocol、data、error。
本 v1 技能视为只读，不应暗示支持钱包、交易或投资组合变更。
Demo 与 Pro 主机使用不同的 API Key 头。如默认 Demo 凭据在 Pro 主机失败，应创建单独的 Pro 凭据，而不是复用 Demo 头名。
Pro 主机需要自己的认证绑定于 pro-api.coingecko.com/api/v3；仅创建凭据不足以让链接调用发送 x-cg-pro-api-key。
CoinGecko 公共与 Demo 限额比 Pro 更紧。默认示例应保持窄范围，避免在没有明确用户意图的情况下进行大规模分页循环。
此 schema 中的 GeckoTerminal 端点与其余精选 CoinGecko 主机契约共享同一 API 根与认证流程。

参考资料

使用模式：references/usage-patterns.md
精选 OpenAPI schema：references/coingecko-market.openapi.json
CoinGecko API 文档：https://docs.coingecko.com/reference/endpoint-overview
认证文档：https://docs.coingecko.com/reference/authentication