Програмна реєстрація: вхід за допомогою гаманця та створення API ключа для агентів і CI

Для автономних AI-агентів, конвеєрів CI та автоматизованих скриптів, що працюють без браузера, BlockVectra надає робочий процес програмного входу та відкриття акаунта на основі підписів Ethereum-гаманця (EIP-4361 / EIP-191).

Перед реєстрацією ви можете спочатку спробувати публічний ендпоінт без ключа https://api.blockvectra.com/v1/robinhood_mainnet/public (тільки гаманцеві методи JSON-RPC, для Data API потрібен ключ; методи та ліміти визначаються /v1/chains); зареєструйте акаунт, якщо квоти недостатньо.

Огляд робочого процесу

Процес програмної реєстрації та створення ключів складається з чотирьох кроків:

1. Запит челенджу: надішліть запит до POST /auth/siwe/challenge, щоб отримати згенероване сервером повідомлення для входу.
2. Підпис повідомлення: підпишіть точний текст повідомлення за допомогою Ethereum EOA-гаманця з використанням EIP-191 (personal_sign).
3. Вхід / відкриття акаунта: надішліть точне повідомлення та підпис до POST /auth/siwe/login. Під час першого входу для гаманця акаунт створюється автоматично (account_created: true). Нові акаунти отримують 30,000,000 CU під час реєстрації — без кредитної картки.
4. Створення API ключа: використайте токен сесії для виклику POST /keys і створіть API ключ.

Повні готові до запуску приклади

Почніть звідси: використайте локальний інструмент підпису Ethereum EOA, створіть ключ і перевірте його за допомогою eth_blockNumber. Для прикладу з Bash вам знадобляться curl, jq та Foundry cast. Зберігайте облікові дані гаманця у вашому локальному середовищі підпису.

Повний стартовий шаблон: blockvectra/agent-quickstart

Наведені нижче скрипти читають облікові дані гаманця, виконують послідовність челенджу та входу, створюють API ключ, експортують або виводять export BLOCKVECTRA_API_KEY=... для налаштування середовища та надсилають перевірочний запит eth_blockNumber:

Новим ключам потрібно кілька секунд, щоб стати активними; ці приклади повторюють спроби автоматично.

BASE=https://console-api.blockvectra.com/v1
# $ADDR: Ethereum wallet address (0x...)
# $PK: wallet private key, loaded from a secrets manager (never hardcode in scripts)

# 1. Fetch server-generated SIWE message (omit Origin header)
curl -s "$BASE/auth/siwe/challenge" -H 'Content-Type: application/json' \
  -d "{\"address\":\"$ADDR\",\"purpose\":\"login\"}" > challenge.json
jq -r .message challenge.json > msg.txt

# 2. Sign the exact message with EIP-191 personal_sign
SIG=$(cast wallet sign --private-key "$PK" "$(cat msg.txt)")

# 3. Submit verbatim message and signature (omit Origin header) to log in (ref is optional)
jq -n --rawfile m msg.txt --arg s "$SIG" '{message: ($m | rtrimstr("\n")), signature: $s, ref: "docs-signup"}' |
  curl -s "$BASE/auth/siwe/login" -H 'Content-Type: application/json' -d @- > session.json
TOKEN=$(jq -r .session.token session.json)

# 4. Create an API key (the secret is returned only once)
KEY_RESP=$(curl -s "$BASE/keys" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"label":"agent-key"}')
export BLOCKVECTRA_API_KEY=$(echo "$KEY_RESP" | jq -r .api_key)

# 5. Call JSON-RPC with the key in the x-api-key request header
RPC_DEADLINE=$((SECONDS + 10))
while true; do
  RPC_TIMEOUT=$((RPC_DEADLINE - SECONDS))
  if ((RPC_TIMEOUT <= 0)); then
    printf '%s' "${RPC_BODY:-}"
    break
  fi
  RPC_RESP=$(curl -s --max-time "$RPC_TIMEOUT" -w '\n%{http_code}' "https://api.blockvectra.com/v1/robinhood_mainnet" \
    -H "x-api-key: $BLOCKVECTRA_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}') || { rc=$?; echo "request failed (curl exit $rc)" >&2; exit $rc; }
  RPC_STATUS=${RPC_RESP##*$'\n'}
  RPC_BODY=${RPC_RESP%$'\n'*}
  if ((SECONDS + 2 < RPC_DEADLINE)) &&
    printf '%s' "$RPC_BODY" | jq -e --arg status "$RPC_STATUS" '
      ($status == "401" and .error.data.reason == "invalid_api_key") or
      ($status == "503" and .error.code == -32021)
    ' >/dev/null 2>&1; then
    sleep 2
  else
    printf '%s' "$RPC_BODY"
    break
  fi
done

Базовий URL та програмний режим

Усі ендпоінти автентифікації та керування ключами використовують офіційний базовий URL:

https://console-api.blockvectra.com/v1

Опущення заголовка Origin

Програмні запити працюють у програмному режимі:

• Обидва запити: челендж (POST /auth/siwe/challenge) та вхід (POST /auth/siwe/login) не повинні містити заголовок Origin (curl та стандартні HTTP-клієнти за замовчуванням опускають цей заголовок; не додавайте його вручну).
• Якщо заголовок Origin надіслано, але він не є налаштованим доменом вебконсолі (включаючи порожній рядок або null), запит челенджу повертає HTTP 400 invalid_request.
• Якщо режим під час входу не збігається з режимом челенджу (наприклад, запит програмного челенджу без Origin, а потім відправка входу із заголовком Origin, або навпаки), запит входу повертає HTTP 400 siwe_invalid з reason: domain_mismatch.

Цілісність повідомлення та вимоги до гаманця

• Точний підпис та відправка: клієнти повинні підписати та надіслати текст повідомлення точно в такому вигляді, як його повернув ендпоінт челенджу. Не змінюйте пробіли, домен, chain ID чи будь-які інші поля. Будь-яка зміна призводить до HTTP 400 siwe_invalid з reason: signature.
• Підтримувані гаманці: Externally Owned Accounts (EOA) в Ethereum mainnet (Chain ID 1). Підпис має бути 65-байтним підписом ECDSA (personal_sign). Контрактні гаманці (EIP-1271) та смарт-акаунти не підтримуються.
• Дійсність челенджу: кожен nonce челенджу є одноразовим і втрачає силу через 5 хвилин.

Тіло запиту та атрибуція реєстрації (необов'язково)

Тіло запиту POST /auth/siwe/login приймає обов'язкові параметри автентифікації та необов'язкові поля атрибуції реєстрації:

• Обов'язкові поля:
  • message: повний рядок повідомлення SIWE, отриманий від ендпоінта челенджу.
  • signature: 65-байтний шістнадцятковий підпис (із префіксом 0x), створений шляхом підписання message за допомогою EIP-191 в Ethereum-гаманці.
• Необов'язкові поля атрибуції (зберігаються лише один раз під час створення нового акаунта; ігноруються під час наступних входів):
  • ref: токен каналу в нижньому регістрі, що відповідає ^[a-z0-9._-]{1,64}$ (рядкові літери ASCII, цифри, ., _, -, від 1 до 64 символів). Наприклад, автономні агенти можуть встановити значення свого фреймворку або ідентифікатора середовища виконання (наприклад, my-agent.v1). Некоректні значення (включаючи великі літери, порожні рядки, перевищення довжини або непідтримувані символи) повертають HTTP 400 invalid_request без переведення регістру і блокують створення акаунта; опускайте або передавайте null, якщо не застосовується.
  • referrer: рядок вихідного URL або імені хоста; лише нерядкові типи повертають HTTP 400.

Надсилання невизначених полів, таких як signup_method, повертає HTTP 400 invalid_request.

Токени сесії та API ключі

Життєвий цикл токена сесії

• Формат: rgs_, за яким слідують 64 шістнадцяткові символи в нижньому регістрі.
• Дійсність: абсолютний термін дії 7 днів; автоматично закінчується після 24 годин бездіяльності.
• Без refresh token: коли термін дії токена сесії закінчується, почніть новий процес челенджу та входу.
• Заголовок: передавайте токен сесії в заголовку запиту Authorization: Bearer rgs_....

Створення API ключа

• Викличте POST /keys із токеном сесії, щоб створити API ключ (rgw_, за яким слідують 64 шістнадцяткові символи).
• На один акаунт дозволено не більше 20 невідкликаних і нетермінованих ключів (active + disabled); прострочені ключі не враховуються. Перевищення повертає HTTP 409 key_limit_reached з reason: active_keys та limit: 20; спочатку відкличте ключ. Ліміт діє для всіх ідентифікаторів, сесій та мереж акаунта. Створення та ротація ключів також обмежені 20 операціями за 24 години; перевищення повертає HTTP 429 rate_limited з Retry-After: 3600.
• Необов'язковий ліміт і термін дії: ви можете вказати cu_cap (загальний ліміт CU для ключа на весь час його дії, що є м'яким лімітом) та термін дії (expires_in_secs або expires_at, аж до максимальної кількості днів, дозволеної політикою ключів); після закінчення терміну дії або вичерпання ліміту сервер повертає 403 (JSON-RPC -32025, reason key_expired або key_cap_exhausted).
• Секретний api_key повертається лише один раз під час створення. Негайно збережіть його в надійному менеджері секретів або змінних середовища.
• Один API ключ працює в усіх підтримуваних мережах для JSON-RPC та Data API.

Втратили сесію або API ключ?

У BlockVectra ідентичність акаунта агента прив'язана до адреси Ethereum-гаманця, використаної під час реєстрації. Якщо термін дії вашого токена сесії закінчився або API ключ втрачено чи скомпрометовано, ви можете відновити повний контроль, використовуючи лише цей гаманець:

1. Повторна автентифікація з тим самим гаманцем: запитайте челендж, підпишіть його тим самим гаманцем і надішліть запит на вхід (POST /auth/siwe/login). Сервер перевіряє підпис, входить до наявного акаунта з account_created: false та видає новий токен сесії.
2. Створення нового API ключа: із новим токеном сесії викличте POST /keys з {"label": "..."} та заголовком Authorization: Bearer <token>. Ендпоінт повертає HTTP 201 з даними створеного ключа в key та одноразовим секретом в api_key. Негайно збережіть цей ключ у змінних середовища або менеджері секретів.
3. Список усіх ключів акаунта:
   • Ендпоінт: GET /keys
   • Заголовок: Authorization: Bearer <token>
   • Параметр запиту: необов'язковий include_revoked=true (якщо true, включає відкликані ключі; за замовчуванням повертаються лише активні/відключені ключі).
   • Відповідь: HTTP 200 з JSON {"items": [...]}. Кожен елемент масиву items містить:
     • key_id: унікальний ідентифікатор ключа (string)
     • label: мітка ключа (string або null)
     • status: статус ("active", "disabled" або "revoked")
     • created_at: позначка часу створення (рядок ISO 8601)
     • revoked_at: позначка часу відкликання (string або null, якщо не відкликано)
4. Відкликання невикористаних або скомпрометованих ключів:
   • Ендпоінт: POST /keys/{key_id}/revoke (зверніть увагу: використовується POST із цільовим key_id у шляху; порожнє тіло запиту)
   • Заголовок: Authorization: Bearer <token>
   • Поведінка: ідемпотентна; ключі зі статусом active або disabled можуть бути відкликані. Якщо ключ уже відкликано, повертається HTTP 200 без змін. Після відкликання запити з цим ключем відхиляються.
   • Відповідь: HTTP 200, що повертає об'єкт відкликаного ключа (поля відповідають об'єкту ключа вище, зі status: "revoked" та позначкою часу в revoked_at).

Рекомендації з безпеки

• Використовуйте короткострокові ключі та відкликайте їх після завершення: для автоматизованих або ефемерних завдань створюйте короткоживучі ключі з expires_in_secs та негайно відкликайте їх через POST /keys/{key_id}/revoke після завершення роботи.

Ліміти запитів на реєстрацію (signup_rate_limited)

Створення акаунтів підлягає обмеженням частоти реєстрацій. Кошик токенів (token bucket) для кожної IP-адреси має місткість 100 акаунтів і поповнюється зі швидкістю 100 акаунтів/годину на IPv4-адресу або префікс IPv6 /64, спільно для реєстрацій через SIWE та OAuth:

• У разі перевищення лімітів реєстрації POST /auth/siwe/login повертає HTTP 429 signup_rate_limited із заголовком Retry-After, що вказує кількість секунд очікування.
• Поле reason визначає область дії ліміту:
  • per_ip: вичерпано бюджет реєстрацій для префікса IP, що запитує.
  • global: вичерпано сукупний ліміт реєстрацій на платформі.
• Ліміти частоти реєстрацій оцінюють лише створення нових акаунтів. Вхід у наявні акаунти не блокується лімітами реєстрації.

Пов'язані ресурси

• Прочитайте посібник з інтеграції AI-агентів, щоб дізнатися про MCP-сервер без ключа та машиночитні файли контексту.
• Ознайомтеся зі швидким стартом для прикладів клієнтів різними мовами.
• Перегляньте довідник помилок для отримання повного списку кодів помилок, причин та автоматизованих дій з відновлення.

Наступні кроки

• Надішліть свій перший виклик JSON-RPC або Data API з x-api-key: $BLOCKVECTRA_API_KEY.
• Перевірте баланс і ліміти акаунта за допомогою GET /v1/account.
• Дотримуйтесь посібника з програмного поповнення для агентів, щоб підтримувати баланс.