# Blockchain RPC dan MCP dokumentasi untuk AI Agent

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

Mulai dengan [endpoint MCP dokumentasi](https://docs.blockvectra.com/mcp) tanpa API key untuk menemukan metode blockchain RPC, dataset Data API, harga, dan dokumentasi. AI Agent adalah pengguna kelas satu: pengembang dan AI Agent menggunakan API, aturan, batas, dan harga yang sama.

1. **Temukan**: gunakan MCP dokumentasi, `llms.txt`, OpenAPI, dan JSON publik untuk memilih chain dan metode. Panggilan RPC tanpa API key terbatas pada `public.methods` chain tersebut.
2. **Buka akun melalui HTTP**: ikuti [pendaftaran terprogram](https://docs.blockvectra.com/en/guides/programmatic-signup/) untuk masuk dengan tanda tangan dompet dan membuat API key. `how_to_get_api_key` MCP mengembalikan petunjuk untuk alur HTTP terpisah ini.
3. **Panggil API data**: simpan API key dalam `BLOCKVECTRA_API_KEY` dan gunakan untuk permintaan RPC atau Data API terautentikasi. Untuk alat MCP yang memerlukan API key, konfigurasikan header `x-api-key` klien; operasi yang diizinkan setiap alat tercantum di bawah.

## 1. Konteks dan spesifikasi yang dapat dibaca mesin

BlockVectra menerbitkan file untuk Agent LLM dan alat pengembang:

### Indeks llms.txt

Mengikuti konvensi [llmstxt.org](https://llmstxt.org), file ini memberi Agent ringkasan terstruktur tentang situs dan endpoint-nya:

* **Indeks situs utama**: [llms.txt situs utama](https://blockvectra.com/llms.txt) — ikhtisar situs utama, chain yang didukung, harga, dan API publik.
* **Indeks dokumentasi**: [llms.txt dokumentasi](https://docs.blockvectra.com/llms.txt) — katalog setiap halaman dokumentasi dengan judul dan deskripsinya.

### File dokumentasi lengkap (`llms-full.txt`)

* **Dokumentasi lengkap**: [llms-full.txt](https://docs.blockvectra.com/llms-full.txt) — teks lengkap setiap halaman dokumentasi berbahasa Inggris dalam satu file Markdown teks biasa, cocok dimuat ke system prompt Agent atau dimasukkan ke pipeline Retrieval-Augmented Generation (RAG).

### Spesifikasi OpenAPI 3.1 yang dapat diunduh

Situs dokumentasi menyediakan file YAML OpenAPI 3.1 yang dapat langsung diimpor ke framework Agent, generator alat, atau klien API:

* **Spesifikasi JSON-RPC API**: [/openapi/json-rpc.yaml](https://docs.blockvectra.com/openapi/json-rpc.yaml) — metode yang didukung, kebijakan metode per chain, respons error, dan pengukuran Compute Unit.
* **Spesifikasi Data API**: [/openapi/data.yaml](https://docs.blockvectra.com/openapi/data.yaml) — definisi endpoint REST untuk blok, transaksi, transfer, saldo, pemegang, dan dataset terkait yang terindeks.
* **Spesifikasi Push API**: [/openapi/push.yaml](https://docs.blockvectra.com/openapi/push.yaml) — pengelolaan langganan HTTP, alamat dompet yang dipantau, peristiwa Webhook, tanda tangan, dan replay.

Untuk aktivitas alamat dompet, ikuti [panduan Blockchain Webhook API](https://docs.blockvectra.com/en/guides/webhook-push/). Untuk notifikasi pembayaran ERC-20 USDT / USDC, gunakan [contoh penerima pembayaran](https://docs.blockvectra.com/en/guides/stablecoin-payments/#receive-payments-with-webhooks). Pengembang dan AI Agent membuat serta mengelola langganan melalui HTTP Push API dengan `x-api-key`; MCP dokumentasi menyediakan penemuan dan pembacaan panduan ini.

Untuk versi path, aturan kompatibilitas mundur, dan rekomendasi bagi pembuat Agent dan SDK, lihat [Versi dan kompatibilitas API](https://docs.blockvectra.com/en/api/versioning/). Untuk resep siap pakai di berbagai framework populer (ElizaOS, viem, wagmi, Coinbase AgentKit), lihat [Resep framework Agent](https://docs.blockvectra.com/en/guides/agent-frameworks/).

### Server Model Context Protocol (MCP)

BlockVectra menyediakan server MCP tanpa state dan tanpa API key melalui Streamable HTTP:

* **Endpoint**: [Endpoint MCP](https://docs.blockvectra.com/mcp) (HTTP POST menerima JSON-RPC 2.0; GET mengembalikan 405)
* **Transport**: MCP Streamable HTTP (tanpa state, tidak memerlukan API key)

#### Alat yang tersedia

1. `read_doc(path, lang?)`: mengembalikan konten Markdown mentah untuk halaman dokumentasi mana pun dari `/md/{lang}/{path}.md`. Menerima path relatif internal (misalnya `quickstart`, `guides/ai-agents`, `api/json-rpc`, `chains`).
2. `search_docs(query, lang?, limit?)`: mencari halaman dokumentasi berdasarkan judul, path, dan ringkasan.
3. `list_chains()`: membaca jaringan blockchain yang didukung, parameter statis, dan kebijakan metode dari `GET /v1/chains`.
4. `get_status()`: membaca kesiapan layanan langsung, status jaringan, tinggi blok terbaru, dan keterlambatan sinkronisasi dari `GET /v1/status`.
5. `get_pricing()`: membaca bobot Compute Unit (CU), parameter Paket Gratis, dan batas API key bawaan dari `GET /v1/plans`.
6. `estimate_usage(lines?, method?, calls_per_day?)`: memperkirakan Compute Units (CU), biaya daftar kotor, dan biaya bersih setelah mengurangi kuota gratis siklus untuk satu atau beberapa metode (mendukung `lines: [{method, calls_per_day}]` beberapa baris atau satu `method` dan `calls_per_day`). Juga melaporkan batas laju per API key dari `key_defaults` dan menyarankan jumlah API key yang diperlukan ketika trafik melebihi batas satu API key.
7. `how_to_get_api_key(lang?)`: mengembalikan langkah penyerahan API key dan bentuk autentikasi permintaan untuk JSON-RPC dan Data API.
8. `get_method_info(method, chain?)`: mengembalikan ketersediaan chain, bobot Compute Unit (CU), harga per satu juta panggilan, dan tautan dokumentasi untuk suatu metode. Ketersediaan JSON-RPC mengikuti `methods.allow` dan `deny` dalam `GET /v1/chains`; cakupan dataset Data API mengikuti `data_features` dalam `GET /v1/status`, dengan `data: true` dalam katalog chain.
9. `explain_error(reason?, code?, http_status?)`: mencari penjelasan error, dampak penagihan, kemungkinan percobaan ulang, dan tindakan pemulihan dari katalog error.
10. `list_docs(lang?)`: mencantumkan semua halaman dokumentasi dengan path relatif dan judul dari indeks dokumentasi.
11. `rpc_call(chain, method, params?)`: menjalankan panggilan JSON-RPC 2.0 hanya-baca pada chain yang didukung dengan API key Anda (`readOnlyHint: true`). Metode tulis (seperti `eth_sendRawTransaction`) ditolak; gunakan `send_raw_transaction` sebagai gantinya. Memerlukan header `x-api-key` dalam konfigurasi klien MCP untuk akses penuh, atau menggunakan endpoint publik tanpa API key jika tersedia.
12. `data_api_get(chain, path, query?)`: mengirim permintaan GET ke Data API untuk chain dan path yang didukung dengan API key Anda (`readOnlyHint: true`). Memerlukan header `x-api-key` dalam konfigurasi klien MCP.
13. `get_account()`: mengueri saldo akun, Compute Units (CU), batas laju, dan parameter API key dari `GET /v1/account` dengan API key Anda (`readOnlyHint: true`). Memerlukan header `x-api-key` dalam konfigurasi klien MCP.
14. `get_deposit_address()`: mengueri alamat deposit on-chain khusus, jaringan yang dibuka, dan token dari `GET /v1/topup/deposit-address` dengan API key Anda (`readOnlyHint: true`). Transfer hanya ke jaringan dan token yang tercantum. Memerlukan header `x-api-key` dalam konfigurasi klien MCP.
15. `send_raw_transaction(chain, raw_tx)`: menyiarkan transaksi mentah yang ditandatangani ke chain yang didukung melalui `eth_sendRawTransaction` (`destructiveHint: true`). Memerlukan header `x-api-key` dalam konfigurasi klien MCP untuk akses penuh, atau menggunakan endpoint publik tanpa API key jika diizinkan pada chain tersebut.

#### Alat yang memerlukan API key

Alat yang memerlukan API key menggunakan API key untuk menjalankan kueri on-chain, transaksi, permintaan Data API, atau operasi akun.

**Keamanan API key**:

* **Baca hanya dari header**: API key dibaca hanya dari header permintaan HTTP klien MCP (`x-api-key: rgw_...` atau `Authorization: Bearer rgw_...`).
* **Jangan pernah memasukkan API key ke obrolan**: Jangan pernah mengirim API key atau private key dalam argumen alat atau menempelkannya ke obrolan. Argumen alat dan riwayat obrolan masuk ke log serta konteks percakapan; pengiriman API key dalam argumen akan ditolak.

Jika dipanggil tanpa header API key, alat ini mengembalikan `isError: true` dan mengarahkan Agent ke `how_to_get_api_key` serta panduan pendaftaran terprogram.

### Menghubungkan dari klien MCP

Anda dapat terhubung ke server MCP dokumentasi BlockVectra di `https://docs.blockvectra.com/mcp` melalui berbagai lingkungan pengembangan dan framework umum.

Mulai tanpa API key. Hubungkan ke endpoint MCP, panggil list\_chains, lalu baca quickstart dengan read\_doc. Tambahkan API key dalam header HTTP klien ketika memerlukan alat Data API atau akun. Akses RPC tanpa API key mengikuti kebijakan metode publik setiap chain.

Header `x-api-key` opsional. Tanpa API key, klien dapat menggunakan semua alat dokumentasi hanya-baca (`read_doc`, `search_docs`, `list_docs`), penemuan chain (`list_chains`), status langsung (`get_status`), estimasi harga (`get_pricing`, `estimate_usage`), penjelasan error (`explain_error`), serta metode yang diizinkan pada endpoint publik. Saat menggunakan alat yang memerlukan API key (`rpc_call` pada metode terbatas, `send_raw_transaction`, `data_api_get`, `get_account`, dan `get_deposit_address`), konfigurasikan header `x-api-key` dengan API key Anda.

#### Claude Code

Hubungkan ke server MCP menggunakan CLI:

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

Untuk menyertakan API key opsional bagi alat terautentikasi, gunakan opsi `--header` (atau `-H`):

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

Dokumentasi resmi: [Dokumentasi MCP Claude Code](https://code.claude.com/docs/en/mcp).

#### Cursor

Tambahkan server ke konfigurasi MCP Cursor:

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

Cursor juga mendukung instalasi sekali klik melalui deep link menggunakan konfigurasi berpengodean base64 `eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9` (mewakili `{"url":"https://docs.blockvectra.com/mcp"}`):

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

Ketika memerlukan alat terautentikasi (Data API atau pengelolaan akun), tambahkan objek `headers` dengan API key Anda:

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

Dokumentasi resmi: [Dokumentasi MCP Cursor](https://cursor.com/docs/context/mcp) dan [tautan instalasi Cursor](https://cursor.com/docs/context/mcp/install-links).

#### VS Code

Di VS Code, konfigurasikan server dalam `.vscode/mcp.json` di bawah kunci tingkat atas `servers` dengan `type: "http"`:

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

Ketika memerlukan alat terautentikasi, tambahkan objek `headers`:

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

Saat menyimpan kredensial sensitif, VS Code mendukung referensi variabel input atau file lingkungan alih-alih menulis API key secara tetap. Anda juga dapat menambahkan server menggunakan tindakan Command Palette `MCP: Add Server`.

Dokumentasi resmi: [Dokumentasi server MCP VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) dan [referensi konfigurasi MCP VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

#### Codex

Tambahkan server menggunakan OpenAI Codex CLI:

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

Dalam `config.toml`, konfigurasikan URL server:

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

Ketika memerlukan alat terautentikasi, konfigurasikan header permintaan dalam `config.toml`:

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

Atau, petakan header dari variabel lingkungan:

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

Dokumentasi resmi: [Dokumentasi MCP OpenAI Codex CLI](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

#### Gemini CLI

Dalam konfigurasi Gemini CLI, tambahkan server di bawah `mcpServers` menggunakan `httpUrl` untuk Streamable HTTP:

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

Ketika memerlukan alat terautentikasi, tambahkan objek `headers` dengan API key Anda:

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

Dokumentasi resmi: [Dokumentasi server MCP Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md).

#### OpenAI Responses API

Saat memanggil OpenAI Responses API, sertakan server MCP dalam array `tools` dengan `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": "..."
  }'
```

Ketika memerlukan alat terautentikasi, sertakan bidang `headers` dalam definisi alat:

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

Dokumentasi resmi: [Panduan alat MCP OpenAI](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) dan [referensi OpenAI Responses API](https://developers.openai.com/api/reference/resources/responses/methods/create).

#### Windsurf

Di Windsurf, konfigurasikan server di bawah `mcpServers` menggunakan bidang `serverUrl`:

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

Ketika memerlukan alat terautentikasi, tambahkan objek `headers` dengan API key Anda:

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

Windsurf juga mendukung referensi variabel lingkungan, seperti `"x-api-key": "${env:BLOCKVECTRA_API_KEY}"`.

Dokumentasi resmi: [Dokumentasi MCP Windsurf](https://docs.devin.ai/desktop/cascade/mcp).

#### Claude Desktop dan claude.ai

Konektor kustom dikonfigurasikan melalui antarmuka pengguna:

* **claude.ai**: Buka **Customize** > **Connectors**, klik **+ Add**, pilih **Add custom connector**, lalu masukkan URL:
  ```text
  https://docs.blockvectra.com/mcp
  ```
* **Claude Desktop**: Buka menu pengaturan akun dan konfigurasikan konektor kustom melalui antarmuka konektor.

Menghubungkan ke URL memungkinkan Claude mencari panduan, membaca dokumentasi Markdown, memeriksa chain yang didukung, memeriksa status jaringan, dan menghitung estimasi harga tanpa kredensial.

Dokumentasi resmi: [Panduan konektor kustom Claude](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).

## 2. Endpoint JSON publik (tanpa API key)

Agent dapat memeriksa chain yang tersedia, status langsung, dan parameter paket sebelum mengirim permintaan terukur apa pun. Tidak satu pun endpoint ini memerlukan API key:

* `GET /v1/status` dan `GET /v1/chains` tidak memerlukan autentikasi dan tidak ditagih.
* `GET /v1/plans` bersifat publik dan tidak memerlukan autentikasi.

Ketiganya mengirim `Access-Control-Allow-Origin: *`.

### Status layanan (`GET /v1/status`)

Mengembalikan kesiapan layanan dan status sinkronisasi setiap chain publik:

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

Bidang respons:

* `checked_at`: waktu snapshot dibuat (RFC 3339 / ISO 8601 UTC).
* `gateway.status`: status layanan yang berjalan. `ok` berarti layanan siap; `degraded` berarti permintaan berbayar ditolak hingga layanan pulih. Nilai ini independen dari status node chain mana pun.
* `chains[]`: chain yang dilayani untuk publik:
  * `chain`: slug chain (misalnya `robinhood_mainnet`).
  * `name`: nama tampilan yang mudah dibaca manusia.
  * `chain_id`: Chain ID EIP-155 (bilangan bulat desimal).
  * `jsonrpc`: apakah JSON-RPC dilayani.
  * `data`: apakah Data API dilayani.
  * `data_features`: kemampuan Data API yang tersedia untuk chain ini (array kosong ketika `data` bernilai `false`).
  * `data_status`: status Data API yang berjalan (`ok`, `syncing`, atau `unavailable`; hanya ada ketika `data` bernilai `true`).
  * `status`: status node chain (`ok` atau `unavailable`).
  * `head`: informasi blok terbaru — `block` (tinggi blok terbaru), `time` (timestamp blok), dan `lag_seconds` (seberapa jauh waktu blok tertinggal dari waktu saat ini) — atau `null` jika belum diketahui.

Contoh respons:

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

### Parameter chain (`GET /v1/chains`)

Mengembalikan parameter statis dan kebijakan metode setiap chain publik:

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

Bidang respons:

* `chains[]`: chain publik dan parameter statisnya:
  * `chain`: slug chain.
  * `name`: nama tampilan yang mudah dibaca manusia.
  * `chain_id`: Chain ID EIP-155.
  * `jsonrpc`: apakah JSON-RPC dilayani.
  * `data`: apakah Data API dilayani.
  * `ws`: apakah koneksi WebSocket didukung.
  * `subscriptions`: jenis langganan WebSocket yang didukung (misalnya `newHeads`, `logs`).
  * `methods`: kebijakan metode:
    * `allow`: nama metode yang diizinkan (misalnya `eth_call`, `debug_traceTransaction`).
    * `deny`: metode yang ditolak atau pola wildcard awalan (misalnya `eth_newFilter`). Metode yang ditolak memiliki prioritas di atas yang diizinkan.
  * `max_logs_block_range`: rentang blok maksimum yang diizinkan dalam satu permintaan `eth_getLogs`.
  * `state_window_blocks`: jendela state historis dalam blok; `null` ketika riwayat lengkap tersedia.
  * `info`: data ekstensi publik per chain (dicadangkan; saat ini objek kosong `{}`).
  * `public`: konfigurasi endpoint publik tanpa autentikasi (atau `null`):
    * `url`: URL dasar untuk permintaan publik.
    * `methods`: metode yang diizinkan pada endpoint publik.
    * `rate_limit`: batas laju (`per_ip_rps`, `burst`, `batch_max`).
    * `history_blocks`: riwayat blok yang dapat diakses pada endpoint publik.
    * `send_raw_rate_limit`: batas laju untuk penyiaran transaksi melalui `eth_sendRawTransaction`.

Contoh respons:

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

### Paket dan bobot metode (`GET /v1/plans`)

Parameter paket disediakan di `GET https://console-api.blockvectra.com/v1/plans`. Agent dapat mengueri endpoint ini saat runtime untuk membaca batas paket gratis aktif dan bobot Compute Unit (CU) setiap metode:

* `free`: parameter Paket Gratis — `signup_units` (pemberian saat pendaftaran, dalam unit), `monthly_units` (ambang pengisian ulang siklus, dalam unit), `window_days` (panjang siklus penggunaan dalam hari), dan `max_calls_per_sec` (batas panggilan per detik paket gratis).
* `pricing`: parameter paket berbayar — `units_per_usd` (unit per 1 USD), `cu_per_unit` (CU per unit), dan `min_topup_usd` (minimum isi saldo dalam USD).
* `method_weights`: bobot CU per panggilan, masing-masing `{ "method": string, "cu_weight": number }`. `method` menentukan nama atau pola metode JSON-RPC, bobot bawaan untuk metode yang tidak tercantum, atau operasi Data API seperti `data.<op>`. Bobot ditentukan per metode dan tidak dipisahkan menurut chain.

## 3. Autentikasi dan keamanan API key

Agent yang mengirim panggilan RPC harus mengikuti aturan berikut:

* **Autentikasi**: kirim API key dengan salah satu dari tiga cara. Dalam path: `POST /v1/{chain}/{api_key}` — bentuk path hanya menggunakan API key di path dan mengabaikan kedua header. Dalam header `x-api-key`: `POST /v1/{chain}` dengan `x-api-key: $BLOCKVECTRA_API_KEY`. Dalam header `Authorization`: `POST /v1/{chain}` dengan `Authorization: Bearer $BLOCKVECTRA_API_KEY`. Ketika kedua header ada, `x-api-key` yang tidak kosong diutamakan; Bearer hanya digunakan ketika `x-api-key` tidak ada atau kosong. API key yang sama berfungsi pada setiap chain yang didukung, dan pada Data API (yang hanya menerima API key dalam header `x-api-key`).
* **Keamanan API key**: simpan API key dalam variabel lingkungan sisi server (misalnya `BLOCKVECTRA_API_KEY`) atau pengelola secret. Jangan pernah menyematkan API key dalam kode browser atau bundle sisi klien mana pun. Endpoint memang mengembalikan `Access-Control-Allow-Origin: *`, tetapi ditujukan untuk dipanggil oleh layanan backend, bukan dari browser.
* **Pengukuran dan peningkatan**: penggunaan diukur dalam Compute Units (CU): setiap metode mengonsumsi CU sesuai bobotnya, dan saldo, bucket CU, serta batas laju paket gratis dibagikan di seluruh chain. Setelah isi saldo berbayar, batas panggilan per detik paket gratis tidak lagi berlaku; setiap API key tetap memiliki batas laju CU dan kapasitas burst. Kredit Gratis yang belum digunakan tetap ada dalam Credits dan masih dapat digunakan. Lihat [halaman Harga](https://blockvectra.com/en/pricing/) untuk rinciannya.

> **No API key yet?**
>
> Jika Anda memiliki dompet Ethereum: ikuti [panduan Pendaftaran terprogram](https://docs.blockvectra.com/en/guides/programmatic-signup/) untuk mendaftar dan membuat API key menggunakan tanda tangan dompet Ethereum tanpa browser. Identitas Agent adalah dompetnya: jika token sesi atau API key hilang, [autentikasi ulang dengan dompet yang sama untuk memulihkannya](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key). Jika Anda tidak memiliki dompet: minta pengguna masuk di [console.blockvectra.com](https://console.blockvectra.com/login/?next=%2Fkeys%2F), membuat API key, dan mengaturnya sebagai variabel lingkungan `BLOCKVECTRA_API_KEY`. Jangan meminta pengguna menempelkan API key ke obrolan.


### Kueri saldo (`GET /v1/account`)

Agent dapat memeriksa saldo API key saat ini, batas CU, dan parameter API key secara langsung tanpa mengonsumsi Compute Units (CU). Untuk format permintaan, batas laju, dan definisi lengkap bidang respons, lihat [Kueri saldo: GET /v1/account](https://docs.blockvectra.com/en/guides/billing-rules/#query-balance-get-v1account).

## 4. Alur pemilihan chain untuk Agent

Sebelum mengirim panggilan, Agent dapat mengikuti langkah berikut:

1. **Periksa chain dan kebijakan metodenya**: panggil `GET /v1/chains`, pastikan chain tujuan ada dan memiliki `jsonrpc: true`, serta metode yang akan dipanggil diizinkan oleh `methods.allow` dan tidak ditolak oleh `methods.deny` (penolakan diutamakan).
2. **Periksa status langsung**: panggil `GET /v1/status` dan pastikan `gateway.status` bernilai `ok` serta `status` chain tujuan bernilai `ok`; gunakan `head.lag_seconds` untuk menentukan apakah data chain cukup baru bagi kasus penggunaan Anda. Ketika node chain belum tersinkronisasi, semua metode kecuali `eth_chainId` mengembalikan error JSON-RPC `-32010` (HTTP 200, tidak ditagih), sehingga Agent dapat menunggu dan mencoba ulang atau memilih chain lain.
3. **Kirim permintaan**: `POST /v1/{chain}` dengan header `x-api-key` dan body JSON-RPC standar.

## 5. Contoh kerja minimal

Contoh di bawah membaca `/v1/chains` untuk memilih chain yang mengizinkan `eth_blockNumber`, memeriksa `/v1/status`, lalu memanggil `eth_blockNumber` sekali.

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


Panggilan yang berhasil mengembalikan objek respons JSON-RPC standar:

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

Untuk memeriksa biaya CU per permintaan dan unit saldo tersisa dalam header respons, sertakan `x-bv-meter: 1`. Untuk perilaku header dan kasus error, lihat [Header respons biaya dan saldo](https://docs.blockvectra.com/en/guides/billing-rules/#http-status-codes-and-billing-rules).

## Langkah selanjutnya

* [Jelajahi direktori dataset](https://blockvectra.com/en/data/) untuk melihat setiap dataset yang diindeks BlockVectra.
* [Lihat paket gratis dan harga](https://blockvectra.com/en/pricing/#free) untuk memeriksa apa yang termasuk dalam akun Anda.
* [Ikuti panduan pendaftaran terprogram](https://docs.blockvectra.com/en/guides/programmatic-signup/) untuk mendaftar dan membuat API key dengan tanda tangan dompet, atau [masuk ke konsol](https://console.blockvectra.com/login/?next=%2Fkeys%2F) untuk membuat API key.