Skip to main content

Quickstart

Your first call in 30 seconds: create a project, create a live key, check your balance, paste one command. Live keys are self-serve and work immediately; you are charged 2 credits when the example call succeeds, and never charged for a failed call.

1. Create a project and a live key​

  1. Open the Developer portal and sign in with your Cognivo account.
  2. Create a project (for example "My trading bot").
  3. Create a live API key. Pick the permissions (scopes) it needs - for this quickstart, grant Token and wallet intelligence (intel:read) and Liquidity reads (liquidity:read).
  4. Copy the key now. It is shown exactly once; afterwards only a masked version (cogv_live_****abcd) is visible. If you lose it, rotate the key.

Keys come in two environments:

  • cogv_live_... - the standard key. Self-serve: it works immediately, billed pay-as-you-go in Cognivo credits per successful call from your account's credit balance. No trial or approval is needed.
  • cogv_test_... - Sandbox keys, clearly labelled Sandbox, for limited demos and integration testing only. They cannot run live intelligence and are tightly capped (25 requests/hour, 100/day, 1/second).

2. Check your key and balance​

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

You get back your masked key, project, environment, scopes and hourly rate limit, plus access_mode, your account's credits_balance (so you can see whether you can afford the next call) and top_up guidance. This call is always free.

3. Run your first live call (curl)​

Intelligence endpoints use POST with a JSON body. This exact command runs a real liquidity check on a real Base token (RWA Inc, a public contract we use in demos). It runs immediately on your new live key:

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

You should see "ok": true with the token's identity (name/symbol), a market snapshot, and LP/lock context in data. On success you are charged the endpoint's price - 2 credits for liquidity - and meta.credits_charged confirms it. If you instead get a 402 error with code payment_required, your Cognivo credit balance cannot cover the call: nothing was charged, so top up on your Cognivo account billing page and run the same command again. Failed calls are never charged. Swap the address for any token contract on eth, base or bsc when you're ready.

Keep your key secret

Never paste a real API key into a public repo, chat, or client-side code. The key is shown only once at creation; if it leaks, rotate it in the portal.

4. The same call in JavaScript / TypeScript​

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/liquidity", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.COGNIVO_API_KEY, // never hardcode keys
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();
if (json.ok) {
  console.log(json.data);        // the intelligence result
  console.log(json.meta.request_id); // keep for support/debugging
} else {
  console.error(json.error);     // e.g. "payment_required": top up, then retry
}

5. Response shape​

Every endpoint answers with the same envelope (ids and timestamps below are example values):

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

On failure (never charged):

{ "ok": false, "error": "payment_required", "request_id": "capi_..." }

Billing and top-ups​

  • Pay-as-you-go, per successful call. Each successful call deducts the endpoint's published credit price from the project owner's Cognivo credit balance (the same credits you use in Chat and the dApp). There is no subscription and no minimum.
  • Where to top up. On the billing page of your Cognivo account in the dApp. GET /v1/api/me shows your current credits_balance and top_up guidance.
  • Failed calls are never charged. Errors, timeouts and denied calls cost nothing. 402 payment_required itself is free: top up and retry.
  • Honest empty results are free. wallet/pnl returns 422 when a wallet has no priced trades in that token, and an empty wallet/approvals list is a valid answer; neither is charged.
  • Retries are safe. A successful call is charged exactly once; duplicate submissions of the same operation cannot double-charge you. On 5xx or 429, retry with backoff; on 402, top up first.
  • Suspension. A suspended key (or a disabled project) cannot execute anything and is never charged; the portal shows the reason.

Keep your key safe​

  • Call the API from a server, never from browser or mobile client code.
  • Store the key in an environment variable or secret manager.
  • If a key may have leaked, revoke or rotate it in the portal - the old key stops working within a minute.