端点参考

本页是什么

Cognivo 开发者 API 让你自己的代码可以向 Cognivo 提出应用里能回答的同样问题。所有端点都位于 https://api.cognivolabs.io/v1/api 之下。

当你想让一次 Cognivo 检查在应用之外的地方运行时就用它：在你自己的机器人里、一个看板里、一个表格任务里，或者一个每晚监控代币清单的脚本里。

情报端点都是带 JSON 请求体的 POST。这是刻意为之：链接预览、爬虫或浏览器预取永远不可能通过加载一个 URL 触发一次执行。GET 只存在于 health、me 和 discover。

在应用中的位置

Developers 页面打开 Endpoints 标签页，显示一张 Permissions explained 卡片，内含 Intelligence、Security 和 Liquidity 分组，下方两个接口条目均标记为 Free。 — Developers 页面上的 Endpoints 标签页，这里列出每个 Cognivo 接口所需的权限及其费用。放大图片

这个标签页是一份参考，不是一个运行器。它列出了每一个正式端点，附带可复制的示例、密钥所需的权限，以及以积分计的价格。权限说明 卡片把这些权限归为三类：情报（为什么下跌、团队钱包、风险、钱包盈亏、精确资金动向）、安全（代币授权）和 Liquidity（流动性、锁仓与销毁）。只给每个密钥它真正需要的权限。

更想要机器可读的版本？完整的 OpenAPI 规范覆盖了本页的全部内容。

响应信封

每个端点都用同一种信封结构作答。下面示例中的 id 和时间戳都是占位值。成功时：

{
  "ok": true,
  "data": { "...": "the result" },
  "meta": {
    "chain": "base",
    "request_id": "capi_9f2c41d8a0b34e7c9d5a1f02",
    "credits_charged": 2,
    "generated_at": "2026-07-09T00:00:00.000Z"
  }
}

data 是结果本身。它的结构因端点而异。
meta.request_id 是这次调用的唯一 id。请保留它，支持团队可以凭它追溯一次调用。
meta.credits_charged 是这次调用的花费：成功的付费调用为该端点的价格，免费端点以及任何失败或诚实为空的结果则为 0。
meta.generated_at 是结果生成的时间。
meta.chain 出现在与网络相关的调用上，meta.sources 则在结果引用了来源时出现。

失败时：

{ "ok": false, "error": "invalid_chain", "message": "chain must be one of: eth, base, bsc", "request_id": "capi_..." }

error 是稳定的机器可读代码。message 是可选的人类可读提示。完整列表见速率限制与错误。

常见请求体字段

chain 取值为 eth（Ethereum）、base（Base）或 bsc（BNB Chain）之一，且不区分大小写。
address、wallet 和 token 是 40 个十六进制字符的 0x EVM 地址。

每个示例都使用占位符 YOUR_API_KEY。在真实代码中，请从环境变量或密钥管理服务加载密钥。绝不要硬编码。

每个端点的费用

正式密钥是自助开通、按量付费的。新建的正式密钥可以立刻运行这些端点，每一次成功的调用都会从你的账户余额中以 Cognivo 积分扣费。失败的调用从不收费，而成功的调用恰好只扣一次费，所以同一操作被重复提交也不会向你重复收费。

每个账户每天获得 5 个免费积分，它们在 UTC 午夜重置。如果你的余额不足以支付一次调用，你会收到 402 payment_required，且不会扣费。请在账户账单页面充值后重试。沙盒（cogv_test_）密钥无法运行正式情报调用。参见账单与积分包。

端点	每次成功调用消耗的积分
`POST intel/liquidity`	2
`POST intel/risk`	2
`POST wallet/approvals`	2
`POST intel/why-down`	3
`POST intel/team-wallets`	5
`POST wallet/exact-movements`	5
`POST wallet/pnl`	10
`POST contract/analysis`	免费
`GET health`、`GET me`	免费
`GET discover`	免费，但速率上限很紧

服务

GET /v1/api/health

检查 Cognivo API 是否在运行。不需要 API 密钥。

curl 'https://api.cognivolabs.io/v1/api/health'

const res = await fetch("https://api.cognivolabs.io/v1/api/health");
const json = await res.json();

响应，按设计不使用标准信封：

{ "ok": true, "service": "cognivo-public-api", "version": "v1", "generated_at": "2026-07-09T00:00:00.000Z" }

如果公开 API 被关闭，这里同样会返回 404 public_api_disabled，所以这个端点也可以兼作可用性检查。

GET /v1/api/me

显示调用方密钥的详情：它的层级、权限和速率限制。任何有效密钥都能用，并且免费。对于自助开通的正式密钥，它还会显示所属账户的 credits_balance 和 top_up 指引，以及该密钥的 access_mode。

curl 'https://api.cognivolabs.io/v1/api/me' \
  -H 'X-API-Key: YOUR_API_KEY'

const res = await fetch("https://api.cognivolabs.io/v1/api/me", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const json = await res.json();

{
  "ok": true,
  "data": {
    "key": "cogv_live_****abcd",
    "project_id": "…",
    "environment": "live",
    "tier": "basic",
    "access_mode": "live",
    "scopes": ["intel:read", "liquidity:read"],
    "rate_limit_per_hour": 1000,
    "credits_balance": 1250,
    "top_up": "Manage credits from your Cognivo account billing page."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

限制：它只显示掩码后的密钥，绝不会显示完整的密钥内容。credits_balance 可能返回 null，这表示 Cognivo 在那一刻读不到余额，而不是余额为零。

其余端点的调用形式都和下面的示例相同。替换路径和请求体字段即可。

代币情报

POST /v1/api/intel/why-down，权限情报（`intel:read`）

用日常语言解读一个代币价格为什么在下跌，依据是近期的链上活动：大量抛售、流动性被抽走、所有者或团队钱包在动。

标价：每次成功调用 3 积分。失败的调用从不收费。目前 Developer API 调用的计费处于关闭状态，因此成功调用不会扣除任何积分，你的余额也不会变化。

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

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/why-down", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();

响应：标准信封。data 中是主导因素以及支撑它的链上观察，并会设置 meta.chain。

限制：这项解读需要近期活动才能给出有用的结论，所以交易历史极少的代币只会得到很单薄的答案。这些是信号，不是投资建议。

POST /v1/api/intel/team-wallets，权限情报（`intel:read`）

呈现与某个代币的团队或金库相关联的钱包：部署者、所有者和控制者钱包，以及它们近期在做什么。

标价：每次成功调用 5 积分。失败的调用从不收费。目前 Developer API 调用的计费处于关闭状态，因此成功调用不会扣除任何积分，你的余额也不会变化。

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

响应：标准信封。data 列出识别到的钱包及其近期行为，通常还带有 meta.sources。

限制：钱包是通过部署、所有权和控制等链上关系识别出来的。Cognivo 看不到链下的团队结构，所以空列表意味着在链上没有可关联的对象，而不是说这个代币没有团队。

POST /v1/api/intel/liquidity，权限 Liquidity（`liquidity:read`）

用链上证据检查一个代币的流动性、锁仓和销毁情况：资金池背景、谁持有 LP 代币，以及锁仓或销毁的背景。

标价：每次成功调用 2 积分。失败的调用从不收费。目前 Developer API 调用的计费处于关闭状态，因此成功调用不会扣除任何积分，你的余额也不会变化。

可选的布尔值 metadata、locks 和 full 会分别加入资金池元数据、带时间的锁仓证明，以及可得的最完整解读。

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

响应：标准信封。data 中是代币身份、市场快照，以及带锁仓或销毁背景的 LP 托管情况。

限制：v1 不提供深层的历史销毁溯源。锁仓背景覆盖的是已识别的锁仓器模式，所以一个不常见的自定义锁仓器可能被读成普通托管而非锁仓。请把这读作"未核实"，而不是"未锁定"。

POST /v1/api/intel/risk，权限情报（`intel:read`）

针对代币合约的 Cognivo 风险信号，能识别网络，并以红旗解读作为兜底。

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":"bsc","address":"0xTOKEN_CONTRACT"}'

响应：标准信封。data 中是为该代币找到的信号和标记。

限制：干净的结果并不意味着这个代币是安全的。它意味着在读取的那一刻没有发现已知的红旗。

POST /v1/api/contract/analysis，权限合约（`contract:read`）

针对某个合约地址的合约与控制权证据：它是否存在、谁拥有它、所有权是否已放弃、它是不是代理合约以及由谁管理、谁部署了它、哪些钱包可以被归因为控制者或团队，以及源码是否已验证。

费用：0 积分。这个端点按决策在所有套餐上都免费。不会扣除任何积分。

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

响应：标准信封。data 中包含 contract、ownership、proxy、deployer、controllers、source_verification、limitations 和 unavailable。

每个字段都会告诉你它从哪里来。meta.provenance 把每个字段映射到下列之一：

标签	含义
`verified_onchain`	在你请求的那一刻从该网络的节点读取。这是事实。
`augmented`	Cognivo 增强情报：由外部来源提供，经过交叉核对但未被 Cognivo 证实。
`interpretation`	Cognivo 对事实的解读。这是判断，不是事实。
`unavailable`	Cognivo 无法获取这一项。原因在 `data.unavailable` 中。

不会有任何内容是猜测的、取默认值的，或者为了填补空缺而返回零的。

meta.chain_data_source.cognivo_grounded 告诉你这次读取所依赖的基础设施是否由 Cognivo 自己运行。Cognivo 运行着自己的 Ethereum 节点，所以 Ethereum 的读取为 true。Base 和 BNB Chain 的读取来自外部 RPC 基础设施，所以为 false。那些读取是准确的，但并非由 Cognivo 掌控的硬件提供，Cognivo 会明说这一点，而不是让你自行假设。

在 Base 上的限制，同样会在 data.limitations 中返回：

深层控制者关系图仅限 Ethereum。在 Base 上，控制者和团队归因来自范围更窄的钱包角色解读。
Base 上的部署者证据来自外部来源，而不是 Cognivo 的归档读取。请把它当作有力线索，而不是已证实的事实。
Base 上不解码流动性锁仓计划。请用 POST /v1/api/intel/liquidity 获取 LP 托管和销毁证据，不要把缺失的锁仓读成没有锁仓。

这个端点只报告合约控制权证据。它对流动性只字不提，而且干净的结果绝不意味着这个合约是安全的。

只读：不签名任何东西，不构建交易，不广播任何内容，也不会委托任何钱包。

钱包情报

POST /v1/api/wallet/pnl，权限情报（`intel:read`）

针对一个钱包在一个代币上的盈亏，依据有据可查的链上兑换计算。wallet 和 token 两者都是必填。

标价：每次成功调用 10 积分。失败的调用，以及 422 无数据结果，从不收费。目前 Developer API 调用的计费处于关闭状态，因此成功调用不会扣除任何积分，你的余额也不会变化。

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/pnl' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","wallet":"0xWALLET","token":"0xTOKEN_CONTRACT"}'

响应：标准信封。data 中是已实现的数字，以及在存在站得住脚的成本基准时，仍持有仓位的未实现数字。

限制：当无法建立站得住脚的成本基准时，未实现数字会返回 null，而不是编造一个数字。当该钱包在那个代币上完全没有可定价的交易时，调用会返回 422（例如 insufficient_data），这表示 Cognivo 无法算出一个公允的数字，而不是说利润为零。422 从不收费。Cognivo 无法定价的兑换会被标为未定价，而不是被丢弃。

POST /v1/api/wallet/approvals，权限安全（`security:read`）

列出某个钱包已授予的代币花费授权，并标记出无限额度。

可选的 limit 和 offset 用于对大量授权做分页。

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

响应：标准信封。data 中是授权列表，含花费方、代币和额度背景。

限制：这是只读的。Cognivo 从不转移资金，也无法替你撤销授权。撤销永远要从你自己的钱包完成。空列表是一个有效的成功答案，并且不收费。

POST /v1/api/wallet/exact-movements，权限情报（`intel:read`）

列出一个钱包精确的代币动向：买入、卖出和转账。token 是可选的，用来把读取范围收窄到一个代币。

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/exact-movements' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","wallet":"0xWALLET"}'

响应：标准信封。data 中是带计数的动向列表。

限制：该调用返回最近的动向，每次调用最多 25 条。没有匹配动向的钱包会返回 422，而不是编造一段历史。

Discover

GET /v1/api/discover

公开的 Discover 信息流：近期匿名化的链上情报卡片，每张都带有代币身份、一个引子和要点。任何有效密钥都能用。免费，但有很紧的每日限额。

查询参数：limit（1 到 50，默认 20）和可选的 chain（eth、base、bsc）。

curl 'https://api.cognivolabs.io/v1/api/discover?limit=10&chain=base' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "ok": true,
  "data": { "cards": [ { "...": "public intelligence card" } ], "total": 10 },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

限制：超出 1 到 50 范围的 limit 值会被夹回区间内。信息流只包含用户选择公开的情报，所以它是一个样本，不是完整覆盖。

尚未提供

以下内容为透明起见列出，目前不返回任何东西：

通过 API 进行的深度钱包追踪（wallet/trace）。异步任务流程目前仅限 Chat 和应用。
按 id 获取报告（reports/:id）。
Webhook。
Solana 端点。

下一步

用快速开始完成你的第一次调用，在认证与 API 密钥创建并限定密钥权限，在把任何东西放上定时任务之前，先读一读速率限制与错误。

本页是什么​

在应用中的位置​

响应信封​

常见请求体字段​

每个端点的费用​

服务​

GET /v1/api/health​

GET /v1/api/me​

代币情报​

POST /v1/api/intel/why-down，权限 情报（intel:read）​

POST /v1/api/intel/team-wallets，权限 情报（intel:read）​

POST /v1/api/intel/liquidity，权限 Liquidity（liquidity:read）​

POST /v1/api/intel/risk，权限 情报（intel:read）​

POST /v1/api/contract/analysis，权限 合约（contract:read）​

钱包情报​

POST /v1/api/wallet/pnl，权限 情报（intel:read）​

POST /v1/api/wallet/approvals，权限 安全（security:read）​

POST /v1/api/wallet/exact-movements，权限 情报（intel:read）​

Discover​

GET /v1/api/discover​

尚未提供​

下一步​