Быстрый старт

Первый вызов за 30 секунд: создайте проект, создайте live-ключ, проверьте баланс, вставьте одну команду. Live-ключи работают по модели self-serve и включаются сразу; за успешный вызов из примера списывается 2 кредита, а за неудачный вызов плата не берётся никогда.

1. Создайте проект и live-ключ

Откройте портал разработчика и войдите со своим аккаунтом Cognivo.
Создайте проект (например, «Мой торговый бот»).
Создайте live API-ключ. Выберите нужные ему разрешения (скоупы) - для этого быстрого старта выдайте Аналитику токенов и кошельков (intel:read) и Чтение ликвидности (liquidity:read).
Скопируйте ключ сразу. Он показывается ровно один раз; после этого видна только маскированная версия (cogv_live_****abcd). Если вы его потеряли, ротируйте ключ.

Ключи бывают двух окружений:

cogv_live_... - стандартный ключ. Self-serve: он работает сразу, оплачивается pay-as-you-go в кредитах Cognivo за каждый успешный вызов с баланса кредитов вашего аккаунта. Ни trial, ни одобрение не нужны.
cogv_test_... - Sandbox-ключи, явно помеченные как Sandbox, только для ограниченных демо и интеграционного тестирования. Они не могут выполнять живую аналитику и жёстко ограничены (25 запросов/час, 100/день, 1/секунду).

2. Проверьте ключ и баланс

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

В ответ вы получите свой маскированный ключ, проект, окружение, скоупы и часовой лимит запросов, плюс access_mode, credits_balance вашего аккаунта (чтобы видеть, хватит ли на следующий вызов) и подсказку top_up. Этот вызов всегда бесплатен.

3. Запустите первый живой вызов (curl)

Аналитические эндпоинты используют POST с JSON-телом. Эта команда запускает настоящую проверку ликвидности реального токена в сети Base (RWA Inc, публичный контракт, который мы используем в демо). Она выполняется сразу на вашем новом live-ключе:

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

Вы должны увидеть "ok": true с идентификацией токена (имя/символ), снимком рынка и контекстом LP/локов в data. При успехе списывается цена эндпоинта - 2 кредита за liquidity - и meta.credits_charged подтверждает это. Если вместо этого вы получили ошибку 402 с кодом payment_required, вашего баланса кредитов Cognivo не хватает на вызов: ничего не списано, поэтому пополните баланс на странице биллинга вашего аккаунта Cognivo и запустите ту же команду ещё раз. Неудачные вызовы никогда не тарифицируются. Когда будете готовы, подставьте в address любой контракт токена в eth, base или bsc.

Держите ключ в секрете

Никогда не вставляйте настоящий API-ключ в публичный репозиторий, чат или клиентский код. Ключ показывается только один раз при создании; если он утёк, ротируйте его в портале.

4. Тот же вызов на 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. Формат ответа

Каждый эндпоинт отвечает одним и тем же конвертом (id и таймстемпы ниже - примеры значений):

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

При ошибке (плата не взимается никогда):

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

Биллинг и пополнения

Pay-as-you-go, за каждый успешный вызов. Каждый успешный вызов списывает опубликованную цену эндпоинта в кредитах с баланса кредитов Cognivo владельца проекта (те же кредиты, что в Chat и dApp). Нет ни подписки, ни минимума.
Где пополнить. На странице биллинга вашего аккаунта Cognivo в dApp. GET /v1/api/me показывает ваш текущий credits_balance и подсказку top_up.
Неудачные вызовы никогда не тарифицируются. Ошибки, таймауты и отклонённые вызовы не стоят ничего. Сам 402 payment_required бесплатен: пополните баланс и повторите.
Честные пустые результаты бесплатны. wallet/pnl возвращает 422, когда у кошелька нет оценённых сделок по этому токену, а пустой список wallet/approvals - валидный ответ; ни то, ни другое не тарифицируется.
Повторы безопасны. Успешный вызов тарифицируется ровно один раз; задублированные отправки одной и той же операции не могут списать дважды. На 5xx или 429 повторяйте с backoff; на 402 сначала пополните баланс.
Приостановка. Приостановленный ключ (или отключённый проект) не может ничего выполнять и никогда не тарифицируется; портал показывает причину.

Берегите свой ключ

Вызывайте API с сервера, никогда из кода браузера или мобильного клиента.
Храните ключ в переменной окружения или менеджере секретов.
Если ключ мог утечь, отзовите или ротируйте его в портале - старый ключ перестаёт работать в течение минуты.

1. Создайте проект и live-ключ​

2. Проверьте ключ и баланс​

3. Запустите первый живой вызов (curl)​

4. Тот же вызов на JavaScript / TypeScript​

5. Формат ответа​

Биллинг и пополнения​

Берегите свой ключ​