Endpoint reference

All endpoints live under https://api.cognivolabs.io/v1/api. Intelligence endpoints are POST with a JSON body (this prevents link previews, crawlers and prefetchers from ever triggering an execution). GET exists only for health, me and discover.

Prefer a machine-readable version? The full OpenAPI spec covers everything on this page.

The response envelope

Every endpoint answers with the same envelope (ids and timestamps in the examples on this page are example values). Success:

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

data - the intelligence result itself; its shape varies per endpoint
meta.request_id - unique id for this call; keep it, support can trace a call from it
meta.credits_charged - the credits this call cost: the endpoint's credit price on a successful paid call; 0 for free endpoints, trial-allowance calls, and any failed or honest-empty result
meta.generated_at - when the result was produced
meta.chain appears on chain-specific calls, and meta.sources (an array of source labels) appears when the result cites sources

Failure:

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

error is a stable machine-readable code (see Rate limits and errors); message is an optional human hint.

Common body fields

chain - one of eth, base, bsc (case-insensitive)
address / wallet / token - a 0x… EVM address (40 hex characters)

All examples below use the placeholder YOUR_API_KEY; in real code load the key from an environment variable or secret manager, never hardcode it.

Pricing

Live keys are self-serve and pay-as-you-go: a new live key runs these endpoints immediately, and each successful call is charged in Cognivo credits from your account's balance; failed calls are never charged, and a successful call is charged exactly once (duplicate submissions of the same operation cannot double-charge). If your balance cannot cover a call you get 402 payment_required (nothing charged): top up on your Cognivo account billing page and retry. Sandbox (cogv_test_) keys cannot run live intelligence. See Rate limits, errors and billing. Prices per endpoint:

Endpoint	Credits per successful call
`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`	free
`GET discover`	free, with a tight rate cap

Service

GET /v1/api/health

Liveness probe. No API key required.

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

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

Response (not the standard envelope, by design):

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

Limitations: if the public API is switched off you get 404 public_api_disabled here too, so this endpoint doubles as an availability check.

GET /v1/api/me

Introspects the calling key. Scope: any valid key. Free. For live self-serve keys it also shows the owner account's credits_balance (null if temporarily unavailable) and top_up guidance, plus the key's 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();

Response:

{
  "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": "…" }
}

Limitations: shows only the masked key, never the full key material. credits_balance is the owner account's Cognivo credit balance and can be null if it is temporarily unavailable.

Token intelligence

POST /v1/api/intel/why-down - scope `intel:read`

Why is this token down: a grounded read of recent on-chain activity looking for the dominant driver (sells, LP pulls, owner movements).

Cost: 3 credits per successful call, self-serve on any live key with this scope; failed calls are never charged.

Request body:

{ "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();

Response: the standard envelope; data holds the drop analysis (dominant driver, supporting on-chain observations) with meta.chain set.

Limitations: needs recent activity to say anything useful; for a token with very little trading history the read can be thin. Signals, not financial advice.

POST /v1/api/intel/team-wallets - scope `intel:read`

Team and controller wallet scan for a token: deployer, owner and controller wallets plus their recent behavior.

Cost: 5 credits per successful call, self-serve on any live key with this scope; failed calls are never charged.

Request body:

{ "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();

Response: the standard envelope; data lists the identified team/controller wallets and their recent behavior, often with meta.sources.

Limitations: identifies wallets from on-chain relationships (deploy, ownership, control); it cannot see off-chain team structure.

POST /v1/api/intel/liquidity - scope `liquidity:read`

Pool/LP status for a token: pool context, LP custody and lock/burn context.

Cost: 2 credits per successful call, self-serve on any live key with this scope; failed calls are never charged.

Request body (optional booleans metadata, locks and full add grounded pool metadata, timed-lock proof and the fullest available read):

{ "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();

Response: the standard envelope; data holds token identity, a market snapshot, and LP custody plus lock/burn context.

Limitations: deep historical burn provenance is not exposed in v1; lock context covers recognized locker patterns, and an unrecognized custom locker may read as unlocked custody.

POST /v1/api/intel/risk - scope `intel:read`

Chain-aware Cognivo risk signals for a token (red-flags read as fallback).

Cost: 2 credits per successful call, self-serve on any live key with this scope; failed calls are never charged.

Request body:

{ "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();

Response: the standard envelope; data holds the risk signals and flags found for the token.

Limitations: a clean result never means "safe"; it means no known red flags were found at read time.

Wallet intelligence

POST /v1/api/wallet/pnl - scope `intel:read`

Realized PnL for a wallet on one token, from grounded wallet activity. Both wallet and token are required.

Cost: 10 credits per successful call, self-serve on any live key with this scope; failed calls and 422 no-data results are never charged.

Request body:

{ "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();

Response: the standard envelope; data holds the realized PnL computation for that wallet/token pair.

Limitations: returns 422 (for example insufficient_data) when the wallet has no priced trades in that token, so a fair number cannot be computed. Cognivo never invents a figure, and a 422 is never charged. Realized PnL only; unrealized (still-held) positions are not valued here.

POST /v1/api/wallet/approvals - scope `security:read`

Token approvals held against a wallet, flagging unlimited allowances. Read-only: Cognivo never moves funds and cannot revoke for you.

Cost: 2 credits per successful call, self-serve on any live key with this scope; failed calls are never charged.

Request body (limit and offset optionally page through large approval sets):

{ "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();

Response: the standard envelope; data holds the approval list with spender, token and allowance context.

Limitations: an empty result (no approvals found) is a valid, successful answer and is not charged.

POST /v1/api/wallet/exact-movements - scope `intel:read`

Exact recent movements for a wallet (owner/deployer style read). token is optional and narrows the read to one token.

Cost: 5 credits per successful call, self-serve on any live key with this scope; failed calls are never charged.

Request body:

{ "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();

Response: the standard envelope; data holds the movement list with counts.

Limitations: returns the most recent movements (up to 25 per call); a wallet with no matching movements returns 422 rather than an invented history.

Discover

GET /v1/api/discover

The public Discover feed: recent high-quality public intelligence cards (token identity, hook, bullets). Scope: any valid key. Free, with a tight rate cap.

Query parameters: limit (1-50, default 20) and optional 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();

Response:

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

Limitations: limit values outside 1-50 are clamped into range; the feed contains only intelligence that users chose to publish, so it is a sample, not full coverage.

Planned (not live yet)

These are documented for roadmap transparency and return nothing today:

Deep wallet trace over the API (wallet/trace) - the async job flow is chat/dApp-only for now
Report fetch by id (reports/:id)
Webhooks
Solana endpoints

The response envelope​

Common body fields​

Pricing​

Service​

GET /v1/api/health​

GET /v1/api/me​

Token intelligence​

POST /v1/api/intel/why-down - scope intel:read​

POST /v1/api/intel/team-wallets - scope intel:read​

POST /v1/api/intel/liquidity - scope liquidity:read​

POST /v1/api/intel/risk - scope intel:read​

Wallet intelligence​

POST /v1/api/wallet/pnl - scope intel:read​

POST /v1/api/wallet/approvals - scope security:read​

POST /v1/api/wallet/exact-movements - scope intel:read​

Discover​

GET /v1/api/discover​

Planned (not live yet)​

The response envelope

Common body fields

Pricing

Service

GET /v1/api/health

GET /v1/api/me

Token intelligence

POST /v1/api/intel/why-down - scope `intel:read`

POST /v1/api/intel/team-wallets - scope `intel:read`

POST /v1/api/intel/liquidity - scope `liquidity:read`

POST /v1/api/intel/risk - scope `intel:read`

Wallet intelligence

POST /v1/api/wallet/pnl - scope `intel:read`

POST /v1/api/wallet/approvals - scope `security:read`

POST /v1/api/wallet/exact-movements - scope `intel:read`

Discover

GET /v1/api/discover

Planned (not live yet)