# Блокчейн RPC и MCP документации для ИИ-агентов

> Source: https://docs.blockvectra.com/ru/guides/ai-agents/

Начните с публичного эндпоинта [MCP документации](https://docs.blockvectra.com/mcp) без ключа, чтобы узнать методы блокчейн RPC, наборы данных Data API, цены и документацию. ИИ-агенты являются полноправными пользователями: разработчики и ИИ-агенты используют одни и те же API, правила, лимиты и цены.

1. **Изучение**: используйте MCP документации, `llms.txt`, OpenAPI и общедоступный JSON для выбора сети и метода. Вызовы RPC без ключа ограничены списком `public.methods` выбранной сети.
2. **Открытие аккаунта по HTTP**: следуйте [руководству по программной регистрации](https://docs.blockvectra.com/en/guides/programmatic-signup/), чтобы войти с помощью подписи кошелька и создать API key. Инструмент MCP `how_to_get_api_key` возвращает инструкции для этой отдельной процедуры HTTP.
3. **Вызов Data API**: сохраните ключ в переменной окружения `BLOCKVECTRA_API_KEY` и используйте его для аутентифицированных запросов к RPC или Data API. Для инструментов MCP, требующих ключ, настройте заголовок `x-api-key` клиента; список разрешенных операций для каждого инструмента приведен ниже.

## 1. Машиночитаемый контекст и спецификации

BlockVectra публикует файлы, ориентированные на LLM-агентов и инструменты разработчиков:

### Индексы llms.txt

Следуя соглашению [llmstxt.org](https://llmstxt.org), эти файлы предоставляют агентам структурированную сводку по сайту и его эндпоинтам:

* **Индекс основного сайта**: [llms.txt основного сайта](https://blockvectra.com/llms.txt) — обзор основного сайта, поддерживаемых сетей, тарифов и публичных API.
* **Индекс документации**: [llms.txt документации](https://docs.blockvectra.com/llms.txt) — каталог всех страниц документации с их заголовками и описаниями.

### Полный файл документации (llms-full.txt)

* **Полная документация**: [llms-full.txt](https://docs.blockvectra.com/llms-full.txt) — полный текст каждой англоязычной страницы документации в одном текстовом файле Markdown, подходящем для загрузки в системный промпт агента или добавления в пайплайн Retrieval-Augmented Generation (RAG).

### Скачиваемые спецификации OpenAPI 3.1

Сайт документации предоставляет YAML-файлы OpenAPI 3.1, которые можно напрямую импортировать во фреймворки агентов, генераторы инструментов или клиенты API:

* **Спецификация JSON-RPC API**: [/openapi/json-rpc.yaml](https://docs.blockvectra.com/openapi/json-rpc.yaml) — поддерживаемые методы, политики методов для каждой сети, ответы с ошибками и учет Compute Units.
* **Спецификация Data API**: [/openapi/data.yaml](https://docs.blockvectra.com/openapi/data.yaml) — определения REST-эндпоинтов для индексированных блоков, транзакций, переводов, балансов, держателей и сопутствующих наборов данных.
* **Спецификация Push API**: [/openapi/push.yaml](https://docs.blockvectra.com/openapi/push.yaml) — управление HTTP-подписками, отслеживаемые адреса кошельков, события вебхуков, подписи и replay (повторная доставка).

Для активности адресов кошельков следуйте [руководству по Blockchain Webhook API](https://docs.blockvectra.com/en/guides/webhook-push/). Для уведомлений о платежах ERC-20 USDT / USDC используйте [пример обработчика платежей](https://docs.blockvectra.com/en/guides/stablecoin-payments/#receive-payments-with-webhooks). Разработчики и ИИ-агенты создают подписки и управляют ими через HTTP Push API с заголовком `x-api-key`; MCP документации позволяет находить и читать эти руководства.

Правила версионирования путей, обратной совместимости и рекомендации для агентов и авторов SDK см. в разделе [Версионирование и совместимость API](https://docs.blockvectra.com/en/api/versioning/). Готовые примеры для популярных фреймворков (ElizaOS, viem, wagmi, Coinbase AgentKit) см. в разделе [Примеры для фреймворков агентов](https://docs.blockvectra.com/en/guides/agent-frameworks/).

### Сервер Model Context Protocol (MCP)

BlockVectra предоставляет сервер MCP без сохранения состояния (stateless) и без ключа через Streamable HTTP:

* **Эндпоинт**: [эндпоинт MCP](https://docs.blockvectra.com/mcp) (HTTP POST, принимающий JSON-RPC 2.0; GET возвращает 405)
* **Транспорт**: MCP Streamable HTTP (stateless, API key не требуется)

#### Доступные инструменты

1. `read_doc(path, lang?)`: возвращает исходное Markdown-содержимое любой страницы документации из `/md/{lang}/{path}.md`. Принимает внутренние относительные пути (например, `quickstart`, `guides/ai-agents`, `api/json-rpc`, `chains`).
2. `search_docs(query, lang?, limit?)`: ищет страницы документации по заголовкам, путям и описаниям.
3. `list_chains()`: считывает поддерживаемые блокчейн-сети, статические параметры и политики методов из `GET /v1/chains`.
4. `get_status()`: считывает оперативную готовность сервиса, статус сетей, актуальную высоту блоков и отставание синхронизации из `GET /v1/status`.
5. `get_pricing()`: считывает веса Compute Units (CU), параметры бесплатного тарифа (Free Plan) и стандартные лимиты ключей из `GET /v1/plans`.
6. `estimate_usage(lines?, method?, calls_per_day?)`: оценивает Compute Units (CU), базовую расчетную стоимость и чистую стоимость за вычетом бесплатной квоты цикла для одного или нескольких методов (поддерживает многострочный формат `lines: [{method, calls_per_day}]` или одиночные `method` и `calls_per_day`). Также сообщает лимиты частоты вызовов на ключ из `key_defaults` и рекомендует количество API key, если трафик превышает лимиты одного ключа.
7. `how_to_get_api_key(lang?)`: возвращает шаги получения API key и форматы аутентификации запросов для JSON-RPC и Data API.
8. `get_method_info(method, chain?)`: возвращает доступность в сети, вес Compute Unit (CU), цену за миллион вызовов и ссылку на документацию для метода. Доступность JSON-RPC определяется списками `methods.allow` и `deny` в `GET /v1/chains`; покрытие наборов данных Data API следует `data_features` в `GET /v1/status`, при наличии `data: true` в каталоге сетей.
9. `explain_error(reason?, code?, http_status?)`: находит пояснения к ошибкам, влияние на тарификацию, возможность повтора и действия по устранению из каталога ошибок.
10. `list_docs(lang?)`: выводит список всех страниц документации с относительными путями и заголовками из индекса документации.
11. `rpc_call(chain, method, params?)`: выполняет вызов JSON-RPC 2.0 только для чтения в поддерживаемой сети с вашим API key (`readOnlyHint: true`). Методы записи (такие как `eth_sendRawTransaction`) отклоняются; используйте вместо них `send_raw_transaction`. Требует заголовок `x-api-key` в конфигурации MCP-клиента для полного доступа или использует публичный эндпоинт без ключа, если он доступен.
12. `data_api_get(chain, path, query?)`: выполняет GET-запрос к Data API для поддерживаемой сети и пути с вашим API key (`readOnlyHint: true`). Требует заголовок `x-api-key` в конфигурации MCP-клиента.
13. `get_account()`: запрашивает баланс аккаунта, Compute Units (CU), лимиты частоты вызовов и параметры ключа из `GET /v1/account` с вашим API key (`readOnlyHint: true`). Требует заголовок `x-api-key` в конфигурации MCP-клиента.
14. `get_deposit_address()`: запрашивает выделенный ончейн-адрес депозита, открытые сети и токены из `GET /v1/topup/deposit-address` с вашим API key (`readOnlyHint: true`). Переводите средства только в указанные сети и токены. Требует заголовок `x-api-key` в конфигурации MCP-клиента.
15. `send_raw_transaction(chain, raw_tx)`: отправляет подписанную необработанную транзакцию (raw transaction) в поддерживаемую сеть через `eth_sendRawTransaction` (`destructiveHint: true`). Требует заголовок `x-api-key` в конфигурации MCP-клиента для полного доступа или использует публичный эндпоинт без ключа, если это разрешено в сети.

#### Инструменты, требующие ключ

Инструменты, требующие ключ, нуждаются в API key для выполнения ончейн-запросов, транзакций, обращений к Data API или операций с аккаунтом.

**Безопасность API key**:

* **Чтение строго из заголовков**: API key считывается исключительно из HTTP-заголовков запроса MCP-клиента (`x-api-key: rgw_...` или `Authorization: Bearer rgw_...`).
* **Никогда не передавайте ключи в чат**: никогда не передавайте API key или приватные ключи в аргументах инструментов и не вставляйте их в чат. Аргументы инструментов и история чата попадают в логи бесед и контекст; передача ключей в аргументах будет отклонена.

При вызове без заголовка API key эти инструменты возвращают `isError: true` и направляют агента к `how_to_get_api_key` и руководству по программной регистрации.

### Подключение из MCP-клиентов

Вы можете подключиться к MCP-серверу документации BlockVectra по адресу `https://docs.blockvectra.com/mcp` в распространенных средах разработки и фреймворках.

Начните работу без API key. Подключитесь к эндпоинту MCP, вызовите list\_chains, затем прочитайте quickstart с помощью read\_doc. Добавьте API key в HTTP-заголовки клиента, когда вам понадобятся Data API или инструменты для работы с аккаунтом. Доступ к RPC без ключа подчиняется политике публичных методов каждой сети.

Заголовок `x-api-key` необязателен. Без API key клиенты могут использовать все инструменты документации только для чтения (`read_doc`, `search_docs`, `list_docs`), обнаружение сетей (`list_chains`), актуальный статус (`get_status`), расчет стоимости (`get_pricing`, `estimate_usage`), пояснения к ошибкам (`explain_error`) и методы, разрешенные на публичных эндпоинтах. При использовании инструментов, требующих ключ (`rpc_call` для ограниченных методов, `send_raw_transaction`, `data_api_get`, `get_account` и `get_deposit_address`), настройте заголовок `x-api-key` со своим API key.

#### Claude Code

Подключитесь к MCP-серверу с помощью CLI:

```bash
claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp
```

Чтобы передать опциональный API key для инструментов, требующих аутентификации, используйте флаг `--header` (или `-H`):

```bash
claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp \
  --header "x-api-key: YOUR_API_KEY"
```

Официальная документация: [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).

#### Cursor

Добавьте сервер в конфигурацию MCP в Cursor:

```json
{
  "mcpServers": {
    "blockvectra": {
      "url": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

Cursor также поддерживает установку в один клик через deep link с использованием конфигурации в формате base64 `eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9` (соответствует `{"url":"https://docs.blockvectra.com/mcp"}`):

```text
cursor://anysphere.cursor-deeplink/mcp/install?name=blockvectra&config=eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9
```

Если требуются аутентифицированные инструменты (Data API или управление аккаунтом), добавьте объект `headers` с вашим API key:

```json
{
  "mcpServers": {
    "blockvectra": {
      "url": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

Официальная документация: [Cursor MCP documentation](https://cursor.com/docs/context/mcp) и [Cursor install links](https://cursor.com/docs/context/mcp/install-links).

#### VS Code

В VS Code настройте сервер в `.vscode/mcp.json` под ключом верхнего уровня `servers` с `type: "http"`:

```json
{
  "servers": {
    "blockvectra": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

Если требуются аутентифицированные инструменты, добавьте объект `headers`:

```json
{
  "servers": {
    "blockvectra": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

Для хранения конфиденциальных данных VS Code поддерживает ссылки на входные переменные или файлы переменных окружения вместо прямого указания ключей в коде. Серверы также можно добавлять через палитру команд действием `MCP: Add Server`.

Официальная документация: [VS Code MCP servers documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) и [VS Code MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

#### Codex

Добавьте сервер с помощью OpenAI Codex CLI:

```bash
codex mcp add blockvectra --url https://docs.blockvectra.com/mcp
```

В файле `config.toml` укажите URL сервера:

```toml
[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
```

Если требуются аутентифицированные инструменты, настройте заголовки запросов в `config.toml`:

```toml
[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
http_headers = { "x-api-key" = "YOUR_API_KEY" }
```

Либо сопоставьте заголовок с переменной окружения:

```toml
[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
env_http_headers = { "x-api-key" = "BLOCKVECTRA_API_KEY" }
```

Официальная документация: [OpenAI Codex CLI MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

#### Gemini CLI

В конфигурации Gemini CLI добавьте сервер в раздел `mcpServers`, используя `httpUrl` для Streamable HTTP:

```json
{
  "mcpServers": {
    "blockvectra": {
      "httpUrl": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

Если требуются аутентифицированные инструменты, добавьте объект `headers` с вашим API key:

```json
{
  "mcpServers": {
    "blockvectra": {
      "httpUrl": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

Официальная документация: [Gemini CLI MCP server documentation](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md).

#### OpenAI Responses API

При вызове OpenAI Responses API передайте MCP-сервер в массиве `tools` с `type: "mcp"`:

```bash
OPENAI_API_BASE="https://api.openai.com/v1"
curl "$OPENAI_API_BASE/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "tools": [{
      "type": "mcp",
      "server_label": "blockvectra",
      "server_url": "https://docs.blockvectra.com/mcp",
      "require_approval": "never"
    }],
    "input": "..."
  }'
```

Если требуются аутентифицированные инструменты, добавьте поле `headers` в определение инструмента:

```json
{
  "type": "mcp",
  "server_label": "blockvectra",
  "server_url": "https://docs.blockvectra.com/mcp",
  "headers": { "x-api-key": "YOUR_API_KEY" },
  "require_approval": "never"
}
```

Официальная документация: [OpenAI MCP tools guide](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) и [OpenAI Responses API reference](https://developers.openai.com/api/reference/resources/responses/methods/create).

#### Windsurf

В Windsurf настройте сервер в разделе `mcpServers`, используя поле `serverUrl`:

```json
{
  "mcpServers": {
    "blockvectra": {
      "serverUrl": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

Если требуются аутентифицированные инструменты, добавьте объект `headers` с вашим API key:

```json
{
  "mcpServers": {
    "blockvectra": {
      "serverUrl": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

Windsurf также поддерживает ссылки на переменные окружения, такие как `"x-api-key": "${env:BLOCKVECTRA_API_KEY}"`.

Официальная документация: [Windsurf MCP documentation](https://docs.devin.ai/desktop/cascade/mcp).

#### Claude Desktop и claude.ai

Пользовательские коннекторы настраиваются через пользовательский интерфейс:

* **claude.ai**: перейдите в **Настроить (Customize)** > **Коннекторы (Connectors)**, нажмите **+ Добавить (+ Add)**, выберите **Добавить пользовательский коннектор (Add custom connector)** и введите URL:
  ```text
  https://docs.blockvectra.com/mcp
  ```
* **Claude Desktop**: откройте меню настроек аккаунта и настройте пользовательские коннекторы через интерфейс коннекторов.

Подключение по этому URL позволяет Claude искать по руководствам, читать документацию в Markdown, просматривать поддерживаемые сети, проверять статус сети и рассчитывать ориентировочную стоимость без ввода учетных данных.

Официальная документация: [Claude custom connectors guide](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).

## 2. Публичные JSON-эндпоинты (ключ не требуется)

Агент может проверить доступные сети, статус в реальном времени и параметры тарифов перед отправкой тарифицируемых запросов. Ни один из этих эндпоинтов не требует API key:

* `GET /v1/status` и `GET /v1/chains` не требуют аутентификации и не тарифицируются.
* `GET /v1/plans` является публичным и не требует аутентификации.

Все три эндпоинта отправляют заголовок `Access-Control-Allow-Origin: *`.

### Статус сервиса (GET /v1/status)

Возвращает готовность сервиса и статус синхронизации каждой публичной сети:

```bash
curl -s "https://api.blockvectra.com/v1/status"
```

Поля ответа:

* `checked_at`: время формирования снимка состояния (RFC 3339 / ISO 8601 UTC).
* `gateway.status`: рабочий статус сервиса. `ok` означает готовность сервиса; `degraded` означает, что платные запросы отклоняются до восстановления. Это значение не зависит от статуса узлов отдельных сетей.
* `chains[]`: сети, обслуживаемые для общего доступа:
  * `chain`: слаг сети (например, `robinhood_mainnet`).
  * `name`: понятное отображаемое имя сети.
  * `chain_id`: EIP-155 Chain ID (десятичное целое число).
  * `jsonrpc`: обслуживается ли JSON-RPC.
  * `data`: обслуживается ли Data API.
  * `data_features`: возможности Data API, доступные для этой сети (пустой массив, если `data` равно `false`).
  * `data_status`: рабочий статус Data API (`ok`, `syncing` или `unavailable`; присутствует только если `data` равно `true`).
  * `status`: статус узла сети (`ok` или `unavailable`).
  * `head`: информация о последнем блоке — `block` (высота последнего блока), `time` (временная метка блока) и `lag_seconds` (на сколько время блока отстает от текущего времени) — или `null`, если неизвестно.

Пример ответа:

```json
{
  "checked_at": "2026-09-28T12:00:00Z",
  "gateway": {
    "status": "ok"
  },
  "chains": [
    {
      "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663,
      "jsonrpc": true,
      "data": true,
      "data_features": [
        "blocks",
        "transactions",
        "address_transactions",
        "transfers",
        "token_metadata",
        "freshness"
      ],
      "status": "ok",
      "head": {
        "block": 73017329,
        "time": "2026-09-28T11:59:58Z",
        "lag_seconds": 2
      }
    }
  ]
}
```

### Параметры сетей (GET /v1/chains)

Возвращает статические параметры каждой публичной сети и политику методов:

```bash
curl -s "https://api.blockvectra.com/v1/chains"
```

Поля ответа:

* `chains[]`: публичные сети и их статические параметры:
  * `chain`: слаг сети.
  * `name`: понятное отображаемое имя сети.
  * `chain_id`: EIP-155 Chain ID.
  * `jsonrpc`: обслуживается ли JSON-RPC.
  * `data`: обслуживается ли Data API.
  * `ws`: поддерживаются ли WebSocket-соединения.
  * `subscriptions`: поддерживаемые типы WebSocket-подписок (например, `newHeads`, `logs`).
  * `methods`: политика методов:
    * `allow`: разрешенные имена методов (например, `eth_call`, `debug_traceTransaction`).
    * `deny`: запрещенные методы или маски префиксов (например, `eth_newFilter`). Запрещенные методы имеют приоритет над разрешенными.
  * `max_logs_block_range`: максимальный диапазон блоков, допустимый в одном запросе `eth_getLogs`.
  * `state_window_blocks`: окно исторических состояний в блоках; `null`, если доступна полная история.
  * `info`: публичные данные расширения для сети (зарезервировано; в настоящее время пустой объект `{}`).
  * `public`: конфигурация публичного эндпоинта без аутентификации (или `null`):
    * `url`: базовый URL для публичных запросов.
    * `methods`: методы, разрешенные на публичном эндпоинте.
    * `rate_limit`: лимиты частоты вызовов (`per_ip_rps`, `burst`, `batch_max`).
    * `history_blocks`: история блоков, доступная на публичном эндпоинте.
    * `send_raw_rate_limit`: лимиты частоты вызовов для отправки транзакций через `eth_sendRawTransaction`.

Пример ответа:

```json
{
  "chains": [
    {
      "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663,
      "jsonrpc": true,
      "data": true,
      "ws": true,
      "subscriptions": [
        "newHeads",
        "logs"
      ],
      "methods": {
        "allow": [
          "eth_blockNumber",
          "eth_call",
          "eth_chainId",
          "debug_traceTransaction"
        ],
        "deny": [
          "eth_newFilter",
          "eth_newBlockFilter",
          "eth_newPendingTransactionFilter",
          "eth_getFilterLogs",
          "eth_getFilterChanges",
          "eth_uninstallFilter",
          "eth_subscribe",
          "eth_unsubscribe"
        ]
      },
      "max_logs_block_range": 1000,
      "state_window_blocks": 900,
      "info": {},
      "public": {
        "url": "https://api.blockvectra.com/v1/robinhood_mainnet/public",
        "methods": [
          "eth_chainId",
          "net_version",
          "eth_blockNumber",
          "eth_call"
        ],
        "rate_limit": {
          "per_ip_rps": 3,
          "burst": 20,
          "batch_max": 10
        },
        "history_blocks": 128,
        "send_raw_rate_limit": {
          "per_ip_rps": 1,
          "burst": 3
        }
      }
    }
  ]
}
```

### Тарифы и веса методов (GET /v1/plans)

Параметры тарифов отдаются по адресу `GET https://console-api.blockvectra.com/v1/plans`. Агент может запросить этот эндпоинт во время работы, чтобы узнать действующие лимиты бесплатного тарифа и вес каждого метода в Compute Units (CU):

* `free`: параметры бесплатного тарифа (Free Plan) — `signup_units` (стартовый бонус при регистрации в units), `monthly_units` (целевой баланс пополнения цикла в units), `window_days` (длительность цикла использования в днях) и `max_calls_per_sec` (ограничение частоты вызовов в секунду для бесплатного тарифа).
* `pricing`: параметры платных тарифов — `units_per_usd` (количество units за 1 USD), `cu_per_unit` (CU на unit) и `min_topup_usd` (минимальная сумма пополнения в USD).
* `method_weights`: вес CU за вызов, каждый элемент вида `{ "method": string, "cu_weight": number }`. `method` указывает имя или шаблон метода JSON-RPC, стандартные веса для методов вне списка или операцию Data API, например `data.<op>`. Веса задаются для метода и не разделяются по сетям.

## 3. Аутентификация и безопасность ключей

Агенты, выполняющие вызовы RPC, должны соблюдать следующие правила:

* **Аутентификация**: передавайте API key одним из трех способов. В пути: `POST /v1/{chain}/{api_key}` — при передаче в пути используется только ключ из пути, а оба заголовка игнорируются. В заголовке `x-api-key`: `POST /v1/{chain}` с `x-api-key: $BLOCKVECTRA_API_KEY`. В заголовке `Authorization`: `POST /v1/{chain}` с `Authorization: Bearer $BLOCKVECTRA_API_KEY`. При наличии обоих заголовков приоритет имеет непустой `x-api-key`; Bearer используется, только если `x-api-key` отсутствует или пуст. Один и тот же ключ работает во всех поддерживаемых сетях и в Data API (который принимает ключ только в заголовке `x-api-key`).
* **Безопасность ключей**: храните API key в серверных переменных окружения (например, `BLOCKVECTRA_API_KEY`) или в менеджере секретов. Никогда не встраивайте ключ в код браузера или клиентские сборки. Эндпоинты возвращают заголовок `Access-Control-Allow-Origin: *`, но они предназначены для вызова из бэкенд-сервисов, а не из браузера.
* **Учет расхода и переход на платный тариф**: использование учитывается в Compute Units (CU): каждый метод потребляет CU в соответствии со своим весом, а баланс, пулы CU и лимиты частоты вызовов бесплатного тарифа распределяются между всеми сетями. После платного пополнения ограничение частоты вызовов в секунду бесплатного тарифа больше не действует; для каждого ключа по-прежнему действуют лимит CU в секунду и емкость всплеска (burst). Неиспользованные бесплатные кредиты сохраняются на балансе и могут использоваться далее. Подробности см. на [странице цен](https://blockvectra.com/ru/pricing/).

> **У вас еще нет API key?**
>
> Если у вас есть кошелек Ethereum: следуйте [руководству по программной регистрации](https://docs.blockvectra.com/en/guides/programmatic-signup/), чтобы зарегистрироваться и создать API key с помощью подписи кошелька Ethereum без использования браузера. Идентичность агента — это его кошелек: если токен сессии или ключ утеряны, [повторно пройдите аутентификацию с тем же кошельком для их восстановления](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key). Если у вас нет кошелька: попросите пользователя войти на [console.blockvectra.com](https://console.blockvectra.com/login/?next=%2Fkeys%2F), создать ключ и задать его в переменной окружения `BLOCKVECTRA_API_KEY`. Не просите пользователя отправлять ключ в чат.


### Запрос баланса (GET /v1/account)

Агент может напрямую проверять текущий баланс ключа, лимиты CU и параметры ключа без расхода Compute Units (CU). Формат запроса, ограничения частоты вызовов и полные описания полей ответа см. в разделе [Запрос баланса: GET /v1/account](https://docs.blockvectra.com/en/guides/billing-rules/#query-balance-get-v1account).

## 4. Процесс выбора сети для агентов

Перед отправкой вызовов агент может выполнить следующие шаги:

1. **Проверьте сеть и ее политику методов**: вызовите `GET /v1/chains`, убедитесь, что целевая сеть существует и имеет `jsonrpc: true`, а метод, который планируется вызвать, разрешен в `methods.allow` и не запрещен в `methods.deny` (запрет имеет приоритет).
2. **Проверьте текущий статус**: вызовите `GET /v1/status` и убедитесь, что `gateway.status` равен `ok`, а `status` целевой сети равен `ok`; используйте `head.lag_seconds`, чтобы определить, достаточно ли актуальны данные сети для вашей задачи. Когда узел сети не синхронизирован, каждый метод, кроме `eth_chainId`, возвращает ошибку JSON-RPC `-32010` (HTTP 200, не тарифицируется), поэтому агент может подождать и повторить попытку или выбрать другую сеть.
3. **Отправьте запрос**: `POST /v1/{chain}` с заголовком `x-api-key` и стандартным телом JSON-RPC.

## 5. Минимальный рабочий пример

В приведенном ниже примере считывается `/v1/chains` для выбора сети, разрешающей `eth_blockNumber`, проверяется `/v1/status`, а затем один раз вызывается `eth_blockNumber`.

**cURL**

```bash
export BLOCKVECTRA_API_KEY="rgw_your_api_key"

# 1. List public chains and their method policy
curl -s "https://api.blockvectra.com/v1/chains"

# 2. Check the service and per-chain status
curl -s "https://api.blockvectra.com/v1/status"

# 3. Call eth_blockNumber on the chain you selected (e.g. robinhood_mainnet)
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -H "x-bv-meter: 1" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```


  **TypeScript**

```typescript
const apiKey = process.env.BLOCKVECTRA_API_KEY;

if (!apiKey) {
  throw new Error("Missing BLOCKVECTRA_API_KEY");
}

type ChainFacts = {
  chain: string;
  jsonrpc: boolean;
  methods: { allow: string[]; deny: string[] };
};

function matches(pattern: string, method: string): boolean {
  if (pattern === "*") return true;
  if (pattern.endsWith("*")) return method.startsWith(pattern.slice(0, -1));
  return pattern === method;
}

// 1. Fetch the public chain directory
const chainsRes = await fetch("https://api.blockvectra.com/v1/chains");
const { chains } = (await chainsRes.json()) as { chains: ChainFacts[] };

// 2. Select a chain that serves JSON-RPC and allows eth_blockNumber
const selected = chains.find(
  (chain) =>
    chain.jsonrpc &&
    !chain.methods.deny.some((pattern) => matches(pattern, "eth_blockNumber")) &&
    chain.methods.allow.some((pattern) => matches(pattern, "eth_blockNumber")),
);

if (!selected) {
  throw new Error("No chain found that allows eth_blockNumber");
}

// 3. Confirm the service and the selected chain are ready
const statusRes = await fetch("https://api.blockvectra.com/v1/status");
const status = await statusRes.json();
const chainStatus = status.chains?.find(
  (chain: { chain: string }) => chain.chain === selected.chain,
);

if (status.gateway?.status !== "ok" || chainStatus?.status !== "ok") {
  throw new Error(`Chain ${selected.chain} is currently unavailable`);
}

// 4. Call eth_blockNumber on the selected chain
const defaultEndpoint = "https://api.blockvectra.com/v1/robinhood_mainnet";
const rpcUrl = `${defaultEndpoint.slice(0, defaultEndpoint.lastIndexOf("/"))}/${selected.chain}`;
const rpcRes = await fetch(rpcUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": apiKey,
    "x-bv-meter": "1",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "eth_blockNumber",
    params: [],
  }),
});

console.log("Response:", await rpcRes.json());
```


  **Python**

```python
import os
import requests

api_key = os.environ["BLOCKVECTRA_API_KEY"]


def matches(pattern: str, method: str) -> bool:
    if pattern == "*":
        return True
    if pattern.endswith("*"):
        return method.startswith(pattern[:-1])
    return pattern == method


# 1. Fetch the public chain directory
chains = requests.get("https://api.blockvectra.com/v1/chains").json()["chains"]

# 2. Select a chain that serves JSON-RPC and allows eth_blockNumber
selected = next(
    (
        chain
        for chain in chains
        if chain["jsonrpc"]
        and not any(matches(p, "eth_blockNumber") for p in chain["methods"]["deny"])
        and any(matches(p, "eth_blockNumber") for p in chain["methods"]["allow"])
    ),
    None,
)

if selected is None:
    raise RuntimeError("No chain found that allows eth_blockNumber")

# 3. Confirm the service and the selected chain are ready
status = requests.get("https://api.blockvectra.com/v1/status").json()
chain_status = next(
    (c for c in status["chains"] if c["chain"] == selected["chain"]),
    None,
)

if (
    status["gateway"]["status"] != "ok"
    or chain_status is None
    or chain_status["status"] != "ok"
):
    raise RuntimeError(f"Chain {selected['chain']} is currently unavailable")

# 4. Call eth_blockNumber on the selected chain
default_endpoint = "https://api.blockvectra.com/v1/robinhood_mainnet"
rpc_url = f"{default_endpoint.rsplit('/', 1)[0]}/{selected['chain']}"
rpc_response = requests.post(
    rpc_url,
    headers={
        "Content-Type": "application/json",
        "x-api-key": api_key,
        "x-bv-meter": "1",
    },
    json={"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []},
).json()

print("Response:", rpc_response)
```


Успешный вызов возвращает стандартный объект ответа JSON-RPC:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x45a27f1"
}
```

Чтобы проверить списания CU за запрос и оставшиеся единицы баланса в заголовках ответа, передайте `x-bv-meter: 1`. Поведение заголовков и случаи ошибок см. в разделе [Заголовки ответа с балансом и списаниями](https://docs.blockvectra.com/en/guides/billing-rules/#http-status-codes-and-billing-rules).

## Следующие шаги

* [Изучите каталог наборов данных](https://blockvectra.com/ru/data/), чтобы увидеть все наборы данных, индексируемые BlockVectra.
* [Ознакомьтесь с бесплатным тарифом и ценами](https://blockvectra.com/ru/pricing/#free), чтобы узнать, что включено в ваш аккаунт.
* [Следуйте руководству по программной регистрации](https://docs.blockvectra.com/en/guides/programmatic-signup/), чтобы зарегистрироваться и создать API key с помощью подписи кошелька, или [войдите в консоль](https://console.blockvectra.com/login/?next=%2Fkeys%2F) для создания ключа.