认证与 API 密钥

什么是 API 密钥

API 密钥是你的代码发送给 Cognivo 的秘密凭证，我们据此知道某个请求来自你。每一次开发者 API 调用都要带上它。密钥归属于某个项目，而项目把你的密钥和它们的用量归拢在一起。

在第一次调用之前请先读本页；当你需要知道一个密钥被允许做什么时，或者当某个密钥可能已泄露、你需要把它关掉时，也请回来看这一页。

在哪里找到它

登录 Cognivo dApp，在左侧边栏打开 账户，然后进入 Developers。未登录时，该页面只显示一个介绍页面。

Developers 页面有四个标签页：密钥、Usage、端点 和 快速开始。本页涉及的所有操作都在密钥标签页上完成。

正式访问与你的积分余额

页面顶部的横幅直白地说明了访问模式：有些端点用任意有效密钥都免费，另一些则按每次成功调用从你的 Cognivo 积分余额中扣费。再往下，正式 API 访问 卡片确认正式密钥创建后立即可用。没有审批步骤，也没有等待名单。

旁边页面会显示你当前的积分余额、一个 充值积分 按钮和一个 企业级访问 按钮。企业级是唯一需要提交申请的访问路径，用于定制定价或更高的限额。其他一切都是自助的。

Live API access 面板，位于 Developers 页面靠下的位置。放大图片

每个 Cognivo 账户每天还会获得 5 个免费积分，它们在 UTC 午夜重置。余额如何运作请见 账单与积分包，各端点的价格请见 速率限制、错误与账单。

密钥标签页

从 项目 下拉框中选择一个项目，或用 新建项目 创建一个。密钥标签页随后会列出属于它的每一个密钥。

Developers 页面上的 Keys 标签页，列出属于所选项目的每一个密钥。放大图片

每一行密钥会显示你给它起的名称、它是测试密钥还是正式密钥、适用的每小时限额、它携带的权限，以及创建时间和最后使用时间。最后使用：从未 表示从来没有用该密钥发起过调用。

页面只显示密钥的前缀和最后四个字符。Cognivo 不会存储任何其他可以反读的内容，这也是完整密钥只出现一次的原因。

创建密钥

选择 + 新建密钥。表单要求填三项内容：一个可选的名称，帮助你区分自己的密钥；一个模式，测试 或 正式；以及至少一项权限。

Developers 页面上的新建密钥表单，通过 New key 按钮打开。放大图片

选择正式模式时，模式下拉框下方会显示你的积分余额，提醒你正式调用是真实调用，会从该余额中扣费。选择测试模式则会创建一个永不收费、限额很紧的沙盒密钥。

选择 创建密钥，完整密钥会在一个对话框中出现一次。

1. 趁密钥还显示在屏幕上，用复制图标复制完整密钥，它不会再次显示。
2. 把密钥保存到之后能找到的地方后，点击 Done。

Keys 标签页上的一次性密钥对话框，在新密钥创建的那一刻显示。放大图片

如果你弄丢了密钥，是无法找回的。请改为轮换密钥，下文有说明。

发送你的密钥

标准请求头是 X-API-Key：

curl -X POST 'https://api.cognivolabs.io/v1/api/intel/risk' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"chain":"eth","address":"0xTOKEN_CONTRACT"}'

对于偏好它的客户端库，Authorization: Bearer YOUR_API_KEY 也可作为别名使用。请把密钥留在你的服务器上，绝不要放进浏览器代码。

目前 API 覆盖 Ethereum、Base 和 BNB Chain。

权限

密钥采用默认拒绝策略。一个密钥只能调用你在创建时授予它的端点组。共有三项权限，每一项解锁一组端点。

情报（intel:read）是日常使用的权限。它回答"这个代币或钱包正在发生什么？"：价格下跌的驱动因素、风险信号、团队钱包行为、已实现盈亏，以及精确的资金动向。它解锁 POST /v1/api/intel/why-down、POST /v1/api/intel/team-wallets、POST /v1/api/intel/risk、POST /v1/api/wallet/pnl 和 POST /v1/api/wallet/exact-movements。

安全（security:read）让密钥可以查看某个钱包已经授权了什么，包括哪些合约可以花费它的代币，以及哪些额度是无限的。它是只读的。带有该权限的密钥永远无法转移资金，也无法撤销授权。它解锁 POST /v1/api/wallet/approvals。

Liquidity（liquidity:read）让密钥可以读取资金池背景、LP 托管情况，以及锁仓和销毁背景。它解锁 POST /v1/api/intel/liquidity。

GET /v1/api/health 完全不需要密钥。GET /v1/api/me 和 GET /v1/api/discover 用任何有效密钥都能调用，无论它带有什么权限。

权限在密钥创建时就固定了。要更改权限，请用你需要的权限创建一个新密钥，然后吊销旧的。调用失败并返回 403 scope_denied，表示该密钥不具备这个端点所需的权限。

测试密钥与正式密钥

前缀	用途	计费	速率上限
cogv_test_	试用 API。在门户中标记为测试和沙盒。无法运行正式情报调用。	从不收费	25 次请求/小时，100 次/天，1 次/秒
cogv_live_	真实流量。自助开通，立即可用。	按每次成功调用消耗 Cognivo 积分。失败的调用从不收费。	起步为每小时 1,000 次请求，参见速率限制

测试密钥不是免费的生产密钥。用它发起的正式调用会返回 403 sandbox_limited。目前 Developer API 调用的计费处于关闭状态，因此成功调用不会扣除任何积分，你的余额也不会变化。

门户还会在每个密钥上显示访问模式。付费 是普通的按量付费。试用 是有结束日期的临时评估额度。合作伙伴 和 企业级 是与 Cognivo 约定的安排。已暂停 表示该密钥无法执行任何操作，门户会显示原因。少量较老的密钥早于自助计费，只能调用元数据端点，因此正式调用会返回 403 access_required。创建一个新的正式密钥即可把它们迁移到按量付费。

GET /v1/api/me 会报告你的密钥的访问模式、它的权限、你的 credits_balance 以及充值指引。如果你的余额不足以支付一次调用，你会收到 402 payment_required，且不会扣费。充值后重试即可。

轮换与吊销

这两个控件都位于每行密钥的右侧。

1. 看名称旁边的 Test 和 Sandbox 徽标，就知道这是哪一类密钥，旁边还显示了每小时限额。
2. 点击 Rotate 用一个新密钥替换这个密钥，新密钥只显示一次，旧密钥会立即失效。
3. 点击 Revoke 永久停用某个密钥，例如它已经不再需要，或者你认为别人看到过它。

Developers 页面 Keys 标签页上的密钥行。放大图片

轮换会先要求你确认，对话框会准确说明将会发生什么。

Keys 标签页上的轮换确认框，在你对某个密钥点击 Rotate 后显示。放大图片

轮换后的密钥会保留它的名称、权限、层级、任何网络限制、任何过期日期以及任何剩余额度，因此轮换是安全的，绝不会悄悄放宽该密钥能做的事。替代密钥会在同一个对话框中显示一次，和新密钥一样。吊销是永久性的，会立刻让该密钥在所有端点上停止工作。

一旦怀疑泄露就轮换，并且按固定周期定期轮换。

Cognivo 可以对密钥施加的限制

这些限制设置在密钥记录上，而不是门户表单里，并且会在每一次请求上强制执行。你可以用 GET /v1/api/me 确认自己的密钥适用哪些限制。

• 网络限制。 密钥可以被限定在特定网络上。指名了其他网络的请求会被拒绝，返回 403 chain_denied。这个拒绝发生在 Cognivo 调用任何上游服务之前，也在消耗任何额度之前，所以你的密钥无权发起的调用永远不会让你花钱。报告字段为 allowed_chains，其中 null 表示没有限制。
• 过期时间。 密钥可以设定一个结束日期。过了这个日期，密钥在所有地方都会停止工作，包括 GET /v1/api/me，并返回 403 key_expired。报告字段为 expires_at，其中 null 表示不会过期。如果试用额度也有结束日期，则以较早的那个为准。
• 来源和 IP 允许列表。 密钥可以被限定到特定来源，包括像 https://*.yourapp.com 这样的通配符子域名，或者限定到特定 IP 地址和 CIDR 范围。来自其他任何地方的请求都会被拒绝，返回 403 origin_denied。空列表表示没有限制。

下一步

拿到密钥后，就到 快速开始 完成你的第一次调用，然后浏览 端点参考 看看每个端点返回什么、花费多少。如果某次调用返回了你不认识的错误代码，速率限制、错误与账单 列出了其中的每一个。