# RPC blockchain và MCP tài liệu cho AI Agent

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

Bắt đầu với [endpoint MCP tài liệu](https://docs.blockvectra.com/mcp) không cần key để khám phá phương thức RPC blockchain, bộ dữ liệu Data API, giá và tài liệu. AI Agent là người dùng được hỗ trợ đầy đủ: nhà phát triển và AI Agent dùng cùng API, quy tắc, giới hạn và giá.

1. **Khám phá**: dùng MCP tài liệu, `llms.txt`, OpenAPI và JSON công khai để chọn chuỗi và phương thức. Lệnh gọi RPC không cần key bị giới hạn ở `public.methods` của chuỗi.
2. **Mở tài khoản qua HTTP**: làm theo [đăng ký bằng chương trình](https://docs.blockvectra.com/en/guides/programmatic-signup/) để đăng nhập bằng chữ ký ví và tạo API key. `how_to_get_api_key` của MCP trả hướng dẫn cho luồng HTTP riêng này.
3. **Gọi API dữ liệu**: giữ key trong `BLOCKVECTRA_API_KEY` và dùng cho yêu cầu RPC hoặc Data API có xác thực. Với công cụ MCP cần key, cấu hình header `x-api-key` của client; các thao tác được phép của từng công cụ được liệt kê bên dưới.

## 1. Ngữ cảnh và đặc tả máy đọc được

BlockVectra công bố các tệp dành cho LLM Agent và công cụ phát triển:

### Chỉ mục llms.txt

Theo quy ước [llmstxt.org](https://llmstxt.org), các tệp này cung cấp cho Agent bản tóm tắt có cấu trúc của trang web và các endpoint:

* **Chỉ mục trang chính**: [llms.txt trang chính](https://blockvectra.com/llms.txt) — tổng quan trang chính, các chuỗi được hỗ trợ, giá và API công khai.
* **Chỉ mục tài liệu**: [llms.txt tài liệu](https://docs.blockvectra.com/llms.txt) — danh mục mọi trang tài liệu với tiêu đề và mô tả.

### Tệp tài liệu đầy đủ (`llms-full.txt`)

* **Tài liệu đầy đủ**: [llms-full.txt](https://docs.blockvectra.com/llms-full.txt) — toàn văn mọi trang tài liệu tiếng Anh trong một tệp Markdown văn bản thuần, phù hợp để nạp vào system prompt của Agent hoặc đưa vào pipeline Retrieval-Augmented Generation (RAG).

### Đặc tả OpenAPI 3.1 có thể tải xuống

Trang tài liệu phục vụ tệp YAML OpenAPI 3.1 có thể nhập trực tiếp vào framework Agent, bộ tạo công cụ hoặc API client:

* **Đặc tả JSON-RPC API**: [/openapi/json-rpc.yaml](https://docs.blockvectra.com/openapi/json-rpc.yaml) — phương thức được hỗ trợ, chính sách phương thức theo chuỗi, phản hồi lỗi và đo lường Compute Unit.
* **Đặc tả Data API**: [/openapi/data.yaml](https://docs.blockvectra.com/openapi/data.yaml) — định nghĩa endpoint REST cho khối, giao dịch, chuyển tiền, số dư, người nắm giữ và bộ dữ liệu liên quan được lập chỉ mục.
* **Đặc tả Push API**: [/openapi/push.yaml](https://docs.blockvectra.com/openapi/push.yaml) — quản lý đăng ký qua HTTP, địa chỉ ví theo dõi, sự kiện Webhook, chữ ký và phát lại.

Với hoạt động địa chỉ ví, làm theo [hướng dẫn Blockchain Webhook API](https://docs.blockvectra.com/vi/guides/webhook-push/). Với thông báo thanh toán ERC-20 USDT / USDC, dùng [ví dụ bộ nhận thanh toán](https://docs.blockvectra.com/vi/guides/stablecoin-payments/#receive-payments-with-webhooks). Nhà phát triển và AI Agent tạo và quản lý đăng ký qua HTTP Push API với `x-api-key`; MCP tài liệu cung cấp khả năng khám phá và đọc các hướng dẫn này.

Để biết phiên bản đường dẫn, quy tắc tương thích ngược và khuyến nghị cho tác giả Agent và SDK, xem [Phiên bản và tương thích API](https://docs.blockvectra.com/en/api/versioning/). Để xem công thức sẵn dùng trên các framework phổ biến (ElizaOS, viem, wagmi, Coinbase AgentKit), xem [Công thức framework Agent](https://docs.blockvectra.com/en/guides/agent-frameworks/).

### Máy chủ Model Context Protocol (MCP)

BlockVectra cung cấp máy chủ MCP không trạng thái, không cần key qua Streamable HTTP:

* **Endpoint**: [Endpoint MCP](https://docs.blockvectra.com/mcp) (HTTP POST nhận JSON-RPC 2.0; GET trả 405)
* **Truyền tải**: MCP Streamable HTTP (không trạng thái, không cần API key)

#### Công cụ khả dụng

1. `read_doc(path, lang?)`: trả nội dung Markdown thô cho bất kỳ trang tài liệu nào từ `/md/{lang}/{path}.md`. Chấp nhận đường dẫn tương đối nội bộ (ví dụ `quickstart`, `guides/ai-agents`, `api/json-rpc`, `chains`).
2. `search_docs(query, lang?, limit?)`: tìm kiếm trang tài liệu theo tiêu đề, đường dẫn và tóm tắt.
3. `list_chains()`: đọc mạng blockchain được hỗ trợ, tham số tĩnh và chính sách phương thức từ `GET /v1/chains`.
4. `get_status()`: đọc mức sẵn sàng hiện tại của dịch vụ, trạng thái mạng, độ cao khối mới nhất và độ trễ đồng bộ từ `GET /v1/status`.
5. `get_pricing()`: đọc trọng số Compute Unit (CU), tham số gói miễn phí và giới hạn key mặc định từ `GET /v1/plans`.
6. `estimate_usage(lines?, method?, calls_per_day?)`: ước tính Compute Unit (CU), chi phí niêm yết gộp và chi phí ròng sau khi trừ hạn mức miễn phí theo chu kỳ cho một hoặc nhiều phương thức (hỗ trợ nhiều dòng `lines: [{method, calls_per_day}]` hoặc một `method` và `calls_per_day`). Cũng báo giới hạn tốc độ theo key từ `key_defaults` và đề xuất số API key cần khi lưu lượng vượt giới hạn một key.
7. `how_to_get_api_key(lang?)`: trả các bước nhận API key và hình thức xác thực yêu cầu cho JSON-RPC và Data API.
8. `get_method_info(method, chain?)`: trả khả năng dùng trên chuỗi, trọng số Compute Unit (CU), giá mỗi triệu lệnh gọi và liên kết tài liệu của phương thức. Khả năng JSON-RPC tuân theo `methods.allow` và `deny` trong `GET /v1/chains`; phạm vi bộ dữ liệu Data API tuân theo `data_features` trong `GET /v1/status`, với `data: true` trong danh mục chuỗi.
9. `explain_error(reason?, code?, http_status?)`: tra giải thích lỗi, ảnh hưởng tính phí, khả năng thử lại và thao tác khôi phục từ danh mục lỗi.
10. `list_docs(lang?)`: liệt kê mọi trang tài liệu với đường dẫn tương đối và tiêu đề từ chỉ mục tài liệu.
11. `rpc_call(chain, method, params?)`: thực hiện lệnh gọi JSON-RPC 2.0 chỉ đọc trên chuỗi được hỗ trợ bằng API key (`readOnlyHint: true`). Phương thức ghi (chẳng hạn `eth_sendRawTransaction`) bị từ chối; dùng `send_raw_transaction` thay thế. Cần header `x-api-key` trong cấu hình MCP client để truy cập đầy đủ, hoặc dùng endpoint công khai không cần key nếu có.
12. `data_api_get(chain, path, query?)`: gửi yêu cầu GET tới Data API cho chuỗi và đường dẫn được hỗ trợ bằng API key (`readOnlyHint: true`). Cần header `x-api-key` trong cấu hình MCP client.
13. `get_account()`: truy vấn số dư tài khoản, Compute Unit (CU), giới hạn tốc độ và tham số key từ `GET /v1/account` bằng API key (`readOnlyHint: true`). Cần header `x-api-key` trong cấu hình MCP client.
14. `get_deposit_address()`: truy vấn địa chỉ nạp tiền trên chuỗi riêng, mạng đang mở và token từ `GET /v1/topup/deposit-address` bằng API key (`readOnlyHint: true`). Chỉ chuyển tới mạng và token trong danh sách. Cần header `x-api-key` trong cấu hình MCP client.
15. `send_raw_transaction(chain, raw_tx)`: phát giao dịch thô đã ký tới chuỗi được hỗ trợ qua `eth_sendRawTransaction` (`destructiveHint: true`). Cần header `x-api-key` trong cấu hình MCP client để truy cập đầy đủ, hoặc dùng endpoint công khai không cần key nếu chuỗi cho phép.

#### Công cụ cần key

Công cụ cần key yêu cầu API key để thực hiện truy vấn trên chuỗi, giao dịch, yêu cầu Data API hoặc thao tác tài khoản.

**Bảo mật API key**:

* **Chỉ đọc từ header**: API key chỉ được đọc từ header yêu cầu HTTP của MCP client (`x-api-key: rgw_...` hoặc `Authorization: Bearer rgw_...`).
* **Tuyệt đối không đưa key vào chat**: Không truyền API key hoặc private key trong tham số công cụ hay dán vào chat. Tham số công cụ và lịch sử chat đi vào log và ngữ cảnh hội thoại; key truyền qua tham số sẽ bị từ chối.

Nếu gọi mà không có header API key, các công cụ này trả `isError: true` và hướng Agent tới `how_to_get_api_key` cùng hướng dẫn đăng ký bằng chương trình.

### Kết nối từ MCP client

Bạn có thể kết nối tới máy chủ MCP tài liệu BlockVectra tại `https://docs.blockvectra.com/mcp` trên các môi trường phát triển và framework phổ biến.

Bắt đầu không cần API key. Kết nối tới endpoint MCP, gọi list\_chains, rồi đọc quickstart bằng read\_doc. Thêm API key vào header HTTP của client khi cần công cụ Data API hoặc tài khoản. Truy cập RPC không cần key tuân theo chính sách phương thức công khai của từng chuỗi.

Header `x-api-key` là tùy chọn. Không có API key, client dùng được mọi công cụ tài liệu chỉ đọc (`read_doc`, `search_docs`, `list_docs`), khám phá chuỗi (`list_chains`), trạng thái hiện tại (`get_status`), ước tính giá (`get_pricing`, `estimate_usage`), giải thích lỗi (`explain_error`) và phương thức được phép trên endpoint công khai. Khi dùng công cụ cần key (`rpc_call` cho phương thức bị hạn chế, `send_raw_transaction`, `data_api_get`, `get_account` và `get_deposit_address`), cấu hình header `x-api-key` bằng API key.

#### Claude Code

Kết nối tới máy chủ MCP bằng CLI:

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

Để thêm API key tùy chọn cho công cụ có xác thực, truyền tùy chọn `--header` (hoặc `-H`):

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

Tài liệu chính thức: [Tài liệu MCP Claude Code](https://code.claude.com/docs/en/mcp).

#### Cursor

Thêm máy chủ vào cấu hình MCP của Cursor:

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

Cursor cũng hỗ trợ cài đặt bằng một lần nhấp qua deep link dùng cấu hình mã hóa base64 `eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9` (biểu diễn `{"url":"https://docs.blockvectra.com/mcp"}`):

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

Khi cần công cụ có xác thực (Data API hoặc quản lý tài khoản), thêm đối tượng `headers` với API key:

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

Tài liệu chính thức: [Tài liệu MCP Cursor](https://cursor.com/docs/context/mcp) và [Liên kết cài đặt Cursor](https://cursor.com/docs/context/mcp/install-links).

#### VS Code

Trong VS Code, cấu hình máy chủ trong `.vscode/mcp.json` dưới khóa cấp cao nhất `servers` với `type: "http"`:

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

Khi cần công cụ có xác thực, thêm đối tượng `headers`:

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

Khi lưu thông tin xác thực nhạy cảm, VS Code hỗ trợ tham chiếu biến đầu vào hoặc tệp môi trường thay vì viết cứng key. Bạn cũng có thể thêm máy chủ bằng thao tác Command Palette `MCP: Add Server`.

Tài liệu chính thức: [Tài liệu máy chủ MCP VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) và [Tham chiếu cấu hình MCP VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

#### Codex

Thêm máy chủ bằng OpenAI Codex CLI:

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

Trong `config.toml`, cấu hình URL máy chủ:

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

Khi cần công cụ có xác thực, cấu hình header yêu cầu trong `config.toml`:

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

Hoặc ánh xạ header từ biến môi trường:

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

Tài liệu chính thức: [Tài liệu MCP OpenAI Codex CLI](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

#### Gemini CLI

Trong cấu hình Gemini CLI, thêm máy chủ dưới `mcpServers` bằng `httpUrl` cho Streamable HTTP:

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

Khi cần công cụ có xác thực, thêm đối tượng `headers` với API key:

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

Tài liệu chính thức: [Tài liệu máy chủ MCP Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md).

#### OpenAI Responses API

Khi gọi OpenAI Responses API, truyền máy chủ MCP trong mảng `tools` với `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": "..."
  }'
```

Khi cần công cụ có xác thực, thêm trường `headers` vào định nghĩa công cụ:

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

Tài liệu chính thức: [Hướng dẫn công cụ MCP OpenAI](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) và [Tham chiếu OpenAI Responses API](https://developers.openai.com/api/reference/resources/responses/methods/create).

#### Windsurf

Trong Windsurf, cấu hình máy chủ dưới `mcpServers` bằng trường `serverUrl`:

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

Khi cần công cụ có xác thực, thêm đối tượng `headers` với API key:

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

Windsurf cũng hỗ trợ tham chiếu biến môi trường, chẳng hạn `"x-api-key": "${env:BLOCKVECTRA_API_KEY}"`.

Tài liệu chính thức: [Tài liệu MCP Windsurf](https://docs.devin.ai/desktop/cascade/mcp).

#### Claude Desktop và claude.ai

Trình kết nối tùy chỉnh được cấu hình qua giao diện người dùng:

* **claude.ai**: Vào **Tùy chỉnh** > **Trình kết nối**, nhấp **+ Thêm**, chọn **Thêm trình kết nối tùy chỉnh** và nhập URL:
  ```text
  https://docs.blockvectra.com/mcp
  ```
* **Claude Desktop**: Mở menu cài đặt tài khoản và cấu hình trình kết nối tùy chỉnh qua giao diện trình kết nối.

Kết nối tới URL cho phép Claude tìm hướng dẫn, đọc tài liệu Markdown, xem chuỗi được hỗ trợ, kiểm tra trạng thái mạng và tính ước tính giá mà không cần thông tin xác thực.

Tài liệu chính thức: [Hướng dẫn trình kết nối tùy chỉnh Claude](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).

## 2. Endpoint JSON công khai (không cần key)

Agent có thể xem chuỗi khả dụng, trạng thái hiện tại và tham số gói trước khi gửi yêu cầu có đo lường sử dụng. Không endpoint nào trong số này cần API key:

* `GET /v1/status` và `GET /v1/chains` không cần xác thực và không tính phí.
* `GET /v1/plans` công khai và không cần xác thực.

Cả ba đều gửi `Access-Control-Allow-Origin: *`.

### Trạng thái dịch vụ (`GET /v1/status`)

Trả mức sẵn sàng của dịch vụ và trạng thái đồng bộ của từng chuỗi công khai:

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

Các trường phản hồi:

* `checked_at`: thời điểm tạo snapshot (RFC 3339 / ISO 8601 UTC).
* `gateway.status`: trạng thái chạy dịch vụ. `ok` nghĩa là dịch vụ sẵn sàng; `degraded` nghĩa là yêu cầu trả phí bị từ chối cho đến khi khôi phục. Giá trị này độc lập với trạng thái nút của từng chuỗi.
* `chains[]`: các chuỗi được phục vụ công khai:
  * `chain`: slug chuỗi (ví dụ `robinhood_mainnet`).
  * `name`: tên hiển thị dễ đọc.
  * `chain_id`: Chain ID EIP-155 (số nguyên thập phân).
  * `jsonrpc`: có phục vụ JSON-RPC hay không.
  * `data`: có phục vụ Data API hay không.
  * `data_features`: khả năng Data API có trên chuỗi này (mảng rỗng khi `data` là `false`).
  * `data_status`: trạng thái chạy Data API (`ok`, `syncing` hoặc `unavailable`; chỉ có khi `data` là `true`).
  * `status`: trạng thái nút chuỗi (`ok` hoặc `unavailable`).
  * `head`: thông tin khối mới nhất — `block` (độ cao khối mới nhất), `time` (dấu thời gian khối) và `lag_seconds` (thời gian khối chậm hơn thời gian hiện tại bao nhiêu) — hoặc `null` khi chưa biết.

Ví dụ phản hồi:

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

### Tham số chuỗi (`GET /v1/chains`)

Trả tham số tĩnh và chính sách phương thức của từng chuỗi công khai:

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

Các trường phản hồi:

* `chains[]`: các chuỗi công khai và tham số tĩnh:
  * `chain`: slug chuỗi.
  * `name`: tên hiển thị dễ đọc.
  * `chain_id`: Chain ID EIP-155.
  * `jsonrpc`: có phục vụ JSON-RPC hay không.
  * `data`: có phục vụ Data API hay không.
  * `ws`: có hỗ trợ kết nối WebSocket hay không.
  * `subscriptions`: loại đăng ký WebSocket được hỗ trợ (ví dụ `newHeads`, `logs`).
  * `methods`: chính sách phương thức:
    * `allow`: tên phương thức được phép (ví dụ `eth_call`, `debug_traceTransaction`).
    * `deny`: phương thức hoặc mẫu wildcard tiền tố bị từ chối (ví dụ `eth_newFilter`). Phương thức bị từ chối được ưu tiên hơn phương thức được phép.
  * `max_logs_block_range`: độ rộng khối tối đa được phép trong một yêu cầu `eth_getLogs`.
  * `state_window_blocks`: cửa sổ trạng thái lịch sử tính theo khối; `null` khi có toàn bộ lịch sử.
  * `info`: dữ liệu mở rộng công khai theo chuỗi (dành riêng; hiện là đối tượng rỗng `{}`).
  * `public`: cấu hình endpoint công khai không cần xác thực (hoặc `null`):
    * `url`: URL cơ sở cho yêu cầu công khai.
    * `methods`: phương thức được phép trên endpoint công khai.
    * `rate_limit`: giới hạn tốc độ (`per_ip_rps`, `burst`, `batch_max`).
    * `history_blocks`: lịch sử khối có thể truy cập trên endpoint công khai.
    * `send_raw_rate_limit`: giới hạn tốc độ phát giao dịch qua `eth_sendRawTransaction`.

Ví dụ phản hồi:

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

### Gói và trọng số phương thức (`GET /v1/plans`)

Tham số gói được phục vụ tại `GET https://console-api.blockvectra.com/v1/plans`. Agent có thể truy vấn endpoint này lúc chạy để đọc giới hạn gói miễn phí đang áp dụng và trọng số Compute Unit (CU) của từng phương thức:

* `free`: tham số gói miễn phí — `signup_units` (khoản cấp khi đăng ký, tính bằng unit), `monthly_units` (mốc bổ sung theo chu kỳ, tính bằng unit), `window_days` (độ dài chu kỳ sử dụng theo ngày) và `max_calls_per_sec` (giới hạn lệnh gọi mỗi giây của gói miễn phí).
* `pricing`: tham số gói trả phí — `units_per_usd` (unit trên 1 USD), `cu_per_unit` (CU trên mỗi unit) và `min_topup_usd` (mức nạp tối thiểu bằng USD).
* `method_weights`: trọng số CU mỗi lần gọi, mỗi mục là `{ "method": string, "cu_weight": number }`. `method` chỉ định tên hoặc mẫu phương thức JSON-RPC, trọng số mặc định cho phương thức không được liệt kê hoặc thao tác Data API như `data.<op>`. Trọng số tính theo phương thức và không tách theo chuỗi.

## 3. Xác thực và bảo mật key

Agent gửi lệnh gọi RPC phải tuân theo các quy tắc này:

* **Xác thực**: truyền API key theo một trong ba cách. Trong đường dẫn: `POST /v1/{chain}/{api_key}` — dạng đường dẫn chỉ dùng key trong đường dẫn và bỏ qua cả hai header. Trong header `x-api-key`: `POST /v1/{chain}` với `x-api-key: $BLOCKVECTRA_API_KEY`. Trong header `Authorization`: `POST /v1/{chain}` với `Authorization: Bearer $BLOCKVECTRA_API_KEY`. Khi có cả hai header, `x-api-key` không rỗng được ưu tiên; Bearer chỉ dùng khi `x-api-key` thiếu hoặc rỗng. Cùng key hoạt động trên mọi chuỗi được hỗ trợ và trên Data API (chỉ chấp nhận key trong header `x-api-key`).
* **Bảo mật key**: giữ API key trong biến môi trường phía máy chủ (ví dụ `BLOCKVECTRA_API_KEY`) hoặc trình quản lý secret. Tuyệt đối không nhúng key vào mã trình duyệt hoặc bất kỳ bundle phía client nào. Endpoint có trả `Access-Control-Allow-Origin: *`, nhưng dành cho dịch vụ backend gọi thay vì trình duyệt.
* **Đo lường và nâng cấp**: mức sử dụng được đo bằng Compute Unit (CU): mỗi phương thức tiêu thụ CU theo trọng số, còn số dư, bucket CU và giới hạn tốc độ gói miễn phí được dùng chung giữa mọi chuỗi. Sau khi nạp tiền trả phí, giới hạn lệnh gọi mỗi giây của gói miễn phí không còn áp dụng; mỗi key vẫn có giới hạn tốc độ CU và dung lượng burst. Free Credits chưa dùng vẫn nằm trong Credits và còn dùng được. Xem [Trang giá](https://blockvectra.com/vi/pricing/) để biết chi tiết.

> **No API key yet?**
>
> Nếu có ví Ethereum: làm theo [Hướng dẫn đăng ký bằng chương trình](https://docs.blockvectra.com/en/guides/programmatic-signup/) để đăng ký và tạo API key bằng chữ ký ví Ethereum mà không cần trình duyệt. Danh tính của Agent là ví của nó: nếu mất session token hoặc key, [xác thực lại bằng cùng ví để khôi phục](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key). Nếu không có ví: yêu cầu người dùng đăng nhập tại [console.blockvectra.com](https://console.blockvectra.com/login/?next=%2Fkeys%2F), tạo key và đặt làm biến môi trường `BLOCKVECTRA_API_KEY`. Không yêu cầu người dùng dán key vào chat.


### Truy vấn số dư (`GET /v1/account`)

Agent có thể trực tiếp kiểm tra số dư hiện tại của key, giới hạn CU và tham số key mà không tiêu thụ Compute Unit (CU). Để biết định dạng yêu cầu, giới hạn tốc độ và định nghĩa đầy đủ trường phản hồi, xem [Truy vấn số dư: GET /v1/account](https://docs.blockvectra.com/en/guides/billing-rules/#query-balance-get-v1account).

## 4. Quy trình chọn chuỗi cho Agent

Trước khi gửi lệnh gọi, Agent có thể làm theo các bước:

1. **Kiểm tra chuỗi và chính sách phương thức**: gọi `GET /v1/chains`, xác nhận chuỗi mục tiêu có tồn tại và có `jsonrpc: true`, đồng thời phương thức định gọi được `methods.allow` cho phép và không bị `methods.deny` từ chối (từ chối được ưu tiên).
2. **Kiểm tra trạng thái hiện tại**: gọi `GET /v1/status` và xác nhận `gateway.status` là `ok` và `status` của chuỗi mục tiêu là `ok`; dùng `head.lag_seconds` để quyết định dữ liệu chuỗi có đủ mới cho trường hợp sử dụng hay không. Khi nút chuỗi chưa đồng bộ, mọi phương thức trừ `eth_chainId` trả lỗi JSON-RPC `-32010` (HTTP 200, không tính phí), nên Agent có thể đợi và thử lại hoặc chọn chuỗi khác.
3. **Gửi yêu cầu**: `POST /v1/{chain}` với header `x-api-key` và body JSON-RPC tiêu chuẩn.

## 5. Ví dụ chạy tối thiểu

Ví dụ bên dưới đọc `/v1/chains` để chọn chuỗi cho phép `eth_blockNumber`, kiểm tra `/v1/status`, rồi gọi `eth_blockNumber` một lần.

**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)
```


Lệnh gọi thành công trả đối tượng phản hồi JSON-RPC tiêu chuẩn:

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

Để xem phí CU theo từng yêu cầu và số dư unit còn lại trong header phản hồi, thêm `x-bv-meter: 1`. Để biết hành vi header và trường hợp lỗi, xem [Header phản hồi phí và số dư](https://docs.blockvectra.com/en/guides/billing-rules/#http-status-codes-and-billing-rules).

## Các bước tiếp theo

* [Duyệt danh mục bộ dữ liệu](https://blockvectra.com/vi/data/) để xem mọi bộ dữ liệu BlockVectra lập chỉ mục.
* [Xem gói miễn phí và giá](https://blockvectra.com/vi/pricing/#free) để kiểm tra những gì tài khoản bao gồm.
* [Làm theo hướng dẫn đăng ký bằng chương trình](https://docs.blockvectra.com/en/guides/programmatic-signup/) để đăng ký và tạo API key bằng chữ ký ví, hoặc [đăng nhập bảng điều khiển](https://console.blockvectra.com/login/?next=%2Fkeys%2F) để tạo key.