Skip to main content

Quickstart

Your first Cognivo API call​

The Cognivo Developer API lets your own code ask the same on-chain questions you can ask in the dApp and in Cognivo Chat. This page walks the shortest path through it: create a project, create a key, run one real call, read the answer.

When to use it​

Use the API when you want token, wallet or liquidity checks inside something you are building, such as a trading bot, an internal dashboard, an alerting job or a backend service, instead of clicking through the dApp each time. If you only want to run checks by hand, the dApp and Chat already do that and you do not need a key.

Where to find it​

Sign in to the dApp, open Account in the sidebar, then select Developers. Signed out visitors see an orientation screen only, so sign in first. Everything on this page happens on that one screen.

Create a project, then a key​

A project groups your API keys and their usage together, so start there.

  1. Select New project to open the short form underneath the project picker.
  2. Type a name into Project name so you can tell your projects apart later.
  3. Select Create to add the project, or Cancel to close the form without saving.
  4. Select Create live key to make a key for the project, then send it with your requests from your own code.
The project controls on the Developers page, where you set up a project before you create a key.Enlarge image

The project name is only a label for you. It does not appear in your requests and you can create more than one project, up to the limit shown on the page.

When you select Create live key, Cognivo shows the full key exactly once, in a dialog with a copy button. Copy it then and store it somewhere safe. Afterwards the page shows only a masked version, the prefix and the last four characters, because Cognivo stores the key in a form it cannot read back. If you lose a key, or think it has leaked, use Rotate or Revoke on the key row. The old key stops working right away.

Each key also carries Permissions, which control what it can call: Intelligence, Security and Liquidity. Give a key only the permissions it needs. The example below needs Liquidity.

Two more buttons sit on the same card. Top up credits takes you to your billing page. Enterprise access opens the support flow, and it is the only path that involves a request, for custom pricing or higher limits. A normal live key needs no approval and works the moment you create it.

Run the example call​

Open the Quickstart tab. It carries a working example you can copy and run without writing anything yourself.

The Quickstart tab on the Developers page, where you copy a working example call.Enlarge image

The Test keys vs live keys card explains the difference. A test key makes safe calls with tight limits, which is good for wiring things up. A live key makes real calls that are charged from your Cognivo credit balance. The Test a live endpoint card then gives five numbered steps and the command itself, with a copy icon.

The command is a real liquidity check on a real Base contract:

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":"0xe2b1dc2d4a3b4e59fdf0c47b71a7a86391a8b35a"}'

The same call from JavaScript or TypeScript:

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/liquidity", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.COGNIVO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();
if (json.ok) {
  console.log(json.data);
  console.log(json.meta.request_id);
} else {
  console.error(json.error);
}

What comes back​

Every endpoint answers with the same envelope, which the Expected response block on the Quickstart tab shows:

{
  "ok": true,
  "data": { "identity": { "name": "...", "symbol": "..." }, "marketSnapshot": {} },
  "meta": {
    "chain": "base",
    "request_id": "capi_...",
    "credits_charged": 0,
    "generated_at": "..."
  }
}

data holds the result. meta.request_id is worth logging, because support can look up a single call by it. meta.credits_charged tells you exactly what that call cost.

A field can come back empty, unknown or unavailable. That means Cognivo could not verify it from the data it can reach, not that there is nothing there. Read it as "not confirmed", and do not treat a quiet result as an all clear. Cognivo reports what it checked and what it found, and nothing in a response proves a token is a scam or proves one is safe.

A failed call answers with ok set to false, an error code and a request_id. Failed calls are not charged.

Cost, chains and limits​

  • Some endpoints are free with any active key. Others are charged per successful call from your Cognivo credit balance. The Endpoints tab lists each endpoint with its price in Cognivo credits, or Free where it is free, so check it there before you build against an endpoint.
  • You are charged only for a successful call, and meta.credits_charged confirms the amount. Errors, timeouts and blocked calls cost nothing.
  • Every account gets 5 free credits per day. They reset at midnight UTC and are used before any paid credits.
  • The API covers Ethereum, Base and BNB Chain today. Some endpoints support fewer chains than others.
  • Test keys are capped tightly and are not a free production tier. Each key row on the Keys tab shows the limits Cognivo is applying to that key right now, which can be lower than the tier default.
  • A suspended key, or a key in a suspended project, cannot run anything, and the portal shows the reason.

Keep your key safe​

Call the API from a server, never from browser or mobile app code. Keep the key in an environment variable or a secret manager, never in a public repository, a chat message or a screenshot. If a key may have leaked, rotate or revoke it on the Keys tab.

Next steps​

Read Authentication and keys for permissions and key handling in full, Endpoints for what each call returns and what it costs, and Rate limits and errors for retries and error codes. For your credit balance and top ups, see Billing and credits.