Справочник эндпоинтов

Все эндпоинты живут под https://api.cognivolabs.io/v1/api. Аналитические эндпоинты - это POST с JSON-телом (это не даёт превью ссылок, краулерам и префетчерам когда-либо запустить выполнение). GET существует только для health, me и discover.

Предпочитаете машиночитаемый вариант? Полная спецификация OpenAPI покрывает всё, что есть на этой странице.

Конверт ответа

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

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

data - сам аналитический результат; его форма зависит от эндпоинта
meta.request_id - уникальный id этого вызова; сохраните его, поддержка может отследить вызов по нему
meta.credits_charged - кредиты, которые стоил этот вызов: цена эндпоинта в кредитах при успешном платном вызове; 0 для бесплатных эндпоинтов, вызовов по trial-квоте и любого неудачного или честно-пустого результата
meta.generated_at - когда был получен результат
meta.chain появляется в вызовах, привязанных к сети, а meta.sources (массив меток источников) появляется, когда результат ссылается на источники

Ошибка:

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

error - это стабильный машиночитаемый код (см. Лимиты и ошибки); message - необязательная подсказка для человека.

Общие поля тела запроса

chain - одно из eth, base, bsc (без учёта регистра)
address / wallet / token - EVM-адрес вида 0x… (40 hex-символов)

Во всех примерах ниже используется заполнитель YOUR_API_KEY; в реальном коде загружайте ключ из переменной окружения или менеджера секретов и никогда не хардкодьте его.

Цены

Live-ключи работают по модели self-serve и pay-as-you-go: новый live-ключ выполняет эти эндпоинты сразу, и каждый успешный вызов тарифицируется в кредитах Cognivo с баланса вашего аккаунта; неудачные вызовы никогда не тарифицируются, а успешный вызов тарифицируется ровно один раз (задублированные отправки одной и той же операции не могут списать дважды). Если баланса не хватает на вызов, вы получаете 402 payment_required (ничего не списано): пополните баланс на странице биллинга вашего аккаунта Cognivo и повторите. Sandbox-ключи (cogv_test_) не могут выполнять живую аналитику. См. Лимиты, ошибки и биллинг. Цены по эндпоинтам:

Эндпоинт	Кредитов за успешный вызов
`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`	бесплатно
`GET discover`	бесплатно, с жёстким лимитом запросов

Сервис

GET /v1/api/health

Проверка живости. API-ключ не требуется.

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

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

Ответ (намеренно не стандартный конверт):

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

Ограничения: если публичный API отключён, здесь вы тоже получите 404 public_api_disabled, так что этот эндпоинт заодно служит проверкой доступности.

GET /v1/api/me

Интроспекция вызывающего ключа. Скоуп: любой действительный ключ. Бесплатно. Для live self-serve ключей он также показывает credits_balance аккаунта-владельца (null, если временно недоступен) и подсказку top_up, плюс 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": "Top up Cognivo credits on your account billing page in the dApp."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

Ограничения: показывает только маскированный ключ, никогда полный материал ключа. credits_balance - это баланс кредитов Cognivo аккаунта-владельца, и он может быть null, если временно недоступен.

Аналитика токенов

POST /v1/api/intel/why-down - скоуп `intel:read`

Почему этот токен падает: обоснованное чтение недавней on-chain активности в поисках доминирующего драйвера (продажи, вывод LP, движения владельца).

Цена: 3 кредита за успешный вызов, self-serve на любом live-ключе с этим скоупом; неудачные вызовы никогда не тарифицируются.

Тело запроса:

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

Ответ: стандартный конверт; data содержит анализ падения (доминирующий драйвер, подтверждающие on-chain наблюдения), с заполненным meta.chain.

Ограничения: чтобы сказать что-то полезное, нужна недавняя активность; для токена с очень скудной торговой историей результат может быть скудным. Это сигналы, а не финансовый совет.

POST /v1/api/intel/team-wallets - скоуп `intel:read`

Скан командных и управляющих кошельков токена: кошельки деплоера, владельца и контролёров плюс их недавнее поведение.

Цена: 5 кредитов за успешный вызов, self-serve на любом live-ключе с этим скоупом; неудачные вызовы никогда не тарифицируются.

Тело запроса:

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

Ответ: стандартный конверт; data перечисляет выявленные командные/управляющие кошельки и их недавнее поведение, часто с meta.sources.

Ограничения: кошельки выявляются по on-chain связям (деплой, владение, контроль); off-chain структуру команды он видеть не может.

POST /v1/api/intel/liquidity - скоуп `liquidity:read`

Статус пула/LP для токена: контекст пула, кастодия LP и контекст локов/сжигания.

Цена: 2 кредита за успешный вызов, self-serve на любом live-ключе с этим скоупом; неудачные вызовы никогда не тарифицируются.

Тело запроса (необязательные булевы metadata, locks и full добавляют подтверждённые метаданные пула, доказательство временных локов и максимально полное доступное чтение):

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

Ответ: стандартный конверт; data содержит идентификацию токена, снимок рынка и кастодию LP плюс контекст локов/сжигания.

Ограничения: глубокая историческая провенансность сжигания в v1 не раскрывается; контекст локов покрывает распознаваемые паттерны локеров, и нераспознанный кастомный локер может выглядеть как незалоченная кастодия.

POST /v1/api/intel/risk - скоуп `intel:read`

Учитывающие сеть сигналы риска Cognivo для токена (чтение красных флагов как fallback).

Тело запроса:

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

Ответ: стандартный конверт; data содержит найденные для токена сигналы риска и флаги.

Ограничения: чистый результат никогда не означает «безопасно»; он означает, что на момент чтения известных красных флагов не найдено.

Аналитика кошельков

POST /v1/api/wallet/pnl - скоуп `intel:read`

Реализованный PnL кошелька по одному токену, по подтверждённой активности кошелька. Оба поля wallet и token обязательны.

Цена: 10 кредитов за успешный вызов, self-serve на любом live-ключе с этим скоупом; неудачные вызовы и результаты 422 «нет данных» никогда не тарифицируются.

Тело запроса:

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

Ответ: стандартный конверт; data содержит расчёт реализованного PnL для этой пары кошелёк/токен.

Ограничения: возвращает 422 (например, insufficient_data), когда у кошелька нет оценённых сделок по этому токену и честное число посчитать невозможно. Cognivo никогда не выдумывает цифру, и за 422 никогда не списывается плата. Только реализованный PnL; нереализованные (ещё удерживаемые) позиции здесь не оцениваются.

POST /v1/api/wallet/approvals - скоуп `security:read`

Токен-approvals, висящие на кошельке, с пометкой безлимитных allowance. Только чтение: Cognivo никогда не перемещает средства и не может ничего отозвать за вас.

Тело запроса (limit и offset опционально листают большие наборы approvals):

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

Ответ: стандартный конверт; data содержит список approvals с контекстом спендера, токена и allowance.

Ограничения: пустой результат (approvals не найдены) - это валидный успешный ответ, и он не тарифицируется.

POST /v1/api/wallet/exact-movements - скоуп `intel:read`

Точные недавние движения кошелька (чтение в стиле владелец/деплоер). token необязателен и сужает чтение до одного токена.

Тело запроса:

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

Ответ: стандартный конверт; data содержит список движений со счётчиками.

Ограничения: возвращает самые недавние движения (до 25 за вызов); кошелёк без подходящих движений возвращает 422, а не выдуманную историю.

Discover

GET /v1/api/discover

Публичная лента Discover: свежие качественные публичные аналитические карточки (идентификация токена, хук, буллеты). Скоуп: любой действительный ключ. Бесплатно, с жёстким лимитом запросов.

Query-параметры: limit (1-50, по умолчанию 20) и необязательный 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();

Ответ:

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

Ограничения: значения limit вне диапазона 1-50 подрезаются в диапазон; лента содержит только аналитику, которую пользователи решили опубликовать, поэтому это выборка, а не полное покрытие.

В планах (пока не запущено)

Это задокументировано для прозрачности роадмапа и сегодня ничего не возвращает:

Глубокая трассировка кошелька через API (wallet/trace) - асинхронный поток заданий пока доступен только в чате/dApp
Получение отчёта по id (reports/:id)
Вебхуки
Эндпоинты Solana

Конверт ответа​

Общие поля тела запроса​

Цены​

Сервис​

GET /v1/api/health​

GET /v1/api/me​

Аналитика токенов​

POST /v1/api/intel/why-down - скоуп intel:read​

POST /v1/api/intel/team-wallets - скоуп intel:read​

POST /v1/api/intel/liquidity - скоуп liquidity:read​

POST /v1/api/intel/risk - скоуп intel:read​

Аналитика кошельков​

POST /v1/api/wallet/pnl - скоуп intel:read​

POST /v1/api/wallet/approvals - скоуп security:read​

POST /v1/api/wallet/exact-movements - скоуп intel:read​

Discover​

GET /v1/api/discover​

В планах (пока не запущено)​

Конверт ответа

Общие поля тела запроса

Цены

Сервис

GET /v1/api/health

GET /v1/api/me

Аналитика токенов

POST /v1/api/intel/why-down - скоуп `intel:read`

POST /v1/api/intel/team-wallets - скоуп `intel:read`

POST /v1/api/intel/liquidity - скоуп `liquidity:read`

POST /v1/api/intel/risk - скоуп `intel:read`

Аналитика кошельков

POST /v1/api/wallet/pnl - скоуп `intel:read`

POST /v1/api/wallet/approvals - скоуп `security:read`

POST /v1/api/wallet/exact-movements - скоуп `intel:read`

Discover

GET /v1/api/discover

В планах (пока не запущено)