跳到主要内容

认证与 API 密钥

发送密钥​

标准请求头是 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 也可作为别名使用。

密钥如何存储​

Cognivo 从不存储你的完整密钥。只保留单向哈希、前缀和最后四个字符，这也是为什么完整密钥只能在创建时显示一次。请像对待密码一样对待它。

沙盒密钥与正式密钥​

前缀用途收费速率上限
cogv_test_沙盒：在实时链上数据上做集成测试不收费；仅在管理员启用后才能运行少量实时演示额度硬性上限 25 次请求/小时和 100 次/天
cogv_live_生产环境付费使用按每次成功调用消耗 Cognivo 积分计费；失败的调用不收费你的访问模式限额

两种环境访问的是同样的实时链上数据和同样的端点，区别在于速率上限和访问模式。用沙盒密钥开发，用正式密钥上线。

访问模式，一目了然​

  • 免费密钥 - 仅可探索：文档、GET /v1/api/health、GET /v1/api/me，以及有限的沙盒/演示调用。可执行的情报端点会返回明确的错误（例如 403 access_required），而不是免费运行。
  • 试用 - 由管理员授予，有限且会过期；可用于评估实时情报端点。
  • 付费 - 按每次成功调用消耗 Cognivo 积分，费用见公布的各端点价格；失败的调用不收费。
  • 合作伙伴 / 企业级 - 定制定价、更高的限额和按端点划分的访问权限；请在 Developer 门户申请访问。

权限范围（scope）​

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

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:read - 流动性与 LP 读取​

让你的密钥可以检查一个代币的流动性是否真实、LP 代币在哪里：资金池情况、LP 托管、锁仓与销毁情况。

解锁：POST /v1/api/intel/liquidity

GET /v1/api/health 完全不需要密钥；GET /v1/api/me 和 GET /v1/api/discover 用任意有效密钥都能调用，与其权限范围无关。

你可以随时在门户中编辑密钥的权限范围。如果调用以 403 scope_denied 失败，只是说明该密钥没有携带这个端点所需的权限范围。

轮换与吊销​

  • 吊销（Revoke） 会终止一个密钥。它在一分钟内即无法再通过认证。
  • 轮换（Rotate） 会创建一个同名、同权限范围、同层级的替代密钥，只显示一次，并在同一步骤中吊销旧密钥。怀疑泄露时使用，也建议定期执行。

可选的访问限制​

针对每个密钥，你还可以额外配置白名单：

  • 来源（Origin）（精确来源，或如 https://*.yourapp.com 的通配符子域名） - 携带其他 Origin 的请求会被拒绝。
  • IP / CIDR 网段 - 来自其他地址的请求会被拒绝。

列表为空表示不做限制。

密钥从哪里来​

密钥只能通过自助的 Developer 门户、使用你已有的 Cognivo 账户创建。新集成没有人工/遗留方式的密钥发放。