端点
所有端点均为 GET、返回 JSON，且无需密钥。
| 端点 | 返回内容 |
|---|---|
| /api/v1/market | 指定范围的一页排名，附快照元数据 |
| /api/v1/cards/<id> | 以 id 取单张卡；未入榜则返回 404 及错误内容 |
查询参数
无效值一律返回 HTTP 400，不会悄悄退回默认值。
| 参数 | 可接受值 | 备注 |
|---|---|---|
| scope | all、pokemon、one-piece、watchlist | 其他值返回 400 |
| page | 正整数 | 非数字或 0 返回 400 |
| pageSize | 正整数 | 会被限制在服务器上限内 |
响应字段
市场响应会把卡片列表连同快照身份一并包起，让已存储的响应永远追溯得回产生它的那次构建。
| 字段 | 含义 |
|---|---|
| generation | 响应所属快照构建的标识 |
| generatedAt | 快照构建的时间 |
| effectiveAt | 数字所代表的日期 |
| coverage | 快照相对其声称范围的完整程度 |
| count | 本响应中的卡片数量 |
| cards | 已排名卡片，各自带有价格、评级数量与市值 |
请求示例
获取宝可梦范围的第一页：
curl -s "https://cardzmarketcap.com/api/v1/market?scope=pokemon&page=1"响应会在边缘短暂缓存。请以 effectiveAt 字段判断数字属于哪一天，而不是看响应时间。
更新频率
每日发布新快照，API 提供当前那一份。旧的 generation 不会由这些端点提供。
若你要存储响应，请连同 generation 与 effectiveAt 一起存。不同 generation 的两个数字，没有日期就不可比较。
合理使用
API 公开且免鉴权，所以请保持合理的请求频率：读一页、缓存起来，不要用快过数据变动的速度轮询。快照一日才动一次。
过量自动化流量可能被限速。若你需要整批访问，请先联系我们，不要用爬的。
出处标注与授权
数字可依 CC BY 4.0（https://creativecommons.org/licenses/by/4.0/）引用及转载，但须注明出处为 CardZ Marketcap，并链接回所引用的页面或端点。
标注时必须附上该数字的生效日期，因为市值每日重新计算。
标注格式
CardZ Marketcap，https://cardzmarketcap.com，数据截至 2026-08-28
可机读文件
供爬虫、智能体与语言模型使用：
- /llms.txt — 本站与主要页面的简短说明
- /llms-full.txt — 加长版本，附计算方法摘要
- /sitemap.xml — 所有可索引页面
CardZ Marketcap 是集换式卡牌的价格指数，不是加密货币、不是代币，也不是上市公司。本站没有任何代币代号，与名为 CARDS 的加密资产无关。
