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

Разработчики и AI Agent могут протестировать публичный RPC без ключа, а затем создать ключ для продолжения работы.

1. Получение высоты блока без ключа

Вызовите публичный эндпоинт JSON-RPC для примера сети без создания аккаунта и передачи API key:

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/public" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Значение id: 1 в ответе соответствует этому запросу; result — шестнадцатеричная высота блока, которая может меняться между вызовами. Если ответ содержит error, проверьте его код и причину. См. бесплатные публичные эндпоинты RPC, где перечислены публичные методы, диапазоны истории и лимиты на IP.

2. Создание API key

Перейдите в консоль, войдите с помощью GitHub, Google или кошелька Ethereum (аккаунт создается при первом входе) и создайте API key. Секретный ключ отображается только один раз: сохраните его в надежном месте и задайте в переменной окружения BLOCKVECTRA_API_KEY. Не используйте его в клиентском коде браузера. Новые аккаунты получают 30,000,000 CU при регистрации — банковская карта не требуется.

3. Отправка первого аутентифицированного запроса

Запросите высоту блока той же сети с заголовком x-api-key. URL заканчивается названием сети, без завершающего слэша:

: "${BLOCKVECTRA_API_KEY:?Set BLOCKVECTRA_API_KEY first}"

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

result снова содержит шестнадцатеричную высоту блока. Этот запрос расходует CU; см. справочник JSON-RPC для ознакомления с весами методов и кодами ошибок, а также Цены с актуальными тарифами. Новый ключ вступает в силу примерно через 5 секунд; если вы получаете invalid_api_key, подождите немного и повторите попытку. При возникновении других сбоев см. раздел Распространенные ошибки ниже.

4. Переход к бизнес-задачам

• Запрос ончейн-активности токенизированных акций в Robinhood Chain
• Пакетная выгрузка логов HyperEVM по частям
• Получение активности кошельков и переводов токенов через вебхуки

Справочник

API keys и баланс

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

Каждый ключ выглядит как префикс rgw_, за которым следуют 64 шестнадцатеричных символа, например rgw_1f2e... (сокращено). Храните его в секрете — любой, у кого есть ключ, может расходовать ваш баланс.

# Прямая публичная конечная точка:
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/public" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# Или с шаблоном резервного API key (по умолчанию публичный, если BLOCKVECTRA_API_KEY не задан):
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/${BLOCKVECTRA_API_KEY:-public}" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Следующие два публичных эндпоинта метаданных показывают статус сервиса и конфигурацию каждой сети; они не требуют API key и не тарифицируются.

Проверка статуса сервиса и состояния сетей

curl https://api.blockvectra.com/v1/status

Возвращает временную метку проверки checked_at, рабочий статус сервиса gateway.status, а также прогресс синхронизации узла sync, высоту головного блока и задержку head для каждой поддерживаемой сети:

{
  "checked_at": "2026-10-03T13:30:47Z",
  "gateway": {
    "status": "ok"
  },
  "chains": [
    {
      "chain": "bsc_mainnet",
      "name": "BNB Smart Chain",
      "chain_id": 56,
      "jsonrpc": true,
      "data": true,
      "data_features": [
        "blocks",
        "transactions",
        "address_transactions",
        "transfers",
        "token_metadata",
        "freshness"
      ],
      "data_status": "ok",
      "data_head_block": 125492675,
      "data_head_age_seconds": 3,
      "status": "ok",
      "sync": {
        "stage": "synced",
        "node_block": 125492676,
        "target_block": null
      },
      "head": {
        "block": 125492676,
        "time": "2026-10-03T13:30:45Z",
        "lag_seconds": 2
      }
    }
  ]
}

Запрос поддерживаемых сетей и политик методов

curl https://api.blockvectra.com/v1/chains

Возвращает chain_id каждой поддерживаемой сети, флаги возможностей для JSON-RPC, Data API и WebSocket, политики разрешенных и запрещенных методов (methods.allow и methods.deny), лимит диапазона блоков логов в одном запросе max_logs_block_range и окно исторического состояния state_window_blocks:

{
  "chains": [
    {
      "chain": "bsc_mainnet",
      "name": "BNB Smart Chain",
      "chain_id": 56,
      "jsonrpc": true,
      "data": true,
      "ws": false,
      "subscriptions": [],
      "methods": {
        "allow": [
          "eth_blockNumber",
          "eth_call",
          "eth_chainId",
          "eth_getLogs"
        ],
        "deny": [
          "eth_newFilter",
          "eth_subscribe",
          "eth_unsubscribe"
        ]
      },
      "max_logs_block_range": 1000,
      "state_window_blocks": 100,
      "info": {}
    }
  ]
}

Выбор сети

Каждый эндпоинт BlockVectra привязан к определенной сети: запросы JSON-RPC содержат имя сети {chain} в пути URL, а запросы Data API начинаются с него. Список доступных на данный момент сетей и их идентификаторов см. в разделе Поддерживаемые сети.

Примеры эндпоинтов JSON-RPC меняются в соответствии с выбранной сетью для примеров. Примеры Data API ниже используют robinhood_mainnet.

Другие варианты аутентификации и примеры на разных языках

Эндпоинты JSON-RPC привязаны к сети: POST /v1/{chain}/{api_key} с ключом в пути или POST /v1/{chain} с ключом в заголовке x-api-key. {chain} — это имя сети, которое также используется в Data API; пример эндпоинта имеет вид https://api.blockvectra.com/v1/robinhood_mainnet. Вызов eth_subscribe по HTTP возвращает -32601; подписки WebSocket перечислены для каждой сети в разделе Поддерживаемые сети. API отправляет заголовок Access-Control-Allow-Origin: *, однако вам следует хранить свой API key в секрете и выполнять запросы из бэкенд-сервиса, а не из клиентского кода браузера.

Вы можете передать ключ одним из трех способов: в пути URL (POST /v1/{chain}/{api_key}, при этом используется только ключ из пути, а оба заголовка игнорируются), в заголовке x-api-key или в заголовке Authorization: Bearer <api_key>.

Ключ в пути URL

: "${BLOCKVECTRA_API_KEY:?Set BLOCKVECTRA_API_KEY first}"

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/$BLOCKVECTRA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Ключ в заголовке запроса

: "${BLOCKVECTRA_API_KEY:?Set BLOCKVECTRA_API_KEY first}"

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Заголовок Authorization: Bearer <api_key> также поддерживается. При запросе POST /v1/{chain} непустой заголовок x-api-key имеет приоритет перед Bearer, а Bearer используется только в том случае, если x-api-key отсутствует или пуст. Формат с ключом в пути игнорирует оба заголовка.

Пакетные запросы

Отправьте массив, чтобы выполнить несколько вызовов в одном запросе (до 100 вызовов в пакете). Обратите внимание, что каждый API key имеет корзину CU (пополнение cu_per_sec, емкость burst_cu — по умолчанию 100 CU/s и всплеск (burst) 400 CU; после платного пополнения каждый ключ имеет минимум 2,000 CU/с и всплеск 10,000 CU, более высокие пользовательские лимиты сохраняются; отображается для каждого ключа в таблице Keys в консоли); отдельный запрос (включая весь пакет JSON-RPC), суммарный объем CU которого превышает емкость burst ключа, отклоняется с ошибкой -32022 request_exceeds_burst даже при соблюдении лимита в 100 вызовов на пакет; разделите его на более мелкие пакеты. В этом примере за один цикл запроса считываются идентификатор сети и баланс аккаунта:

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '[
    {"jsonrpc":"2.0","id":1,"method":"eth_chainId"},
    {"jsonrpc":"2.0","id":2,"method":"eth_getBalance","params":["0x1111111111111111111111111111111111111111","latest"]}
  ]'

Ответы возвращаются в виде массива в том же порядке, что и запросы, сопоставляясь по полю id.

Если сервер отклоняет пакет целиком (недостаточный баланс, ограничение частоты запросов, превышение burst-лимита или превышение допустимого размера пакета; см. Распространенные ошибки ниже), он возвращает один объект ошибки JSON-RPC вместо массива; в режиме viem batch: true это отображается как неинформативная ошибка UnknownRpcError, поэтому повторите одиночный вызов, чтобы увидеть фактическую ошибку.

Тарификация Compute Units (CU)

Каждый тарифицируемый вызов расходует Compute Units (CU): простые вызовы, такие как eth_blockNumber или eth_chainId, стоят меньше всего, стандартные операции чтения вроде eth_getBlockByNumber стоят немного больше, более тяжелые вызовы, такие как eth_call или eth_getLogs, стоят еще дороже, а методы трассировки выполнения (например, debug_traceTransaction) обходятся дороже всего. Плата за использование списывается с аккаунта за каждый почасовой период с округлением в меньшую сторону до целых расчетных единиц (1 единица = 1,000 CU), а остаток переносится на следующий период (таким образом, суммарно за все периоды списывается floor(всего CU / 1,000)); расчет происходит примерно через 15 минут после окончания периода. Например: 508 CU перенесенных + 2557 CU потребленных = 3065 CU, в результате чего списываются 3 расчетные единицы и 65 CU переносятся на следующий период. Актуальные цены см. в разделе Цены.

Полная таблица весов каждого метода и коды ошибок представлены в разделе Справочник API → JSON-RPC — на этой странице рассматривается только формат запросов.

Распространенные ошибки

Перечисленные выше отклоненные запросы никогда не тарифицируются. За каждый принятый вызов, получивший ответ, взимается плата в соответствии с опубликованным весом метода в CU; в таблице кодов ошибок перечислены случаи, которые не тарифицируются (см. колонку Billed в разделе Коды ошибок).

Вызовы Data API

Data API предоставляет доступ к данным блокчейна только для чтения (блоки, транзакции, балансы, держатели, активность на DEX и многое другое) в формате REST/JSON. Все маршруты, за исключением GET https://api.blockvectra.com/v1/data/chains, содержат префикс с идентификатором сети: robinhood_mainnet — это идентификатор сети (поле chain, возвращаемое эндпоинтом /chains и в объекте meta), используемый во всех приведенных ниже путях. Эндпоинт GET https://api.blockvectra.com/v1/data/chains возвращает список только публичных сетей и только поле {"data": [...]} (без meta и next_cursor). Запросы измеряются и тарифицируются в Compute Units (CU); тарифицируются только успешные ответы 2xx.

Для каждого запроса требуется тот же API key, что и для JSON-RPC — передавайте его в заголовке x-api-key. Каждый успешный ответ, привязанный к сети, содержит data (полезная нагрузка) и meta (chain, chain_slug (верхний регистр chain), chain_external_id, as_of_block, safe_block, finalized_block, coverage, refreshed_at; refreshed_at может быть null, что означает неизвестное время обновления данных и необходимость считать их устаревшими — эндпоинты на основе блоков всегда возвращают значение). Эндпоинты списков с пагинацией также могут возвращать next_cursor (непрозрачная строка, никогда не равна null). Передавайте полученный курсор обратно без изменений и продолжайте, пока next_cursor не исчезнет; некоторые эндпоинты возвращают оптимистичный курсор после полной страницы, поэтому следующая страница может быть пустой. Сведения о поддержке пагинации для каждого эндпоинта см. в справочнике Data API. Ответы с ошибками обычно содержат {"error":{"code","message"}} — 409 not_indexed_yet дополнительно возвращает indexed_through (наибольший проиндексированный блок). Неизвестная или непубличная сеть возвращает HTTP 404 с error.code not_found (не тарифицируется; имена сетей должны быть точными слагами в нижнем регистре); отсутствующий, неизвестный или отключенный API key возвращает HTTP 401 с error.code missing_api_key или invalid_api_key. Запросы, превысившие лимит частоты, возвращают HTTP 429 (error.code rate_limited, data.reason: "key_rate_limit"), а при исчерпании баланса возвращается HTTP 402 (error.code insufficient_balance); оба случая не тарифицируются. Значения, которые могут превышать 2^53 (балансы, объемы токенов), передаются в виде десятичных строк, а не JSON-чисел.

Получение блока по номеру:

curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/72838701" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

{
  "data": {
    "number": 72838701,
    "hash": "0x9f2c1e7a4b6d3f805e1c9a72b4d6f1e0a3c8b5d7e2f4a1c6b9d3e7f0a2c4b6d8",
    "parent_hash": "0x1a3c5e7f9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3c5e7b9d1f3a",
    "timestamp": "2026-09-26T05:41:07Z",
    "miner": "0x00000000000000000000000000000000000a4b05",
    "gas_limit": 32000000,
    "gas_used": 4821932,
    "base_fee_per_gas": "100000000",
    "state_root": "0x2b4d6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d",
    "transactions_root": "0x3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3c5e",
    "receipts_root": "0x4d6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f",
    "tx_count": 239,
    "size": 48213,
    "l1_block_number": null,
    "extra": {}
  },
  "meta": {
    "chain": "robinhood_mainnet",
    "chain_slug": "ROBINHOOD_MAINNET",
    "chain_external_id": "eip155:4663",
    "as_of_block": 72838957,
    "safe_block": 72838800,
    "finalized_block": 72838701,
    "coverage": "full",
    "refreshed_at": "2026-09-27T02:15:03Z"
  }
}

Номер блока выше проиндексированной вершины (as_of_block) возвращает 409 (error.code: "not_indexed_yet") с полем indexed_through, указывающим на наивысший проиндексированный блок — данные еще не готовы, повторите попытку позже. Номер блока, предшествующий покрываемой истории сети (coverage.from_block), возвращает 422 (error.code: "no_coverage"). В пределах диапазона покрытия номер блока на уровне или ниже as_of_block при отсутствии активной записи (никогда не индексировался или откатился в результате реорганизации) возвращает 404 (error.code: "not_found").

Проверка свежести данных (насколько каждый отслеживаемый набор данных отстает от вершины сети — полезно для страницы статуса или предварительной проверки перед отправкой запроса):

curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/status/freshness" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

{
  "data": [
    {
      "dataset": "blocks",
      "category": "raw",
      "max_block_number": 72838957,
      "max_day": null,
      "max_time": "2026-09-27T02:15:01Z",
      "seconds_behind": 0,
      "blocks_behind": null,
      "days_behind": null,
      "checked_at": "2026-09-27T02:15:07Z"
    }
  ],
  "meta": {
    "chain": "robinhood_mainnet",
    "chain_slug": "ROBINHOOD_MAINNET",
    "chain_external_id": "eip155:4663",
    "as_of_block": 72838957,
    "safe_block": 72838800,
    "finalized_block": 72838701,
    "coverage": "full",
    "refreshed_at": "2026-09-27T02:15:07Z"
  }
}

(Сокращено: в ответе возвращается по одной строке для каждого набора данных; показана только строка blocks. В строке traces также содержатся поля coverage_from_block, coverage_to_block и coverage_complete.)

Если данные о свежести для данной сети временно недоступны, возвращается 503 (error.code: "unavailable") вместо частичного результата; ответ содержит заголовок Retry-After (в секундах) — подождите указанное время перед повторным запросом.

Список балансов ERC-20 для адреса (снимок ненулевых балансов с сортировкой по токену):

curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/addresses/0x1111111111111111111111111111111111111111/balances" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

{
  "data": [
    { "token": "0x0bd7d308f8e1639fab988df18a8011f41eacad73", "balance": "185371464119396", "symbol": "WETH", "decimals": 18 },
    { "token": "0x2295f15bd4914ae9b4685f01d52f4e6f89bf8b03", "balance": "10000000000000000", "symbol": "WNVDA", "decimals": 18 }
  ],
  "meta": {
    "chain": "robinhood_mainnet",
    "chain_slug": "ROBINHOOD_MAINNET",
    "chain_external_id": "eip155:4663",
    "as_of_block": 72838957,
    "safe_block": 72838800,
    "finalized_block": 72838701,
    "coverage": "full",
    "refreshed_at": "2026-09-27T02:10:00Z"
  }
}

Для адреса без ненулевых балансов по-прежнему возвращается 200 с data: [] — никогда не 404. Передавайте параметр ?limit= (по умолчанию 50, максимум 500) и возвращаемый next_cursor для постраничной навигации.

Полный перечень эндпоинтов — блоки, транзакции, адреса, токены, NFT, DEX, токенизированные акции — доступен в разделе Справочник API → Data API.

Дополнительные материалы

• Справочник API → JSON-RPC — методы, веса CU, коды ошибок
• Полный справочник JSON-RPC — полные спецификации, параметры и схемы ответов для всех поддерживаемых методов
• Справочник API → Data API — REST-эндпоинты для данных блокчейна
• Наборы данных — производные наборы данных по поддерживаемым сетям
• Руководства — практические руководства по интеграции API, управлению CU и мультичейн-процессам
• Поддерживаемые сети — идентификаторы сетей и URL эндпоинтов

FAQ