# Блокчейн-RPC та docs MCP для AI-агентів

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

Почніть із [docs MCP ендпоінта](https://docs.blockvectra.com/mcp) без ключа, щоб дізнатися про методи блокчейн-RPC, набори даних Data API, ціни та документацію. AI-агенти є першокласними користувачами: розробники та AI-агенти використовують ті самі API, правила, ліміти та ціни.

1. **Дослідження**: використовуйте docs 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 для завантаження

Сайт документації надає файли OpenAPI 3.1 YAML, які можна імпортувати безпосередньо у фреймворки агентів, генератори інструментів або клієнти 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, адреси гаманців під спостереженням, події вебхуків, підписи та повторне відтворення.

Щоб відстежувати активність адрес гаманців, перегляньте [Посібник з 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). Розробники та AI-агенти створюють підписки та керують ними через HTTP Push API за допомогою `x-api-key`; docs 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 надає безстанний (stateless) MCP-сервер без ключа через Streamable HTTP:

* **Ендпоінт**: [MCP ендпоінт](https://docs.blockvectra.com/mcp) (HTTP POST, що приймає JSON-RPC 2.0; GET повертає 405)
* **Транспорт**: MCP Streamable HTTP (без стану, 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), параметри безкоштовного плану та ліміти ключів за замовчуванням з `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 keys, якщо трафік перевищує ліміти одного ключа.
7. `how_to_get_api_key(lang?)`: повертає кроки передачі API key та формати автентифікації запитів для JSON-RPC і Data API.
8. `get_method_info(method, chain?)`: повертає доступність у мережі, вагу Compute Units (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)`: транслює підписану необроблену транзакцію в підтримувану мережу через `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 keys або приватні ключі в аргументах інструментів і не вставляйте їх у чат. Аргументи інструментів та історія чату потрапляють до журналів і контекстів розмови; передача ключів в аргументах буде відхилена.

Якщо ці інструменти викликаються без заголовка 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](https://code.claude.com/docs/en/mcp).

#### Cursor

Додайте сервер до конфігурації MCP у Cursor:

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

Cursor також підтримує встановлення в один клік через діплінки за допомогою закодованої в 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](https://cursor.com/docs/context/mcp) та [Посилання для встановлення Cursor](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 підтримує посилання на вхідні змінні або файли середовища замість прямого внесення ключів у конфігурацію. Ви також можете додавати сервери за допомогою команди Command Palette `MCP: Add Server`.

Офіційна документація: [Документація серверів VS Code MCP](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) та [Довідник з конфігурації VS Code MCP](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

#### Codex

Додайте сервер за допомогою CLI OpenAI Codex:

```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](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"
      }
    }
  }
}
```

Офіційна документація: [Документація MCP-сервера Gemini CLI](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](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) та [Довідник OpenAI Responses API](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](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](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`: ідентифікатор мережі (slug, наприклад `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`: ідентифікатор мережі (slug).
  * `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` (бонус за реєстрацію в одиницях), `monthly_units` (рівень поповнення циклу в одиницях), `window_days` (тривалість циклу використання в днях) та `max_calls_per_sec` (обмеження викликів на секунду для безкоштовного плану).
* `pricing`: параметри платного плану — `units_per_usd` (одиниць за 1 USD), `cu_per_unit` (CU на одиницю) та `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 keys у змінних середовища на стороні сервера (наприклад, `BLOCKVECTRA_API_KEY`) або в менеджері секретів. Ніколи не вбудовуйте ключ у код браузера або будь-який клієнтський бандл. Ендпоінти повертають `Access-Control-Allow-Origin: *`, проте вони призначені для виклику бекенд-сервісами, а не з браузера.
* **Облік та оновлення**: використання обліковується в Compute Units (CU): кожен метод споживає CU відповідно до своєї ваги, а баланс, накопичувачі CU та обмеження швидкості безкоштовного плану є спільними для всіх мереж. Після платного поповнення обмеження викликів на секунду безкоштовного плану більше не застосовується; для кожного ключа продовжують діяти ліміт швидкості в CU та ємність burst. Невикористані безкоштовні кредити залишаються у вашому балансі й можуть використовуватися далі. Подробиці див. на [Сторінці цін](https://blockvectra.com/en/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/en/data/), щоб побачити кожен набір даних, який індексує BlockVectra.
* [Ознайомтеся з безкоштовним планом та цінами](https://blockvectra.com/en/pricing/#free), щоб перевірити, що включено у ваш акаунт.
* [Дотримуйтесь посібника з програмної реєстрації](https://docs.blockvectra.com/en/guides/programmatic-signup/), щоб зареєструватися та створити API key за допомогою підпису гаманця, або [увійдіть до консолі](https://console.blockvectra.com/login/?next=%2Fkeys%2F), щоб створити ключ.