# Blockchain RPC และ docs MCP สำหรับ AI Agent

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

เริ่มต้นด้วย [docs MCP endpoint](https://docs.blockvectra.com/mcp) แบบไม่ต้องใช้คีย์เพื่อค้นหาเมธอด Blockchain RPC, ชุดข้อมูล Data API, ราคา และเอกสารประกอบ AI Agent ถือเป็นผู้ใช้งานชั้นหนึ่ง (first-class users): นักพัฒนาและ AI Agent ใช้ API, กฎ, ขีดจำกัด และราคาเดียวกัน

1. **ค้นหา (Discover)**: ใช้ docs MCP, `llms.txt`, OpenAPI และ JSON สาธารณะเพื่อเลือกเชนและเมธอด การเรียก RPC แบบไม่ใช้คีย์จะจำกัดเฉพาะ `public.methods` ของเชนนั้นๆ
2. **เปิดบัญชีผ่าน HTTP**: ทำตาม [การลงทะเบียนแบบเป็นโปรแกรม](https://docs.blockvectra.com/en/guides/programmatic-signup/) เพื่อเข้าสู่ระบบด้วยลายเซ็นกระเป๋าเงินและสร้าง API key โดย `how_to_get_api_key` ของ MCP จะส่งคืนคำแนะนำสำหรับโฟลว์ HTTP แยกต่างหากนี้
3. **เรียกใช้ Data API**: จัดเก็บคีย์ไว้ใน `BLOCKVECTRA_API_KEY` และใช้สำหรับคำขอ RPC หรือ Data API ที่ต้องยืนยันตัวตน สำหรับเครื่องมือ MCP ที่ต้องใช้คีย์ ให้กำหนดค่าส่วนหัว `x-api-key` ของไคลเอนต์ โดยการดำเนินการที่อนุญาตของแต่ละเครื่องมือมีรายละเอียดอยู่ด้านล่าง

## 1. บริบทและข้อกำหนดที่เครื่องอ่านได้

BlockVectra เผยแพร่ไฟล์สำหรับ LLM agent และเครื่องมือของนักพัฒนา:

### ดัชนี llms.txt

ตามรูปแบบมาตรฐานของ [llmstxt.org](https://llmstxt.org) ไฟล์เหล่านี้จะสรุปข้อมูลของเว็บไซต์และ endpoint ต่างๆ อย่างมีโครงสร้างสำหรับ agent:

* **ดัชนีเว็บไซต์หลัก**: [Main site llms.txt](https://blockvectra.com/llms.txt) — ภาพรวมของเว็บไซต์หลัก, เชนที่รองรับ, ราคา และ API สาธารณะ
* **ดัชนีเอกสาร**: [Documentation llms.txt](https://docs.blockvectra.com/llms.txt) — แคตตาล็อกของหน้าเอกสารทั้งหมดพร้อมชื่อเรื่องและคำอธิบาย

### ไฟล์เอกสารฉบับเต็ม (`llms-full.txt`)

* **เอกสารฉบับสมบูรณ์**: [llms-full.txt](https://docs.blockvectra.com/llms-full.txt) — ข้อความฉบับเต็มของหน้าเอกสารภาษาอังกฤษทุกหน้าในไฟล์ Markdown ข้อความล้วนไฟล์เดียว เหมาะสำหรับการโหลดลงใน system prompt ของ agent หรือนำเข้าสู่ไปป์ไลน์ Retrieval-Augmented Generation (RAG)

### ข้อกำหนด OpenAPI 3.1 ที่ดาวน์โหลดได้

เว็บไซต์เอกสารให้บริการไฟล์ YAML ของ OpenAPI 3.1 ซึ่งสามารถนำเข้าสู่เฟรมเวิร์กของ agent, เครื่องมือสร้าง tool หรือไคลเอนต์ API ได้โดยตรง:

* **ข้อกำหนด JSON-RPC API**: [/openapi/json-rpc.yaml](https://docs.blockvectra.com/openapi/json-rpc.yaml) — เมธอดที่รองรับ, นโยบายเมธอดต่อเชน, การตอบกลับข้อผิดพลาด และการวัดปริมาณ Compute Unit
* **ข้อกำหนด Data API**: [/openapi/data.yaml](https://docs.blockvectra.com/openapi/data.yaml) — นิยาม REST endpoint สำหรับบล็อกที่จัดทำดัชนีแล้ว, ธุรกรรม, การโอน, ยอดคงเหลือ, ผู้ถือครอง และชุดข้อมูลที่เกี่ยวข้อง
* **ข้อกำหนด Push API**: [/openapi/push.yaml](https://docs.blockvectra.com/openapi/push.yaml) — การจัดการการสมัครรับข้อมูลผ่าน HTTP, ที่อยู่กระเป๋าเงินที่เฝ้าดู, อีเวนต์ webhook, ลายเซ็น และการเล่นซ้ำ

สำหรับกิจกรรมที่อยู่กระเป๋าเงิน โปรดทำตาม [คู่มือ 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 agent สามารถสร้างและจัดการการสมัครรับข้อมูลผ่าน HTTP Push API ด้วย `x-api-key`; โดย docs MCP จะช่วยค้นหาและอ่านคู่มือเหล่านี้

สำหรับการกำหนดเวอร์ชันของพาธ, กฎความเข้ากันได้ย้อนหลัง และคำแนะนำสำหรับ agent ตลอดจนผู้พัฒนา SDK โปรดดู [การกำหนดเวอร์ชันและความเข้ากันได้ของ API](https://docs.blockvectra.com/en/api/versioning/) สำหรับสูตรสำเร็จที่พร้อมใช้งานในเฟรมเวิร์กยอดนิยม (ElizaOS, viem, wagmi, Coinbase AgentKit) โปรดดู [สูตรการใช้งานสำหรับเฟรมเวิร์ก Agent](https://docs.blockvectra.com/en/guides/agent-frameworks/)

### เซิร์ฟเวอร์ Model Context Protocol (MCP)

BlockVectra ให้บริการเซิร์ฟเวอร์ MCP แบบ stateless และไม่ต้องใช้คีย์ผ่าน Streamable HTTP:

* **Endpoint**: [MCP endpoint](https://docs.blockvectra.com/mcp) (HTTP POST รับ JSON-RPC 2.0; GET จะส่งคืน 405)
* **Transport**: 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 Unit (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 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 สำหรับการเข้าถึงแบบเต็มรูปแบบ หรือใช้ endpoint สาธารณะแบบไม่ใช้คีย์หากมีให้บริการ
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 สำหรับการเข้าถึงแบบเต็มรูปแบบ หรือใช้ endpoint สาธารณะแบบไม่ใช้คีย์หากได้รับอนุญาตบนเชนนั้น

#### เครื่องมือที่ต้องใช้คีย์

เครื่องมือที่ต้องใช้คีย์จำเป็นต้องมี API key เพื่อดำเนินการสอบถามบนเชน, ทำธุรกรรม, ส่งคำขอ Data API หรือดำเนินการเกี่ยวกับบัญชี

**ความปลอดภัยของ API key**:

* **อ่านจากส่วนหัวอย่างเคร่งครัด**: API key จะถูกอ่านจากส่วนหัวคำขอ HTTP ของไคลเอนต์ MCP เท่านั้น (`x-api-key: rgw_...` หรือ `Authorization: Bearer rgw_...`)
* **ห้ามใส่คีย์ในแชทเด็ดขาด**: ห้ามส่ง API key หรือ private key ในอาร์กิวเมนต์ของเครื่องมือ หรือวางลงในแชท อาร์กิวเมนต์ของเครื่องมือและประวัติการแชทจะเข้าสู่บันทึกและบริบทของการสนทนา การส่งคีย์ในอาร์กิวเมนต์จะถูกปฏิเสธ

หากเรียกใช้โดยไม่มีส่วนหัว API key เครื่องมือเหล่านี้จะส่งคืน `isError: true` และนำทาง agent ไปยัง `how_to_get_api_key` รวมถึงคู่มือการเริ่มต้นใช้งานแบบเป็นโปรแกรม

### การเชื่อมต่อจากไคลเอนต์ MCP

คุณสามารถเชื่อมต่อกับเซิร์ฟเวอร์ MCP เอกสารของ BlockVectra ได้ที่ `https://docs.blockvectra.com/mcp` ในสภาพแวดล้อมการพัฒนาและเฟรมเวิร์กทั่วไป

เริ่มต้นโดยไม่ต้องใช้ API key เชื่อมต่อกับ MCP endpoint, เรียกใช้ 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`) และเมธอดที่อนุญาตบน endpoint สาธารณะ เมื่อใช้เครื่องมือที่ต้องมีคีย์ (`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 ยังรองรับการติดตั้งแบบคลิกเดียวผ่าน 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](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 รองรับการอ้างอิงตัวแปร input หรือไฟล์สภาพแวดล้อมแทนการฮาร์ดโค้ดคีย์ คุณยังสามารถเพิ่มเซิร์ฟเวอร์โดยใช้คำสั่งใน 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

เพิ่มเซิร์ฟเวอร์โดยใช้ 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](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](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` field:

```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**: เปิดเมนูการตั้งค่าบัญชีและกำหนดค่าตัวเชื่อมต่อแบบกำหนดเองผ่านอินเทอร์เฟซ connectors

การเชื่อมต่อกับ URL นี้จะช่วยให้ Claude สามารถค้นหาคู่มือ, อ่านเอกสาร Markdown, ตรวจสอบเชนที่รองรับ, ตรวจสอบสถานะเครือข่าย และคำนวณการประเมินราคาได้โดยไม่ต้องใช้ข้อมูลประจำตัว

เอกสารอย่างเป็นทางการ: [คู่มือตัวเชื่อมต่อแบบกำหนดเองของ Claude](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp)

## 2. Public JSON endpoint (ไม่ต้องใช้คีย์)

agent สามารถตรวจสอบเชนที่มีอยู่, สถานะแบบเรียลไทม์ และพารามิเตอร์ของแพ็กเกจก่อนส่งคำขอที่มีการวัดปริมาณได้ โดยไม่มี endpoint ใดในกลุ่มนี้ที่ต้องใช้ API key:

* `GET /v1/status` และ `GET /v1/chains` ไม่ต้องยืนยันตัวตนและไม่คิดค่าบริการ
* `GET /v1/plans` เป็นแบบสาธารณะและไม่ต้องยืนยันตัวตน

ทั้งสาม endpoint จะส่ง `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`: การกำหนดค่า endpoint สาธารณะที่ไม่ต้องยืนยันตัวตน (หรือ `null`):
    * `url`: base URL สำหรับคำขอสาธารณะ
    * `methods`: เมธอดที่ได้รับอนุญาตบน endpoint สาธารณะ
    * `rate_limit`: ขีดจำกัดอัตรา (`per_ip_rps`, `burst`, `batch_max`)
    * `history_blocks`: ประวัติบล็อกที่สามารถเข้าถึงได้บน endpoint สาธารณะ
    * `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` โดย agent สามารถสอบถาม endpoint นี้ขณะรันไทม์เพื่ออ่านขีดจำกัดของแพ็กเกจฟรีที่ใช้งานอยู่ และน้ำหนัก Compute Unit (CU) ของแต่ละเมธอด:

* `free`: พารามิเตอร์แพ็กเกจฟรี — `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. การยืนยันตัวตนและความปลอดภัยของคีย์

agent ที่ส่งการเรียก 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` หรือค่าว่างเท่านั้น ทั้งนี้ API key เดียวกันสามารถใช้ได้กับทุกเชนที่รองรับ และใช้ได้กับ Data API (ซึ่งรับคีย์เฉพาะในส่วนหัว `x-api-key` เท่านั้น)
* **ความปลอดภัยของคีย์**: จัดเก็บ API key ไว้ในตัวแปรสภาพแวดล้อมฝั่งเซิร์ฟเวอร์ (เช่น `BLOCKVECTRA_API_KEY`) หรือเครื่องมือจัดการความลับ (secrets manager) ห้ามฝังคีย์ลงในโค้ดเบราว์เซอร์หรือบันเดิลฝั่งไคลเอนต์ใดๆ แม้ว่า endpoint จะส่งคืน `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 โดยไม่ต้องใช้เบราว์เซอร์ ข้อมูลประจำตัวของ agent คือกระเป๋าเงินของตัวเอง: หาก session token หรือคีย์สูญหาย [ให้ยืนยันตัวตนใหม่ด้วยกระเป๋าเงินเดิมเพื่อกู้คืน](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`)

agent สามารถตรวจสอบยอดคงเหลือปัจจุบันของคีย์, ขีดจำกัด CU และพารามิเตอร์ของคีย์ได้โดยตรงโดยไม่ใช้ Compute Units (CU) สำหรับรูปแบบคำขอ, การจำกัดอัตรา และนิยามฟิลด์การตอบกลับทั้งหมด โปรดดู [ตรวจสอบยอดคงเหลือ: GET /v1/account](https://docs.blockvectra.com/en/guides/billing-rules/#query-balance-get-v1account)

## 4. เวิร์กโฟลว์การเลือกเชนสำหรับ Agent

ก่อนส่งการเรียกคำขอ agent สามารถทำตามขั้นตอนเหล่านี้:

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 ไม่คิดค่าบริการ) ดังนั้น agent สามารถรอแล้วลองใหม่หรือเลือกเชนอื่นได้
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) เพื่อสร้างคีย์