Endpoint Reference

What this page is

The Cognivo Developer API lets your own code ask Cognivo the same questions the app answers. Every endpoint lives under https://api.cognivolabs.io/v1/api.

Use it when you want a Cognivo check to run somewhere other than the app: inside your own bot, a dashboard, a spreadsheet job, or a nightly script that watches a list of tokens.

Intelligence endpoints are POST with a JSON body. That is deliberate: a link preview, a crawler or a browser prefetch can never trigger an execution by loading a URL. GET exists only for health, me and discover.

Where to find this in the app

Sign in to the Cognivo app, open Developers in the left sidebar under Account, then select the Endpoints tab.

The Endpoints tab on the Developers page, where each Cognivo endpoint is listed with the permission it needs and what it costs.Enlarge image

The tab is a reference, not a runner. It lists every live endpoint with a copyable example, the permission the key needs, and the price in credits. The Permissions explained card groups those permissions into three: Intelligence (why is it down, team wallets, risk, wallet PnL, exact movements), Security (token approvals) and Liquidity (liquidity, locks and burns). Give each key only the permissions it needs.

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 below are placeholder 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 is the result itself. Its shape varies per endpoint.
• meta.request_id is a unique id for this call. Keep it, support can trace a call from it.
• meta.credits_charged is what the call cost: the endpoint's price on a successful paid call, and 0 for free endpoints and for any failed or honestly empty result.
• meta.generated_at is when the result was produced.
• meta.chain appears on chain specific calls, and meta.sources 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. message is an optional human hint. The full list is on Rate limits and errors.

Common body fields

• chain is one of eth (Ethereum), base (Base) or bsc (BNB Chain), and is case insensitive.
• address, wallet and token are 0x EVM addresses of 40 hex characters.

Every example uses the placeholder YOUR_API_KEY. In real code, load the key from an environment variable or a secret manager. Never hardcode it.

What each endpoint costs

Live keys are self serve and pay as you go. A new live key runs these endpoints straight away, and each successful call is charged in Cognivo credits from your account balance. Failed calls are never charged, and a successful call is charged exactly once, so a repeated submission of the same operation cannot double charge you.

Every account gets 5 free credits a day, and they reset at midnight UTC. If your balance cannot cover a call you get 402 payment_required and nothing is charged. Top up on your account billing page and retry. Sandbox (cogv_test_) keys cannot run live intelligence. See Billing and credits.

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
POST contract/analysis	free
GET health, GET me	free
GET discover	free, with a tight rate cap

Service

GET /v1/api/health

Checks that the Cognivo API is up. No API key needed.

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, which is not the standard envelope, by design:

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

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

Shows details about the calling key: its tier, permissions and rate limit. Works with any active key, and is free. For live self serve keys it also shows the owner account's credits_balance 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();

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

Limitations: it shows the masked key only, never the full key material. credits_balance can come back as null, which means Cognivo could not read the balance at that moment, not that the balance is zero.

The remaining endpoints all follow the same call shape as the examples below. Swap the path and the body fields.

Token intelligence

POST /v1/api/intel/why-down, permission Intelligence (intel:read)

A plain language read of why a token's price is down, built from recent on-chain activity: heavy selling, liquidity being pulled, owner or team wallets moving.

List price: 3 credits per successful call. Failed calls are never charged. Charging for Developer API calls is switched off today, so a successful call deducts nothing and your balance does not move.

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 dominant driver and the on-chain observations behind it, with meta.chain set.

Limitations: the read needs recent activity to say anything useful, so a token with very little trading history gives a thin answer. These are signals, not financial advice.

POST /v1/api/intel/team-wallets, permission Intelligence (intel:read)

Surfaces wallets linked to a token's team or treasury: deployer, owner and controller wallets, plus what they have been doing recently.

List price: 5 credits per successful call. Failed calls are never charged. Charging for Developer API calls is switched off today, so a successful call deducts nothing and your balance does not move.

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

Response: the standard envelope. data lists the identified wallets and their recent behaviour, often with meta.sources.

Limitations: wallets are identified from on-chain relationships such as deployment, ownership and control. Cognivo cannot see off-chain team structure, so an empty list means nothing was linkable on chain, not that a token has no team.

POST /v1/api/intel/liquidity, permission Liquidity (liquidity:read)

Checks a token's liquidity, locks and burns with on-chain evidence: pool context, who holds the LP tokens, and lock or burn context.

List price: 2 credits per successful call. Failed calls are never charged. Charging for Developer API calls is switched off today, so a successful call deducts nothing and your balance does not move.

Optional booleans metadata, locks and full add pool metadata, timed lock proof, and the fullest available read.

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

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

Limitations: deep historical burn provenance is not exposed in v1. Lock context covers recognised locker patterns, so an unusual custom locker can read as plain custody rather than a lock. Read that as "not verified", not as "not locked".

POST /v1/api/intel/risk, permission Intelligence (intel:read)

Cognivo Risk Signals for a token contract, chain aware, with a red flags read as fallback.

List price: 2 credits per successful call. Failed calls are never charged. Charging for Developer API calls is switched off today, so a successful call deducts nothing and your balance does not move.

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

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

Limitations: a clean result does not mean the token is safe. It means no known red flags were found at the time of the read.

POST /v1/api/contract/analysis, permission Contract (contract:read)

Contract and control evidence for a contract address: does it exist, who owns it, was ownership renounced, is it a proxy and who administers it, who deployed it, which wallets can be attributed as controllers or team, and is the source verified.

Cost: 0 credits. This endpoint is free by decision, on every plan. Nothing is deducted.

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

Response: the standard envelope. data holds contract, ownership, proxy, deployer, controllers, source_verification, limitations and unavailable.

Every field tells you where it came from. meta.provenance maps each field to exactly one of:

Label	What it means
verified_onchain	Read from a node for that network at the time of your request. A fact.
augmented	Cognivo Augmented Intelligence: supplied by an outside source, cross checked but not proven by Cognivo.
interpretation	Cognivo's reading of the facts. A judgement, not a fact.
unavailable	Cognivo could not get this. The reason is in data.unavailable.

Nothing is guessed, defaulted, or returned as zero to fill a gap.

meta.chain_data_source.cognivo_grounded tells you whether Cognivo operates the infrastructure the read came from. Cognivo runs its own Ethereum node, so Ethereum reads are true. Base and BNB Chain reads come from outside RPC infrastructure, so they are false. Those reads are accurate, but they are not served from hardware Cognivo controls, and Cognivo says so rather than let you assume otherwise.

Limitations on Base, also returned in data.limitations:

• The deep controller graph is Ethereum only. On Base, controller and team attribution comes from a narrower wallet role reading.
• Deployer evidence on Base comes from an outside source, not a Cognivo archive read. Treat it as a strong lead, not a proven fact.
• Liquidity lock schedules are not decoded on Base. Use POST /v1/api/intel/liquidity for LP custody and burn evidence, and do not read a missing lock as an absent lock.

This endpoint reports contract control evidence only. It says nothing about liquidity, and a clean result never means the contract is safe.

Read only: nothing is signed, no transaction is built, nothing is broadcast, and no wallet is delegated.

Wallet intelligence

POST /v1/api/wallet/pnl, permission Intelligence (intel:read)

Profit and loss for one wallet on one token, computed from grounded on-chain swaps. Both wallet and token are required.

List price: 10 credits per successful call. Failed calls, and 422 no data results, are never charged. Charging for Developer API calls is switched off today, so a successful call deducts nothing and your balance does not move.

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

Response: the standard envelope. data holds the realized figure, and an unrealized figure for the position still held when a defensible cost basis exists.

Limitations: when no defensible cost basis can be established, the unrealized figure comes back as null rather than a made up number. When the wallet has no priced trades in that token at all, the call returns 422 (for example insufficient_data), which means Cognivo could not compute a fair number, not that the profit was zero. A 422 is never charged. Swaps Cognivo could not price are shown as unpriced rather than dropped.

POST /v1/api/wallet/approvals, permission Security (security:read)

Lists the token spending approvals a wallet has granted, and flags unlimited allowances.

List price: 2 credits per successful call. Failed calls are never charged. Charging for Developer API calls is switched off today, so a successful call deducts nothing and your balance does not move.

Optional limit and offset page through large approval sets.

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

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

Limitations: this is read only. Cognivo never moves funds and cannot revoke an approval for you. Revoking is always done from your own wallet. An empty list is a valid successful answer, and it is not charged.

POST /v1/api/wallet/exact-movements, permission Intelligence (intel:read)

Lists a wallet's exact token movements: buys, sells and transfers. token is optional and narrows the read to one token.

List price: 5 credits per successful call. Failed calls are never charged. Charging for Developer API calls is switched off today, so a successful call deducts nothing and your balance does not move.

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

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

Limitations: the call 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 anonymised on-chain intelligence cards, each with token identity, a hook and bullets. Works with any active key. Free, under a tight daily limit.

Query parameters: limit (1 to 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'

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

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

Not available yet

These are listed for transparency and return nothing today:

• Deep wallet trace over the API (wallet/trace). The async job flow is chat and app only for now.
• Report fetch by id (reports/:id).
• Webhooks.
• Solana endpoints.

Next steps

Make your first call with the Quickstart, create and scope a key on Authentication and keys, and read Rate limits and errors before you put anything on a schedule.