跳转到主要内容

​
API 密钥

除发往 /api/v1/public/status 的请求（无需密钥）外，每个发往 /api/v1/public/ 端点的请求都通过 X-API-Key header 中的密钥进行认证。/api/v1/x402/ 下按次付费的路由不需要密钥（见通过 x402 按次付费）：
密钥是形如 cck_ 后接 56 个十六进制字符的字符串。不支持 Authorization: Bearer。在浏览器中，Bearer token 会返回 401。 在 curl 或 python-requests 这类命令行客户端中，请求会在更前面的一层被拒绝， 返回 403 {"error":"Forbidden"} 且没有 code 字段，因为没有携带 X-API-Key 的请求根本不会被识别为 API 客户端。 请始终发送 X-API-Key。 你可以在 cctools.network/profile/api 创建、列出和吊销密钥。 明文密钥只在创建时显示一次， 之后就只能看到前缀。 拿到密钥后，可以在 cctools.network/api-docs 用它在浏览器中调用任意 endpoint。 你能同时持有多少个有效密钥取决于你的套餐；各套餐的数量见套餐与限制。 每分钟限制按密钥和 endpoint 计算，因此每多一个密钥就多一份吞吐量； 每日限制则按整个账户计算，不会随密钥数量增加。

​
套餐

你的密钥拥有你账户的套餐，套餐决定你的速率限制， 并在每个响应中以 meta.tier 的形式返回。
没有按密钥限制并不等于没有限制。在所有套餐（包括 Validator）上， 每一个发往 /api/ 的请求也都计入 每个 IP 每分钟 600 次请求 的上限。 持续超限会升级为对该 IP 的临时封禁，因此遇到 429 时应当退避， 而不是立即重试。如果你计划的数据回填需要超过这个量， 请先联系我们。
这两种限制的计数方式不同。每分钟限制按密钥和 endpoint 计算。 每日限制按账户在一个 UTC 日内计算，你所有密钥的调用会累加。 每个套餐可以用来做什么。 评估密钥用于测试，Pro 供个人使用。Data 套餐允许对 endpoint 参考中“用途”列标为 Data 套餐 的 endpoint 进行商业使用，需署名； 标为 个人使用 的 endpoint 在所有套餐上都只供个人使用。条款见 cctools.network/terms/api，数字和价格见 套餐与限制。 Free 套餐已经结束。用它创建的密钥会返回 401，代码为 tier_retired， 并带有指向各套餐的 renew_url：请选择一个套餐，然后创建新密钥。

​
如何获得套餐

打开 /profile/api。套餐面板会显示你的账户可以选择什么， 在账户拥有套餐之前，New key 保持不可用。
  • Pro：拥有 CCTools Pro 订阅时，套餐面板会把 Pro 显示为你的套餐。点击一次 Set up keys（曾持有 Free 或评估密钥的账户会看到 Upgrade to Pro tier），然后点击 New key。
  • Evaluation：想在购买前测试 API，请向我们团队申请评估密钥。从未持有过套餐的账户在该页面提交申请；其他账户请联系我们。评估密钥由我们团队按申请签发，仅供测试；有效期见套餐与限制。
  • Data Starter 和 Data Team：Buy Data Starter 或 Buy Data Team，用 Canton Coin 支付，按月或按年。付款时你需要接受 API 条款。Data 套餐的付款不予退款，法律要求退款的情形除外。套餐不会自动续订：除非你续订，访问权限在周期结束时终止。在相同或更大的 Data 套餐生效期间购买的 Data 套餐，在该套餐结束时开始。正在运行的较小 Data 套餐会在较大的 Data 套餐运行期间暂停，并在其结束后继续。
  • Validator：在同一页面提交 party ID。
  • Enterprise：联系我们。
需要的比套餐提供的更多？请通过 cctools.network/contact 联系我们了解 Enterprise。 我们直接签发给组织的密钥归属于该组织而不是某个人， 因此它们不跟随任何账户的套餐， 服务器到服务器的集成也不需要维持任何东西。 密钥会在被吊销或到期时停止工作；套餐密钥在其套餐结束时到期（401，代码为 plan_ended）。 你的密钥跟随你账户的套餐，数量以该套餐允许的密钥数为限。 你创建的密钥采用你账户当前套餐的限制， 并在该套餐的覆盖期结束前一直有效。如果你持有的密钥超过套餐允许的数量，最近使用过的会保留，其余的会终止。当你续订 Pro 或购买 Data 套餐时， 你现有的密钥会采用新的覆盖期，所以无需再创建新密钥：续订 Pro 之后， 在 /profile/api 点击 Extend access， 你的密钥就会相应延长。点击它永远不会降级任何东西：授予你账户的 Validator 或 Enterprise 套餐会保持不变。当没有任何套餐剩余时，你的密钥会返回 401， 代码为 plan_ended 并带有 renew_url。续订 Pro 或 Data 套餐后它们会恢复可用；已结束的评估由我们团队延期，请联系我们。

​
速率限制

有两种限制会计入你的调用。 每分钟限制按密钥、按 endpoint、按分钟、并且按进程计算。 API 以多进程集群的方式运行，每个进程各自维护自己的计数器， 因此把请求分散到多个连接上的客户端，可能在触发任何拦截之前就超过标称数值。 请把这个数字当作设计时应遵循的持续速率， 而不是一个可以去试探的上限。 当你确实超限时，你会收到 429 以及 Retry-After: 60 header：
每日限制按账户在一个 UTC 日内计算，从 00:00 到 24:00 UTC。 你所有密钥的调用会累加（由我们团队签发的密钥有自己的上限）， 被某个限制拒绝的调用不计数。超过上限时，你会收到 429，代码为 daily_limit， Retry-After 为距离 00:00 UTC 剩余的秒数，并带有 X-RateLimit-Remaining-Day: 0：
如果当天额度已经用完，被每分钟限制拒绝的请求同样返回 daily_limit，Retry-After 也相同。 有每日上限的密钥，在每个成功响应以及两种 429（rate_limited 和 daily_limit）上都会带有 X-RateLimit-Limit-Day 和 X-RateLimit-Remaining-Day；如果无法读取计数器，则只发送 X-RateLimit-Limit-Day。 每个成功的响应也会在 meta.rate_limit_remaining 中携带你的上限。 在没有按密钥限制的套餐上，该字段为 null，因此请把它的类型定义为可空。 meta.daily_limit_remaining 是你今天还剩的调用次数；当你的套餐没有每日上限， 或计数器无法读取时为 null。
尽管名字叫 remaining，rate_limit_remaining 实际上是你的上限，而不是倒数。 它在每个响应中返回相同的数字，从不递减，因为精确的逐请求计数会在热路径上 多出一次数据库读取。不要把逻辑建立在它逐渐接近零上，因为那永远不会发生。 请把 429 及其 Retry-After header 作为你真正的退避信号。 daily_limit_remaining 是例外：它确实会递减。

​
错误

大多数错误都带有 { "error": "...", "code": "..." }，但 code 是针对具体 endpoint 的，而不是取自一个固定列表。 请基于稳定的 HTTP 状态码来分支，把 code 当作细节信息。 有两种响应来自处理程序运行之前的边缘层，它们只带 { "error" }， 完全没有 code：面向无密钥工具客户端的 403， 以及针对每个 IP 上限的 429。

​
良好实践

绝不要把密钥打包进浏览器端代码或移动应用。请通过你自己控制的后端代理。 泄露的密钥在你吊销它之前，可以一直被用到其速率限制的上限。
吊销是立即生效的：密钥会马上开始返回 401。 请先生成一个替换密钥，完成切换，然后再吊销旧的那个。
请遵守 Retry-After。对于稳定的工作负载， 应保持在你的套餐限制之内，而不是先突发再退避。
Canton 是 Digital Asset (Switzerland) GmbH 的注册商标。Digital Asset 与 CCTools 没有关联，也未赞助或认可 CCTools。