coingecko

脚本用法

脚本模式技能 — 阅读此文件，然后在 bash 代码块中调用：

python3 - <<'EOF'
import sys, json
sys.path.insert(0, "/data/workspace/skills/coingecko")
from exports import coin_price, cg_trending, cg_global

print(coin_price(coin_ids="bitcoin,ethereum"))
print(cg_trending())
EOF

查看 exports.py 获取可用函数的完整列表。常用函数： coin_price、coin_ohlc、coin_chart、cg_trending、 cg_top_gainers_losers、cg_new_coins、cg_global、cg_global_defi、 cg_categories、cg_derivatives、cg_coins_markets、cg_coin_data、 cg_coin_tickers、cg_search、cg_token_price、cg_coin_by_contract。

CoinGecko 技能

函数参考（签名）

所有公共函数都在 exports.py 中。coin_id 是 CoinGecko id （例如 bitcoin、ethereum）——如果不确定，请先使用 cg_search(query)。 vs_currency 默认为 usd。

价格与图表

函数	描述
coin_price(coin_ids, timestamps=None, vs_currency='usd')	当前或历史价格。coin_ids = 类似 "bitcoin,ethereum" 的逗号分隔字符串。timestamps = 用于历史查询的 Unix 时间戳列表（默认：现在）。
coin_ohlc(coin_id, days=30, vs_currency='usd')	最近 N 天的 OHLC 数据。返回 [ts, o, h, l, c] 列表。粒度自动选择：1d=30min、7-30d=4h、30d+=4h。
coin_chart(coin_id, days=30, vs_currency='usd')	价格 + market_cap + total_volume 时间序列。返回 {prices, market_caps, total_volumes}（每项均为 [ts, val] 列表）。

发现

函数	描述
cg_trending()	热门币种、NFT 和类别（最近 24h）。
cg_top_gainers_losers(vs_currency='usd', duration='24h')	涨幅最高和跌幅最大的币种。duration = 1h/24h/7d/14d/30d/60d/1y。
cg_new_coins()	最近上线的币种。
cg_search(query)	按名称搜索币种、交易所和类别。

市场数据

函数	描述
cg_global()	全球加密货币市场：总 market_cap、volume、dominance。
cg_global_defi()	全球 DeFi：TVL、dominance、顶级协议。
cg_coins_markets(vs_currency='usd', order='market_cap_desc', per_page=100, page=1, sparkline=False, price_change_percentage='24h', category=None, ids=None)	获取包含完整市场数据的顶级币种。
cg_coin_data(coin_id, localization=False, tickers=False, market_data=True, community_data=False, developer_data=False, sparkline=False)	单个币种的详细数据。
cg_coin_tickers(coin_id, exchange_ids=None, include_exchange_logo=False, page=1, order='volume_desc', depth=False)	币种的交易场所及成交量。
cg_coins_list(include_platform=False)	所有币种 id/符号（用于解析）。

类别 / 衍生品 / NFT

函数	描述
cg_categories(order='market_cap_desc')	市值和成交量最高的类别。
cg_categories_list()	仅类别 id/名称。
cg_derivatives(include_tickers='unexpired')	所有交易所的衍生品行情数据（约 27k 行）。返回 {tickers, count, filter}；参见下文“衍生品：字段与全市场 OI”。
cg_derivatives_exchanges(order='open_interest_btc_desc', per_page=50)	衍生品交易所排名。
cg_nfts_list(order='market_cap_usd_desc', per_page=100, page=1)	顶级 NFT 收藏品。
cg_nft(nft_id)	NFT 收藏品详情。
cg_nft_by_contract(asset_platform, contract_address)	按合约地址查询 NFT。

交易所

函数	描述
cg_exchanges(per_page=100, page=1)	交易所排名。
cg_exchange(exchange_id)	单个交易所的详情。
cg_exchange_tickers(exchange_id, ...)	交易所上的行情数据。
cg_exchange_volume_chart(exchange_id, days=30)	交易所成交量历史。

合约 / 代币（按平台）

功能	描述
cg_token_price(platform, contract_addresses, vs_currencies='usd', include_market_cap=False, include_24hr_vol=False, include_24hr_change=False, include_last_updated_at=False)	根据平台上的合约地址查询价格。
cg_coin_by_contract(platform, contract_address)	根据合约查询代币元数据。
cg_asset_platforms(filter=None)	支持的链。
cg_vs_currencies()	支持的报价货币。
cg_exchange_rates()	以 BTC 计价的法币 / 主流代币汇率。

🚫 关键：停下——调用任何工具前请先阅读

最常见的错误是调用 Coinglass 工具，而不是 CoinGecko 工具。 它们名称相似，但属于完全不同的系统。

错误 → 正确的工具替换表

❌ 切勿调用	✅ 改为调用	区分方法
cg_coins_market_data	cg_coins_markets	market_data = Coinglass 衍生品数据；markets = CoinGecko 现货数据。
cg_ohlc_history	coin_ohlc	ohlc_history = Coinglass 期货 K 线；coin_ohlc = CoinGecko 现货 K 线。
cg_pair_market_data	cg_coin_tickers	pair_market_data = Coinglass 期货交易对；coin_tickers = CoinGecko 现货交易对。
cg_supported_exchanges	cg_exchanges	supported_exchanges = Coinglass 期货；exchanges = CoinGecko 现货。
cg_taker_exchanges	cg_exchange	taker = Coinglass 成交量；exchange = CoinGecko 交易所信息。
cg_aggregated_taker_volume	cg_coin_tickers	taker_volume = Coinglass；coin_tickers = CoinGecko 在各交易所的成交量。
defillama_chains	cg_global_defi	查询 CoinGecko 的 DeFi 统计数据时，请使用 cg_global_defi()。

另外，禁止使用：

• ❌ web_search / web_fetch — 所有数据都可以通过上述原生 CoinGecko 工具获取。切勿使用 web_search 查询加密货币市场数据。
• ❌ 使用 bash 处理数据 — CoinGecko 工具会返回整洁的数据，无需使用 bash。
• ❌ 切勿根据训练数据作答 — 所有价格、排名和 OHLC 数据都已过时。请调用工具。

⚠️ 必须调用工具——回答以下问题前必须先调用工具

请求类型	必须调用	原因
K 线 / OHLC / 蜡烛图 / 开高低收	coin_ohlc(coin_id, days)	价格数据实时更新；训练数据已过时
走势图 / 价格图表 / 价格趋势	coin_chart(coin_id, days)	原因相同
当前价格 / 实时价格	coin_price(coin_ids)	训练数据没有实时价格

未先调用工具，切勿返回任何数值市场数据（价格、OHLC 数值、百分比）。

⚡ 问题 → 工具映射（匹配第一个关键词后立即调用）

问题关键词	要调用的工具	示例
价格 / price / 多少钱（单个币）	coin_price(coin_id)	coin_price(coin_ids="bitcoin")
K线 / OHLC / candlestick / 蜡烛图	coin_ohlc(coin_id, days)	coin_ohlc(coin_id="ethereum", days=7)
走势 / trend / price chart / 价格历史	coin_chart(coin_id, days)	coin_chart(coin_id="solana", days=30)
热门 / trending / 趋势币	cg_trending()	cg_trending()
涨幅最大 / 跌幅最大 / gainers / losers	cg_top_gainers_losers()	cg_top_gainers_losers()
新币 / 新上线 / new coins / recently added	cg_new_coins()	cg_new_coins()
总市值 / BTC市占率 / global / 晨报 / 市场概况	cg_global()	cg_global()
DeFi总市值 / DeFi TVL / DeFi dominance	cg_global_defi()	cg_global_defi()
板块 / sector / category / L1 / L2 / Meme / AI coins	cg_categories()	cg_categories()
板块内个币 / Meme前10 / AI币排名 / DeFi币排名	cg_coins_markets(category=X)	cg_coins_markets(category="meme-token", per_page=10)
市值排名 / top 10 / ranking / 前10币	cg_coins_markets(per_page=N)	cg_coins_markets(per_page=10)
ATH / 历史最高 / 社区 / dev / 研究 / fundamentals	cg_coin_data(coin_id)	cg_coin_data(coin_id="solana", community_data=True)
对比两个币 / compare / XX vs YY	cg_coin_data() × 2	每个币调用一次
NFT排名 / NFT市场 / floor price / top NFTs	cg_nfts_list()	cg_nfts_list()
某个NFT（BAYC/Punks/Azuki）	cg_nft(nft_id)	cg_nft(nft_id="bored-ape-yacht-club")
交易所详情 / Binance详情 / exchange data	cg_exchange(exchange_id)	cg_exchange(exchange_id="binance")
交易所列表 / exchange ranking	cg_exchanges()	cg_exchanges()
交易对 / trading pairs / 流动性分布	cg_coin_tickers(coin_id)	cg_coin_tickers(coin_id="bitcoin")
交易所交易量趋势 / volume chart	cg_exchange_volume_chart(exchange_id)	cg_exchange_volume_chart(exchange_id="binance", days=30)
合约地址价格 / token price on-chain	cg_token_price(platform, contract)	cg_token_price(platform="ethereum", contract_addresses="0xa0b...")
搜索币 / 找币 / coin lookup / search	cg_search(query)	cg_search(query="pepe")
永续合约交易所 / derivatives exchange / OI排名	cg_derivatives_exchanges()	cg_derivatives_exchanges()
合约ticker / perpetual / funding / basis	cg_derivatives()	cg_derivatives()
交易所对比 + 永续交易所	cg_exchanges() + cg_derivatives_exchanges()	两个调用

衍生品：字段与全市场未平仓合约

cg_derivatives() 返回 {"tickers": [...], "count": N, "filter": "unexpired"}。每个 ticker：

字段	含义 / 单位
market	交易所，例如 "Binance (Futures)"
index_id	基础币种，例如 "BTC" — 按此分组统计每种币的总量
contract_type	"perpetual" 或 "futures"（有到期日）
open_interest	USD 名义价值
volume_24h	USD
funding_rate	已经是百分比，按每个资金费率间隔计算：0.006162 = 0.0062%。不要乘以 100
basis, spread	百分比
price	字符串 — 使用 float() 转换

全市场未平仓合约（当平台套餐无法使用 CoinGlass coins-markets 时使用）：

from collections import defaultdict
t = cg_derivatives()["tickers"]
perp = [x for x in t if x["contract_type"] == "perpetual" and x.get("open_interest")]
by_coin = defaultdict(float)
for x in perp:
    by_coin[x["index_id"]] += x["open_interest"]
total = sum(by_coin.values())          # ~$217B as of 2026-09

注意事项：

• 仅提供当前快照，没有历史数据。 如需未平仓合约历史数据，请使用 coinglass skill（按币种查询历史数据并求和）。
• 数据由交易所报告，包含小型交易所，因此数值显著高于 CoinGlass （同一天约为 2170 亿美元，而 CoinGlass 约为 1170 亿美元）。始终注明来源为“CoinGecko”，且不要将其与 CoinGlass 或其他第三方数据绘制在同一张图表上。
• 资金费率因交易所和保证金类型（USDT、USDC 或币本位）而异；如果报告单个币种的数据，请使用未平仓合约加权平均值，并注明这一点。

🌳 决策树

How many coins?
├─ ONE coin
│   ├─ Just price? → coin_price()
│   ├─ ATH/community/dev/deep? → cg_coin_data()
│   ├─ OHLC candles? → coin_ohlc()
│   ├─ Price trend? → coin_chart()
│   └─ Unknown ID? → cg_search() first
├─ MULTIPLE coins / ranking
│   ├─ Sector aggregate (板块总市值)? → cg_categories()
│   ├─ Sector individual (Meme前10)? → cg_coins_markets(category=X)
│   └─ General ranking? → cg_coins_markets(per_page=N)
├─ NFTs → cg_nfts_list() or cg_nft(nft_id)
├─ Exchange → cg_exchange(id) or cg_exchanges()
├─ Global → cg_global() or cg_global_defi()
└─ Token by contract → cg_token_price()

常见类别 ID

meme-token、artificial-intelligence、layer-1、layer-2、decentralized-finance-defi、gaming、real-world-assets-rwa

输出格式

• 价格：始终使用 $ 符号 → $66,697
• 百分比：始终使用 % → +4.2%
• NFT 地板价（ETH）：同时显示 USD → 5.17 ETH ($10,534)

重要说明

• CoinGecko 使用 slug ID：“bitcoin”、“ethereum”、“solana”。符号（BTC、ETH、SOL）会自动解析。
• 如果不确定某个币的 ID → 首先使用 cg_search(query="coin name")。
• 大多数问题只需调用 1-2 次工具。不要连续调用 3 次或更多。

常见问题

coin_price 因 ID 无效而失败

解决方案： 使用 cg_search(query="coin name") 查找正确的 CoinGecko ID，或直接使用符号（例如，'COMP'）。

---