Перейти к основному содержимому

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

Ваш первый вызов API Cognivo​

Cognivo Developer API позволяет вашему собственному коду задавать те же вопросы о данных блокчейна, которые вы задаёте в dApp и в Cognivo Chat. Эта страница проводит по самому короткому пути: создать проект, создать ключ, выполнить один настоящий вызов, прочитать ответ.

Когда это использовать​

Используйте API, когда вам нужны проверки токенов, кошельков или ликвидности внутри того, что вы создаёте: торгового бота, внутренней панели, задания оповещений или бэкенд-сервиса, вместо того чтобы каждый раз кликать в dApp. Если вы хотите запускать проверки вручную, dApp и Chat уже это умеют, и ключ вам не нужен.

Где это найти​

Войдите в dApp, откройте Account в боковой панели, затем выберите Developers. Посетители без входа видят только ознакомительный экран, поэтому сначала войдите. Всё, что описано на этой странице, происходит на одном этом экране.

Сначала проект, затем ключ​

Проект объединяет ваши API-ключи и их использование, поэтому начните с него.

  1. Нажмите «Новый проект», чтобы открыть короткую форму под выбором проекта.
  2. Введите название в поле «Название проекта», чтобы потом отличать свои проекты друг от друга.
  3. Нажмите «Создать», чтобы добавить проект, или «Отмена», чтобы закрыть форму без сохранения.
  4. Нажмите «Создать боевой ключ», чтобы сделать ключ для проекта, а затем передавайте его с запросами из своего кода.
Элементы управления проектами на странице Developers, где вы создаёте проект перед созданием ключа.Увеличить изображение

Имя проекта - это просто метка для вас. Оно не появляется в ваших запросах, и вы можете создать больше одного проекта, вплоть до предела, показанного на странице.

Когда вы выбираете Create live key, Cognivo показывает полный ключ ровно один раз, в диалоге с кнопкой копирования. Скопируйте его сразу и сохраните в надёжном месте. После этого страница показывает только замаскированную версию, префикс и последние четыре символа, потому что Cognivo хранит ключ в форме, которую не может прочитать обратно. Если вы потеряли ключ или считаете, что он утёк, используйте Rotate или Revoke в строке ключа. Старый ключ перестаёт работать сразу же.

У каждого ключа также есть Permissions, которые определяют, что он может вызывать: Intelligence, Security и Liquidity. Давайте ключу только те разрешения, которые ему нужны. Примеру ниже нужен Liquidity.

На той же карточке есть ещё две кнопки. Top up credits ведёт на страницу вашего биллинга. Enterprise access открывает обращение в поддержку, и это единственный путь, связанный с заявкой, для индивидуальных цен или повышенных лимитов. Обычному live-ключу одобрение не нужно, и он работает с момента создания.

Выполните пример вызова​

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

Вкладка «Быстрый старт» на странице Developers, где вы копируете рабочий пример вызова.Увеличить изображение

Карточка Test keys vs live keys объясняет разницу. Тестовый ключ делает безопасные вызовы с жёсткими лимитами, что удобно для настройки. Live-ключ делает настоящие вызовы, которые списываются с вашего баланса кредитов Cognivo. Карточка Test a live endpoint затем даёт пять пронумерованных шагов и саму команду, со значком копирования.

Команда представляет собой настоящую проверку ликвидности настоящего контракта в сети Base:

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

Тот же вызов из 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,
    "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);
}

Что приходит в ответ​

Каждый эндпоинт отвечает одной и той же оболочкой, которую показывает блок Expected response на вкладке Quickstart:

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

data содержит результат. meta.request_id стоит записывать в логи, потому что поддержка может найти по нему отдельный вызов. meta.credits_charged сообщает, во сколько именно обошёлся этот вызов.

Поле может вернуться пустым, неизвестным или недоступным. Это значит, что Cognivo не смог подтвердить его по данным, до которых у него есть доступ, а не что там ничего нет. Читайте это как «не подтверждено» и не считайте тихий результат разрешением. Cognivo сообщает, что он проверил и что нашёл, и ничто в ответе не доказывает, что токен является мошенническим, и не доказывает, что он безопасен.

Неудачный вызов отвечает с ok равным false, кодом error и request_id. Неудачные вызовы не тарифицируются.

Стоимость, сети и лимиты​

  • Некоторые эндпоинты бесплатны с любым активным ключом. Другие тарифицируются за каждый успешный вызов с вашего баланса кредитов Cognivo. Вкладка Endpoints перечисляет каждый эндпоинт с его ценой в кредитах Cognivo или пометкой Free, где он бесплатен, поэтому проверяйте цену там, прежде чем строить интеграцию с эндпоинтом.
  • Вы платите только за успешный вызов, и meta.credits_charged подтверждает сумму. Ошибки, таймауты и заблокированные вызовы не стоят ничего.
  • Каждый аккаунт получает 5 бесплатных кредитов в день. Они обновляются в полночь UTC и расходуются раньше любых платных кредитов.
  • Сегодня API охватывает Ethereum, Base и BNB Chain. Некоторые эндпоинты поддерживают меньше сетей, чем другие.
  • Тестовые ключи жёстко ограничены и не являются бесплатным продакшен-тарифом. Каждая строка ключа на вкладке Keys показывает лимиты, которые Cognivo применяет к этому ключу прямо сейчас, и они могут быть ниже значения по умолчанию для тарифа.
  • Приостановленный ключ, или ключ в приостановленном проекте, не может выполнить ничего, и портал показывает причину.

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

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

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

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