端点参考

所有端点都位于 https://api.cognivolabs.io/v1/api 之下。情报端点使用带 JSON 请求体的 POST（这可以防止链接预览、爬虫和预取器意外触发执行）。GET 仅用于 health、me 和 discover。

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

响应信封

每个端点都用相同的信封结构应答。成功时：

{
  "ok": true,
  "data": { "...": "the result" },
  "meta": {
    "chain": "base",
    "request_id": "capi_9f2c41d8a0b34e7c9d5a1f02",
    "credits_charged": 0,
    "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、base、bsc 之一（不区分大小写）
• address / wallet / token - 一个 0x… 开头的 EVM 地址（40 个十六进制字符）

下面所有示例都使用占位符 YOUR_API_KEY；在真实代码中，请从环境变量或密钥管理器加载密钥，绝不要硬编码。

访问与积分费用

可执行的情报端点需要 trial、partner、付费或 enterprise 访问。没有访问授权时它们不会免费运行：你会收到明确的 403 错误，例如 access_required（见速率限制与错误）。付费使用按每次成功调用以 Cognivo 积分计费；失败的调用不收费。各端点的费用（适用于付费使用；为透明起见公示）：

端点	每次成功调用的积分
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
GET health、GET me	免费
GET discover	免费，但速率上限很严格

服务

GET /v1/api/health

存活探针。无需 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

查询调用方密钥的信息。权限范围：任意有效密钥。免费。对于自助式 live 密钥，还会显示所属账户的 credits_balance（暂时不可用时为 null）和 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": "Top up Cognivo credits on your account billing page in the dApp."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

局限：只显示掩码后的密钥，绝不返回完整的密钥内容。credits_balance 是所属账户的 Cognivo 积分余额，暂时不可用时可能为 null。

代币情报

POST /v1/api/intel/why-down - 权限范围 intel:read

这个代币为什么在跌：基于近期链上活动的有据解读，寻找主导因素（抛售、撤走 LP、所有者资金动向）。

访问与费用：需要实时访问授权（trial、partner、付费或 enterprise）；付费使用时每次成功调用计 3 积分。

请求体：

{ "chain": "base", "address": "0xTOKEN_CONTRACT" }

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

对一个代币做团队及控制者钱包扫描：部署者、所有者和控制者钱包，以及它们近期的行为。

访问与费用：需要实时访问授权（trial、partner、付费或 enterprise）；付费使用时每次成功调用计 5 积分。

请求体：

{ "chain": "eth", "address": "0xTOKEN_CONTRACT" }

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"}'

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

响应：标准信封；data 列出识别到的团队/控制者钱包及其近期行为，通常带有 meta.sources。

局限：钱包识别基于链上关系（部署、所有权、控制权），无法看到链下的团队结构。

POST /v1/api/intel/liquidity - 权限范围 liquidity:read

代币的资金池/LP 状态：资金池情况、LP 托管以及锁仓/销毁情况。

访问与费用：需要实时访问授权（trial、partner、付费或 enterprise）；付费使用时每次成功调用计 2 积分。

请求体（可选布尔值 metadata、locks 和 full 分别追加有据的资金池元数据、定时锁证明，以及可用的最完整解读）：

{ "chain": "base", "address": "0xTOKEN_CONTRACT", "locks": true }

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}'

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

响应：标准信封；data 包含代币身份、市场快照，以及 LP 托管和锁仓/销毁情况。

局限：v1 不暴露深层的历史销毁溯源；锁仓情况覆盖已识别的锁仓器模式，未被识别的自定义锁仓器可能被解读为未锁定的托管。

POST /v1/api/intel/risk - 权限范围 intel:read

针对代币的链感知 Cognivo 风险信号（以红旗信号解读作为兜底）。

访问与费用：需要实时访问授权（trial、partner、付费或 enterprise）；付费使用时每次成功调用计 2 积分。

请求体：

{ "chain": "bsc", "address": "0xTOKEN_CONTRACT" }

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"}'

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

响应：标准信封；data 包含针对该代币发现的风险信号和标记。

局限：干净的结果绝不等于"安全"，它只表示在读取时没有发现已知的红旗信号。

钱包情报

POST /v1/api/wallet/pnl - 权限范围 intel:read

某个钱包在单个代币上的已实现盈亏，基于有据可查的钱包活动计算。wallet 和 token 都是必填项。

访问与费用：需要实时访问授权（trial、partner、付费或 enterprise）；付费使用时每次成功调用计 10 积分。

请求体：

{ "chain": "base", "wallet": "0xWALLET", "token": "0xTOKEN_CONTRACT" }

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"}'

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

响应：标准信封；data 包含该钱包/代币组合的已实现盈亏计算结果。

局限：当钱包在该代币上没有可定价的交易、无法计算出公允数字时，返回 422（例如 insufficient_data）。Cognivo 从不编造数字，422 也永远不收费。仅计算已实现盈亏；未实现（仍持有）的头寸不在此估值。

POST /v1/api/wallet/approvals - 权限范围 security:read

某个钱包名下的代币授权，并标记无限额度授权。只读：Cognivo 从不转移资金，也无法替你撤销授权。

访问与费用：需要实时访问授权（trial、partner、付费或 enterprise）；付费使用时每次成功调用计 2 积分。

请求体（limit 和 offset 可选，用于对大量授权分页）：

{ "chain": "eth", "address": "0xWALLET" }

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"}'

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

响应：标准信封；data 包含授权列表，含被授权方（spender）、代币和额度信息。

局限：空结果（未发现授权）是有效且成功的应答，不会被收费。

POST /v1/api/wallet/exact-movements - 权限范围 intel:read

某个钱包精确的近期资金动向（所有者/部署者式解读）。token 为可选项，用于把解读收窄到单个代币。

访问与费用：需要实时访问授权（trial、partner、付费或 enterprise）；付费使用时每次成功调用计 5 积分。

请求体：

{ "chain": "base", "wallet": "0xWALLET", "token": "0xTOKEN_CONTRACT" }

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"}'

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

响应：标准信封；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'

const res = await fetch("https://api.cognivolabs.io/v1/api/discover?limit=10&chain=base", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const json = await res.json();

响应：

{
  "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/dApp
• 按 ID 获取报告（reports/:id）
• Webhook
• Solana 端点