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

Что это за страница

Cognivo Developer API позволяет вашему собственному коду задавать Cognivo те же вопросы, на которые отвечает приложение. Все эндпоинты находятся по адресу https://api.cognivolabs.io/v1/api.

Используйте его, когда хотите, чтобы проверка Cognivo выполнялась не в приложении: внутри вашего бота, панели, задания для таблицы или ночного скрипта, который следит за списком токенов.

Эндпоинты аналитики - это POST с телом JSON. Так сделано намеренно: превью ссылки, поисковый робот или предзагрузка браузера никогда не смогут запустить выполнение простой загрузкой URL. GET существует только для health, me и discover.

Где это найти в приложении

Войдите в приложение Cognivo, откройте Developers в левой боковой панели под Account, затем выберите вкладку Endpoints.

Страница «Разработчики» с открытой вкладкой «Эндпоинты»: карточка с пояснением разрешений и группами Intelligence, Security и Liquidity, а ниже две записи эндпоинтов, обе отмечены как бесплатные. — Вкладка «Эндпоинты» на странице «Разработчики», где для каждого эндпоинта Cognivo указано нужное разрешение и его стоимость.Увеличить изображение

Вкладка - это справочник, а не средство запуска. Она перечисляет каждый действующий эндпоинт с копируемым примером, правом доступа, которое нужно ключу, и ценой в кредитах. Карточка Permissions explained группирует эти права в три: Intelligence (почему цена падает, командные кошельки, риск, Wallet PnL, точные движения), Security (одобрения токенов) и Liquidity (ликвидность, локи и сжигания). Давайте каждому ключу только те права, которые ему нужны.

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

Оболочка ответа

Каждый эндпоинт отвечает одной и той же оболочкой. Идентификаторы и метки времени в примерах ниже - это значения-заглушки. Успех:

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

data - это сам результат. Его структура различается для каждого эндпоинта.
meta.request_id - уникальный идентификатор этого вызова. Сохраняйте его, поддержка может отследить вызов по нему.
meta.credits_charged - во что обошёлся вызов: цена эндпоинта при успешном платном вызове и 0 для бесплатных эндпоинтов и для любого неудачного или честно пустого результата.
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 (Ethereum), base (Base) или bsc (BNB Chain), регистр не важен.
address, wallet и token - это EVM-адреса 0x из 40 шестнадцатеричных символов.

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

Сколько стоит каждый эндпоинт

Live-ключи работают в режиме самообслуживания с оплатой по факту использования. Новый live-ключ запускает эти эндпоинты сразу же, и каждый успешный вызов тарифицируется в кредитах Cognivo с баланса вашего аккаунта. Неудачные вызовы никогда не тарифицируются, а успешный вызов тарифицируется ровно один раз, поэтому повторная отправка той же операции не может списать с вас дважды.

Каждый аккаунт получает 5 бесплатных кредитов в день, они обновляются в полночь UTC. Если баланса не хватает на вызов, вы получаете 402 payment_required, и ничего не списывается. Пополните баланс на странице биллинга вашего аккаунта и повторите. Песочные ключи (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
`POST contract/analysis`	бесплатно
`GET health`, `GET me`	бесплатно
`GET discover`	бесплатно, с жёстким лимитом запросов

Служебные

GET /v1/api/health

Проверяет, что API Cognivo работает. 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-ключей самообслуживания он также показывает credits_balance аккаунта-владельца и подсказку 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": "Manage credits from your Cognivo account billing page."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

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

Все остальные эндпоинты вызываются так же, как в примерах ниже. Замените путь и поля тела запроса.

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

POST /v1/api/intel/why-down, право доступа Intelligence (`intel:read`)

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

Прейскурантная цена: 3 кредита за успешный вызов. Неудачные вызовы никогда не тарифицируются. Тарификация вызовов Developer API сегодня отключена, поэтому успешный вызов ничего не списывает и баланс не меняется.

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 содержит доминирующий драйвер и наблюдения в блокчейне, стоящие за ним, с заполненным meta.chain.

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

POST /v1/api/intel/team-wallets, право доступа Intelligence (`intel:read`)

Показывает кошельки, связанные с командой или казначейством токена: кошельки деплойера, владельца и контроллера, а также то, чем они занимались в последнее время.

Прейскурантная цена: 5 кредитов за успешный вызов. Неудачные вызовы никогда не тарифицируются. Тарификация вызовов Developer API сегодня отключена, поэтому успешный вызов ничего не списывает и баланс не меняется.

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

Ответ: стандартная оболочка. data перечисляет выявленные кошельки и их недавнее поведение, часто с meta.sources.

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

POST /v1/api/intel/liquidity, право доступа Liquidity (`liquidity:read`)

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

Прейскурантная цена: 2 кредита за успешный вызов. Неудачные вызовы никогда не тарифицируются. Тарификация вызовов Developer API сегодня отключена, поэтому успешный вызов ничего не списывает и баланс не меняется.

Необязательные булевы значения metadata, locks и full добавляют метаданные пула, подтверждение лока по времени и наиболее полное доступное чтение.

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

Ответ: стандартная оболочка. data содержит идентичность токена, рыночный снимок и кастодию LP с контекстом лока или сжигания.

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

POST /v1/api/intel/risk, право доступа Intelligence (`intel:read`)

Cognivo Risk Signals для контракта токена, с учётом сети, с анализом красных флагов как запасным вариантом.

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

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

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

POST /v1/api/contract/analysis, право доступа Contract (`contract:read`)

Доказательства по контракту и контролю над ним для адреса контракта: существует ли он, кто им владеет, было ли владение отказано, является ли он прокси и кто им администрирует, кто его задеплоил, какие кошельки можно отнести к контроллерам или команде, и подтверждён ли исходный код.

Стоимость: 0 кредитов. Этот эндпоинт бесплатен по решению, на любом тарифе. Ничего не списывается.

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

Ответ: стандартная оболочка. data содержит contract, ownership, proxy, deployer, controllers, source_verification, limitations и unavailable.

Каждое поле сообщает, откуда оно взялось. meta.provenance сопоставляет каждое поле ровно с одним из значений:

Метка	Что она означает
`verified_onchain`	Прочитано с ноды этой сети в момент вашего запроса. Факт.
`augmented`	Cognivo Augmented Intelligence: предоставлено внешним источником, перепроверено, но не доказано Cognivo.
`interpretation`	Трактовка фактов со стороны Cognivo. Суждение, а не факт.
`unavailable`	Cognivo не смог это получить. Причина находится в `data.unavailable`.

Ничего не угадывается, не подставляется по умолчанию и не возвращается нулём, чтобы заполнить пробел.

meta.chain_data_source.cognivo_grounded сообщает, управляет ли Cognivo инфраструктурой, с которой пришло чтение. Cognivo держит собственную ноду Ethereum, поэтому чтения Ethereum имеют значение true. Чтения Base и BNB Chain приходят с внешней RPC-инфраструктуры, поэтому они false. Эти чтения точны, но они не обслуживаются оборудованием, которое контролирует Cognivo, и Cognivo говорит об этом прямо, а не позволяет вам думать иначе.

Ограничения в сети Base, которые также возвращаются в data.limitations:

Глубокий граф контроллеров работает только для Ethereum. В Base отнесение к контроллерам и команде строится на более узком анализе ролей кошельков.
Данные о деплойере в Base приходят из внешнего источника, а не из архивного чтения Cognivo. Считайте это сильной зацепкой, а не доказанным фактом.
Графики локов ликвидности в Base не декодируются. Используйте POST /v1/api/intel/liquidity для кастодии LP и доказательств сжигания, и не считайте отсутствие лока подтверждением того, что лока нет.

Этот эндпоинт сообщает только доказательства контроля над контрактом. Он ничего не говорит о ликвидности, и чистый результат никогда не означает, что контракт безопасен.

Только чтение: ничего не подписывается, транзакция не собирается, ничего не транслируется в сеть, и никакой кошелёк не делегируется.

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

POST /v1/api/wallet/pnl, право доступа Intelligence (`intel:read`)

Прибыль и убыток для одного кошелька по одному токену, рассчитанные по подтверждённым свопам в блокчейне. Требуются оба поля: wallet и token.

Прейскурантная цена: 10 кредитов за успешный вызов. Неудачные вызовы и результаты 422 без данных никогда не тарифицируются. Тарификация вызовов Developer API сегодня отключена, поэтому успешный вызов ничего не списывает и баланс не меняется.

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

Ответ: стандартная оболочка. data содержит реализованную величину и нереализованную величину по всё ещё удерживаемой позиции, когда существует обоснованная база стоимости.

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

POST /v1/api/wallet/approvals, право доступа Security (`security:read`)

Перечисляет одобрения на трату токенов, выданные кошельком, и помечает безлимитные allowance.

Необязательные limit и offset позволяют листать большие наборы одобрений.

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

Ответ: стандартная оболочка. data содержит список одобрений с контекстом получателя прав, токена и allowance.

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

POST /v1/api/wallet/exact-movements, право доступа Intelligence (`intel:read`)

Перечисляет точные движения токенов кошелька: покупки, продажи и переводы. Поле token необязательно и сужает чтение до одного токена.

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

Ответ: стандартная оболочка. data содержит список движений с количествами.

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

Discover

GET /v1/api/discover

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

Параметры запроса: 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'

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

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

Пока недоступно

Перечислено ради прозрачности, сегодня ничего не возвращает:

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

Дальнейшие шаги

Сделайте первый вызов по Быстрому старту, создайте ключ и задайте ему права доступа в Аутентификация и ключи, и прочитайте Лимиты запросов и ошибки, прежде чем ставить что-либо на расписание.

Что это за страница​

Где это найти в приложении​

Оболочка ответа​

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

Сколько стоит каждый эндпоинт​

Служебные​

GET /v1/api/health​

GET /v1/api/me​

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

POST /v1/api/intel/why-down, право доступа Intelligence (intel:read)​

POST /v1/api/intel/team-wallets, право доступа Intelligence (intel:read)​

POST /v1/api/intel/liquidity, право доступа Liquidity (liquidity:read)​

POST /v1/api/intel/risk, право доступа Intelligence (intel:read)​

POST /v1/api/contract/analysis, право доступа Contract (contract:read)​

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

POST /v1/api/wallet/pnl, право доступа Intelligence (intel:read)​

POST /v1/api/wallet/approvals, право доступа Security (security:read)​

POST /v1/api/wallet/exact-movements, право доступа Intelligence (intel:read)​

Discover​

GET /v1/api/discover​

Пока недоступно​

Дальнейшие шаги​