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

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

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

Канонический заголовок - 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 принимается как псевдоним для клиентских библиотек, которым он удобнее.

Как хранятся ключи​

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

Sandbox-ключи и live-ключи​

ПрефиксНазначениеТарифицируетсяЛимит запросов
cogv_test_Sandbox: только ограниченные демо и интеграционное тестирование, явно помечен как Sandbox; не может выполнять живую аналитикуникогда не тарифицируетсяжёсткий лимит 25 запросов/час, 100/день и 1/секунду
cogv_live_продакшен; self-serve, работает сразуpay-as-you-go: кредиты Cognivo за каждый успешный вызов с вашего баланса кредитов; неудачные вызовы никогда не тарифицируютсяваш лимит режима доступа, для начала 1,000 запросов/час

Если хотите, прототипируйте форматы запросов на sandbox-ключе, а выпускайте с live-ключом. Новому live-ключу не нужны ни одобрение, ни trial: он начинает работать в момент создания, пока на аккаунте есть кредиты.

Режимы доступа, простыми словами​

  • Live (стандартный) - self-serve pay-as-you-go. Новый live-ключ работает сразу; списание идёт в кредитах Cognivo за каждый успешный вызов по опубликованным ценам для каждого эндпоинта. Если баланса не хватает на вызов, вы получаете 402 payment_required (ничего не списано): пополните баланс на странице биллинга вашего аккаунта Cognivo и повторите.
  • Sandbox - ключи cogv_test_; только ограниченные демо/тестирование, живую аналитику выполнять не могут. Живые вызовы отвечают 403 sandbox_limited.
  • Trial - необязательная оценочная квота, выдаваемая администратором (ограниченная и с истекающим сроком). Для обычного платного использования не требуется.
  • Партнёрский - соглашение, управляемое администратором.
  • Enterprise - путь с запросом доступа: индивидуальные цены, индивидуальные лимиты и объёмы. Запросите его в портале разработчика.
  • Приостановленный (suspended) - ключ не может ничего выполнять; портал показывает причину.
  • Legacy-ключи «только метаданные» - небольшое число старых ключей появилось до self-serve биллинга и может вызывать только эндпоинты метаданных; живые вызовы отвечают 403 access_required. Создайте новый live-ключ, чтобы перейти на pay-as-you-go.

GET /v1/api/me сообщает, в каком режиме находится ваш ключ (access_mode), плюс credits_balance вашего аккаунта и подсказку top_up.

Скоупы (разрешения)​

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

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:read - проверки безопасности кошелька​

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

Открывает: POST /v1/api/wallet/approvals

liquidity:read - чтение ликвидности и LP​

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

Открывает: POST /v1/api/intel/liquidity

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

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

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

  • Отзыв (revoke) убивает ключ. Он перестаёт проходить аутентификацию в течение минуты.
  • Ротация (rotate) создаёт ключ-замену с тем же именем, скоупами и тарифом, показывает его один раз и в том же шаге отзывает старый ключ. Используйте её при любом подозрении на утечку и по регулярному расписанию.

Необязательные ограничения​

Для каждого ключа дополнительно можно задать allow-list:

  • Origins (точные origin или wildcard-поддомены вроде https://*.yourapp.com) - запросы с другим Origin отклоняются.
  • IP / диапазоны CIDR - запросы с других адресов отклоняются.

Пустые списки означают отсутствие ограничений.

Откуда берутся ключи​

Ключи создаются только в self-serve портале разработчика с использованием вашего существующего аккаунта Cognivo. Ручной/legacy выдачи ключей для новых интеграций не существует.