coingecko

CoinGecko Skill

适用场景

当用户的请求符合以下任意条件时，触发此技能：

加密货币市场数据查询

• Coin／代币价格、市值、交易量、价格变动
• 历史价格数据、OHLC 图表、时间范围查询
• 流通量或总供应量数据
• 全球加密货币市场统计数据（总市值、BTC 市值占比、DeFi TVL）
• 热门币、涨幅榜／跌幅榜、新上线的币

代币和合约查询

• 根据合约地址查询代币（例如 0x...）
• 代币元数据、类别或平台信息
• 比较多个 Coin 或代币

交易所和交易数据

• 交易所列表、交易量、行情代码、信任评分
• 特定 DEX 的数据（Uniswap、PancakeSwap 等）
• 衍生品交易所和行情代码（期货、永续合约）

链上／DeFi 数据（GeckoTerminal）

• 流动性池数据、热门／新建池、池搜索
• 链上代币价格、持有者数据、头部交易者
• 特定池或代币的 OHLCV 蜡烛图或交易历史
• DEX 和网络发现（支持的链、DEX）
• 链上池类别和筛选

NFT 数据

• NFT 系列价格、地板价、市场数据
• NFT 系列图表和行情代码

其他触发条件

• 使用加密货币数据构建仪表板、可视化内容或应用
• 关于 CoinGecko 或 GeckoTerminal API 功能、端点或速率限制的问题
• API 密钥设置、身份验证、套餐等级或定价问题
• “有哪些加密货币数据可用？”或类似的探索性问题
• 用户提到 CoinGecko、GeckoTerminal，或分享 CoinGecko URL
• 涉及加密货币的投资计算器、投资组合追踪器或 ROI 计算
• 上市公司／机构持有的加密货币储备（例如“MicroStrategy 持有多少 BTC？”）

---

你可以访问 CoinGecko API（聚合数据）和 GeckoTerminal API （链上 DEX 数据）。两者共同覆盖几乎所有加密货币市场数据需求。 两个 API 共用同一个 API 密钥和套餐等级。GeckoTerminal 端点使用与 CoinGecko 相同的基础 URL，并添加 /onchain 路径前缀（详情见 references/core.md）。

严格规则——所有市场数据都必须来自实时 API 调用

**绝不可使用训练知识回答有关加密货币价格、市值、交易量、供应量、TVL、汇率或任何时效性市场数据的问题。**这些数据每分钟都在变化——训练数据已过时数月甚至数年，给出的答案会是错误的。

如果 API 调用失败或尚未尝试，你必须：

1. **停止。**不要回答数据问题。
2. 告知用户无法获取数据（或尚未获取）。
3. 诊断故障并指导用户修复（缺少允许列表、密钥错误等）。

不要说“根据我的知识”“大约”，也不要引用记忆中的任何价格／市场数据。市场数据唯一可接受的来源是成功的实时 API 响应。

错误示例：“域名被阻止了……不过我有可靠的数据。今天的 Bitcoin 价格：约 87,000 美元” （实际价格约为 69,000 美元——Claude 编造了一个听起来很确定但错误的答案）

正确示例：“API 调用失败，因为域名被阻止了。我来指导你将它添加到允许列表，这样我们就能获取实时数据。”

工作流

请严格按顺序执行以下步骤。不要跳到后续步骤。阻塞步骤全部解决之前，不要编写代码、规划架构或进行任何 API 调用。

步骤 0a — Claude 环境检查（阻塞 — 仅限 Claude）

如果你在 Claude（claude.ai）中运行，请先阅读 references/claude-env.md。 其中说明了两个会导致所有 CoinGecko API 调用失败的平台限制：

1. 域名允许列表 — 用户必须在 claude.ai/settings/capabilities 中添加 api.coingecko.com 和 pro-api.coingecko.com。 如果这是用户首次使用，或任何调用因网络错误而失败，请暂停操作， 先引导用户完成此设置，再排查其他问题。
2. Artifact 沙盒 — 在 Artifacts 中使用 fetch() 总会静默失败。 对所有 CoinGecko API 调用，默认使用带 curl 的 bash_tool， 然后将结果作为静态数据嵌入任何 Artifact 或可视化内容中。这是标准做法，不是备用方案。

如果不是在 Claude 中运行，请跳过此步骤。

步骤 0b — 确认凭据（阻塞）

停止。在进行任何其他操作之前，你必须确认用户的 API 套餐等级。这是硬性前提—— 不是建议，不是之后再确认的事项，也不能因为“无密钥应该也能满足本次请求”而跳过。

**原因：**无密钥和 Demo 套餐存在一些限制，会导致多步骤任务悄然失败。失败模式示例：

用户：“如果我 5 年前投资了 Bitcoin，现在会值多少钱？” 不当行为：Claude 假设无密钥也能用，开始构建仪表板，随后因无密钥/Demo 无法获取超过 365 天的历史数据而遇到 错误 10012。 用户在本来就无法完成的任务上浪费了时间和速率限制调用次数。

正确做法是先询问凭据，确认“5 年前”超出无密钥/Demo 的限制，并在编写任何代码之前就告知用户。

流程：

1. 检查记忆中是否保存了之前的套餐等级和 API 密钥。
2. 如果找到了，请确认它们仍然有效。如果没找到，询问用户：
   • 套餐等级 — 付费（Pro）还是免费（Demo）？
   • API 密钥 — 用户的 CG-… 密钥？
3. 没有密钥？ 只有在用户明确表示没有密钥后，才可退而使用无密钥方案。 如果用户只是没有提到密钥，请询问——不要把沉默当作“没有密钥”。 使用无密钥方案时，须提醒：每分钟最多 5 次调用、稳定性不定，且存在数据限制。 建议申请免费的 Demo 密钥：https://www.coingecko.com/en/api/pricing。
4. 根据已确认的套餐评估可行性。 检查请求是否涉及超出套餐限制的数据或端点，例如超过 365 天的历史数据 （无密钥/Demo）、仅限 Enterprise 的时间间隔（5m），或仅限付费套餐的端点。如果超出限制， 请在尝试任何调用之前告知用户。不要先发起调用，等它失败。
5. 阅读 references/core.md 了解完整的身份验证设置，并将已确认的套餐等级保存到记忆中。

在完全完成此步骤之前，不要继续执行步骤 1。

步骤 1 — 确定领域

使用下方的参考索引，决定要加载哪些文件。

步骤 2 — 加载参考资料并构造请求

加载相关参考文件并构建 API 调用。

步骤 3 — 执行并处理错误

身份验证和速率限制错误代码记载在 references/core.md 中。如果 API 返回错误 10005， 说明该端点需要更高等级的套餐——告知用户并提供链接 https://www.coingecko.com/en/api/pricing。如果遇到错误 10010 或 10011，说明密钥类型与基础 URL 不匹配—— 按照 core.md 的错误表切换 URL，并自动重试。

**“Failed to fetch”或网络错误：**如果请求失败且没有 HTTP 状态码（例如 “Failed to fetch”或 TypeError），如果是在 Claude 中运行，请遵循 references/claude-env.md 中的诊断流程—— 原因通常是 Artifact CSP 沙盒（改用 bash_tool），或缺少域名允许列表条目。在 Claude 以外的环境中，原因可能是基础 URL 错误——参阅 core.md 的“网络级故障”部分。无论哪种情况，都不要假定问题出在 CORS。

参考索引

根据用户的请求加载相关参考文件。只需加载与当前请求相匹配的文件。

灵感与使用场景

如果用户询问可以构建什么、想要项目创意，或提出“有哪些数据可用？”之类的探索性问题，请加载 references/common-use-cases.md，而不是下面的特定领域文件，然后按照其中的指引进一步查找。

环境

文件	加载时机
references/claude-env.md	在步骤 0a 中阅读 — Claude 特定限制（域名允许列表、Artifact CSP 沙箱、bash_tool 策略、MCP 升级路径）。仅适用于在 Claude 中运行的情况。

CoinGecko（聚合数据）

文件	加载时机
references/core.md	始终阅读 — 身份验证、方法、速率限制
references/coins.md	Coin 价格、市场数据、元数据、行情、涨幅榜/跌幅榜
references/coin-history.md	按 Coin ID 查询历史图表、OHLC 和时间范围
references/coin-supply.md	流通量/总供应量图表
references/contract.md	按代币合约地址查询 Coin 数据或图表
references/asset-platforms.md	区块链平台 ID、代币列表
references/categories.md	Coin 类别和板块市场数据
references/exchanges.md	现货和 DEX 交易所数据、行情、交易量图表
references/derivatives.md	衍生品交易所和行情
references/treasury.md	上市公司/机构的加密货币储备
references/nfts.md	NFT 收藏品数据、市场数据、图表、行情
references/global.md	全球市场统计数据和 DeFi 数据
references/utils.md	API 状态、API 密钥用量、支持的货币、搜索、热门 Coin/NFT/类别、汇率

GeckoTerminal（链上数据）

文件	加载时机
references/onchain-networks.md	支持的网络和 DEX（ID 解析）
references/onchain-pools.md	池发现、热门/新建池、megafilter
references/onchain-tokens.md	代币数据、按合约地址查询价格、持有者和交易者
references/onchain-ohlcv-trades.md	池/代币的 OHLCV 蜡烛图和交易历史
references/onchain-categories.md	链上池类别（GeckoTerminal 专属）

通用指南

• 如果请求涉及多个领域（例如 Coin 价格和交易所数据），请加载多个参考文件。
• 不确定要加载哪个文件时，请先查看上面的索引。
• 有关 CoinGecko 与 GeckoTerminal 的选择，请参阅 references/core.md（方法部分）。