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

Аутентификация и API-ключи

Что такое API-ключ​

API-ключ - это секрет, который ваш код отправляет в Cognivo, чтобы мы знали, что запрос принадлежит вам. Каждый вызов Developer API несёт его. Ключи находятся внутри проекта, а проект объединяет ваши ключи и их использование.

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

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

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

На странице Developers четыре вкладки: Keys, Usage, Endpoints и Quickstart. Всё, что описано на этой странице, происходит на вкладке Keys.

Живой доступ и ваш баланс кредитов​

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

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

Панель «Live-доступ к API», ниже по странице Developers.Увеличить изображение

Каждый аккаунт Cognivo также получает 5 бесплатных кредитов ежедневно, они обновляются в полночь UTC. Смотрите Биллинг и кредиты о том, как работает баланс, и Лимиты запросов, ошибки и биллинг о ценах для каждого эндпоинта.

Вкладка Keys​

Выберите проект в выпадающем списке Project или создайте его через New project. После этого вкладка Keys перечисляет каждый ключ, который ему принадлежит.

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

Каждая строка ключа показывает данное вами имя, является ли ключ тестовым или live, применяемый часовой лимит, права доступа, которые он несёт, а также когда он был создан и когда использовался последний раз. Last used: Never означает, что с этим ключом ни разу не делали вызовов.

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

Создание ключа​

Выберите + New key. Форма спрашивает три вещи: необязательное имя, чтобы вам было проще различать ключи, режим Test или Live и как минимум одно право доступа.

Форма нового ключа на странице Developers, открытая кнопкой «Новый ключ».Увеличить изображение

Выбор Live показывает ваш баланс кредитов под выпадающим списком режима, как напоминание, что живые вызовы настоящие и тарифицируются с этого баланса. Выбор Test создаёт песочный ключ, который никогда не тарифицируется и имеет жёсткие лимиты.

Выберите Create key, и полный ключ появится один раз, в диалоге.

  1. Скопируйте полный ключ иконкой копирования, пока он ещё на экране: второй раз он показан не будет.
  2. Нажмите «Готово», когда ключ сохранён там, где вы сможете найти его позже.
Диалог с одноразовым показом ключа на вкладке «Ключи», он появляется в момент создания нового ключа.Увеличить изображение

Если вы потеряете ключ, восстановить его нельзя. Вместо этого выполните ротацию ключа, о которой рассказано ниже.

Отправка ключа​

Канонический заголовок - X-API-Key:

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":"eth","address":"0xTOKEN_CONTRACT"}'

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

Сегодня API охватывает Ethereum, Base и BNB Chain.

Права доступа​

Ключи работают по принципу «запрещено по умолчанию». Ключ может вызывать только те группы эндпоинтов, которые вы выдали при его создании. Прав доступа три, и каждое открывает свой набор эндпоинтов.

Intelligence (intel:read) - повседневное право. Оно отвечает на вопрос «что происходит с этим токеном или кошельком?»: драйверы падения цены, сигналы риска, поведение командных кошельков, реализованный PnL и точные движения. Оно открывает POST /v1/api/intel/why-down, POST /v1/api/intel/team-wallets, POST /v1/api/intel/risk, POST /v1/api/wallet/pnl и POST /v1/api/wallet/exact-movements.

Security (security:read) позволяет ключу проверять, что кошелёк одобрил, включая то, какие контракты могут тратить его токены и какие allowance безлимитны. Это только чтение. Ключ с этим правом никогда не сможет перемещать средства или отзывать одобрение. Оно открывает POST /v1/api/wallet/approvals.

Liquidity (liquidity:read) позволяет ключу читать контекст пула, кастодию LP, а также контекст локов и сжигания. Оно открывает POST /v1/api/intel/liquidity.

GET /v1/api/health вообще не требует ключа. GET /v1/api/me и GET /v1/api/discover работают с любым действительным ключом, независимо от его прав доступа.

Права доступа фиксируются в момент создания ключа. Чтобы изменить их, создайте новый ключ с нужными правами и отзовите старый. Вызов, завершившийся ошибкой 403 scope_denied, означает, что у ключа нет права доступа, которое требуется этому эндпоинту.

Тестовые ключи и live-ключи​

ПрефиксДля чего онТарификацияЛимит запросов
cogv_test_Знакомство с API. В портале помечен как Test и Sandbox. Не может выполнять живую аналитику.никогда не тарифицируется25 запросов в час, 100 в день, 1 в секунду
cogv_live_Настоящий трафик. Самообслуживание, работает сразу.кредиты Cognivo за каждый успешный вызов. Неудачные вызовы никогда не тарифицируются.1,000 запросов в час для начала, смотрите лимиты запросов

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

Портал также показывает режим доступа у каждого ключа. Paid - это обычная оплата по факту использования. Trial - временная оценочная квота с датой окончания. Partner и Enterprise - договорённости, оформленные с Cognivo. Suspended означает, что ключ не может ничего выполнять, и портал показывает причину. Небольшое число старых ключей появилось до self-serve биллинга и может вызывать только эндпоинты метаданных, поэтому живые вызовы отвечают 403 access_required. Создайте новый live-ключ, чтобы перевести их на оплату по факту использования.

GET /v1/api/me сообщает режим доступа вашего ключа, его права доступа, ваш credits_balance и подсказку по пополнению. Если баланса не хватает на вызов, вы получаете 402 payment_required, и ничего не списывается. Пополните баланс и повторите.

Ротация и отзыв​

Оба элемента управления находятся справа в каждой строке ключа.

  1. Посмотрите на метки Test и Sandbox рядом с именем, чтобы понять, что это за ключ, и на часовой лимит рядом с ними.
  2. Нажмите «Ротация», чтобы заменить этот ключ новым: новый показывается один раз, а старый перестаёт работать сразу же.
  3. Нажмите «Отозвать», чтобы отключить ключ навсегда, например если он больше не нужен или вы думаете, что его увидел кто-то посторонний.
Строки ключей на вкладке «Ключи» страницы Developers.Увеличить изображение

Ротация сначала просит подтверждение, и диалог точно описывает, что произойдёт.

Подтверждение ротации на вкладке «Ключи», оно появляется после нажатия «Ротация» у ключа.Увеличить изображение

Ключ после ротации сохраняет своё имя, права доступа, тариф, любое сетевое ограничение, любую дату истечения и любую оставшуюся квоту, поэтому ротация безопасна и никогда не расширяет незаметно возможности ключа. Замена показывается один раз, в том же диалоге, что и новый ключ. Отзыв необратим и сразу останавливает работу ключа на всех эндпоинтах.

Выполняйте ротацию при любом подозрении на утечку и по регулярному расписанию.

Ограничения, которые Cognivo может применить к ключу​

Они задаются в записи ключа, а не в форме портала, и применяются к каждому запросу. Проверить, что действует для вашего ключа, можно через GET /v1/api/me.

  • Сетевое ограничение. Ключ может быть ограничен конкретными сетями. Запрос, называющий другую сеть, отклоняется с 403 chain_denied. Отказ происходит до того, как Cognivo обратится к внешним источникам, и до расходования какой-либо квоты, поэтому вызов, который вашему ключу не разрешён, никогда ничего вам не стоит. Сообщается как allowed_chains, где null означает отсутствие ограничения.
  • Истечение срока. Ключу можно задать дату окончания. После её наступления ключ перестаёт работать везде, включая GET /v1/api/me, и возвращает 403 key_expired. Сообщается как expires_at, где null означает, что срок не истекает. Если у пробной квоты тоже есть дата окончания, действует та, что наступает раньше.
  • Списки разрешённых Origin и IP. Ключ может быть ограничен конкретными origin, включая поддомены с подстановкой вроде https://*.yourapp.com, или конкретными IP-адресами и диапазонами CIDR. Запросы из любых других мест отклоняются с 403 origin_denied. Пустые списки означают отсутствие ограничения.

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

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