# Dùng RPC blockchain trong Agent LangChain với BlockVectra

> Source: https://docs.blockvectra.com/vi/guides/langchain/

Một Agent LangChain đọc dữ liệu blockchain trực tiếp qua một tool gửi POST JSON-RPC tới `https://api.blockvectra.com/v1/eth_mainnet/public`. Endpoint đó không cần API key hay đăng ký cho các phương thức trong `public.methods` của từng chuỗi. API key bổ sung phần còn lại, và Gói miễn phí cung cấp 30,000,000 CU cho mỗi cửa sổ 30 ngày. Kiểm tra ngày 2026-10-11.

```python
import httpx
from langchain.agents import create_agent
from langchain.tools import tool

RPC = "https://api.blockvectra.com/v1/eth_mainnet/public"

@tool
def eth_block_number() -> str:
    """Return the latest Ethereum mainnet block number as a hex string."""
    body = {"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []}
    return httpx.post(RPC, json=body, timeout=10).json()["result"]

agent = create_agent("claude-sonnet-5", tools=[eth_block_number])
result = agent.invoke({"messages": [{"role": "user", "content": "What is the latest block?"}]})
print(result["messages"][-1].content)
```

Cài đặt bằng `pip install langchain httpx`; chuỗi tên model và key của nhà cung cấp đi theo [hướng dẫn nhanh LangChain](https://docs.langchain.com/oss/python/langchain/quickstart). Tool dùng [decorator `@tool`](https://docs.langchain.com/oss/python/langchain/tools) của LangChain và [`create_agent`](https://reference.langchain.com/python/langchain/agents/factory/create_agent).

## Cùng tool đó trong TypeScript

```typescript
import * as z from "zod";
import { createAgent, tool } from "langchain";

const ethBlockNumber = tool(
  async () => {
    const res = await fetch("https://api.blockvectra.com/v1/eth_mainnet/public", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_blockNumber", params: [] }),
    });
    return (await res.json()).result as string;
  },
  { name: "eth_block_number", description: "Latest Ethereum mainnet block number (hex).", schema: z.object({}) },
);

const agent = createAgent({ model: "claude-sonnet-5", tools: [ethBlockNumber] });
```

Xem [hướng dẫn tools](https://docs.langchain.com/oss/javascript/langchain/tools) của LangChain JS để biết chữ ký của `tool()`.

## Gọi mọi phương thức bằng API key

Các phương thức ngoài `public.methods`, như `eth_getLogs`, cần key. Đọc key từ biến môi trường và gửi trong header `x-api-key`; chain slug (`eth_mainnet`, `base_mainnet`, v.v.) lấy từ `GET /v1/chains`:

```python
import os
import httpx
from langchain.tools import tool

@tool
def rpc_call(chain: str, method: str, params: list) -> dict:
    """Call a JSON-RPC method on a BlockVectra chain slug such as base_mainnet."""
    headers = {"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]}
    body = {"jsonrpc": "2.0", "id": 1, "method": method, "params": params}
    return httpx.post(f"https://api.blockvectra.com/v1/{chain}", json=body, headers=headers, timeout=15).json()
```

Trả về toàn bộ phản hồi JSON-RPC cho phép model đọc đối tượng `error` và thay đổi lệnh gọi tiếp theo. Để tạo key mà không cần trình duyệt, chạy quy trình bốn bước trong [hướng dẫn đăng ký bằng chương trình](https://docs.blockvectra.com/vi/guides/programmatic-signup/?ref=docs-langchain): challenge, chữ ký, đăng nhập, rồi `POST /keys`. Nhà phát triển cũng có thể [tạo key trong console](https://console.blockvectra.com/login/?next=%2Fkeys%2F\&ref=docs-langchain).

## Thêm máy chủ MCP tài liệu

Agent LangChain kết nối tới máy chủ MCP qua `MCPAdapter`. Trỏ nó tới `https://docs.blockvectra.com/mcp` để cấp cho Agent `list_chains`, `get_status`, `rpc_call`, `read_doc` và các công cụ khác được liệt kê trên [trang máy chủ MCP](https://docs.blockvectra.com/vi/guides/mcp-server/). Kết nối không cần key.

```python
from langchain.agents import create_agent
from langchain.mcp import MCPAdapter

async def main():
    async with MCPAdapter("https://docs.blockvectra.com/mcp") as adapter:
        tools = await adapter.list_tools()
        agent = create_agent("claude-sonnet-5", tools)
        return await agent.ainvoke({"messages": [{"role": "user", "content": "List the supported chains."}]})
```

Cài đặt bằng `pip install "langchain[mcp]"` (`langchain>=1.4.0`, đang ở bản beta). Để dùng các công cụ cần key, truyền key dưới dạng bearer token: `MCPAdapter(Client(url, auth=os.environ["BLOCKVECTRA_API_KEY"]))` với `from fastmcp.client import Client`, như trong [hướng dẫn xác thực MCP](https://docs.langchain.com/oss/python/langchain/mcp/auth) của LangChain.

Trong TypeScript, cài `@langchain/mcp-adapters@^2.0.0` và truyền một map header:

```typescript
import { MCPAdapter } from "@langchain/mcp-adapters";
import { createAgent } from "langchain";

const adapter = new MCPAdapter({
  servers: {
    blockvectra: {
      url: "https://docs.blockvectra.com/mcp",
      headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! },
    },
  },
});

try {
  const agent = createAgent({ model: "claude-sonnet-5", tools: await adapter.listTools() });
  // agent.invoke(...)
} finally {
  await adapter.close();
}
```

Bỏ dòng `headers` để kết nối không cần key. Tài liệu tham khảo chính thức: [LangChain MCP (Python)](https://docs.langchain.com/oss/python/langchain/mcp) và [LangChain MCP (JavaScript)](https://docs.langchain.com/oss/javascript/langchain/mcp).

## Các lỗi tool của bạn sẽ gặp

| Phản hồi                              | Ý nghĩa                                                 | Agent nên làm                                                 |
| ------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------- |
| HTTP 401, `-32024`, `missing_api_key` | URL dùng key được gọi mà không có key                   | Gửi key trong `x-api-key` hoặc đường dẫn                      |
| HTTP 401, `-32024`, `invalid_api_key` | Key không tồn tại, đã bị vô hiệu hóa hoặc đã bị thu hồi | Kiểm tra key trong console; key mới cần vài giây để kích hoạt |
| `-32601`, `method_not_public`         | Phương thức không nằm trong `public.methods` của chuỗi  | Dùng URL có key thay cho `/public`                            |
| `-32601`, method not available        | Phương thức chưa được bật trên chuỗi đó                 | Kiểm tra `methods.allow` trong `GET /v1/chains`               |

Mỗi lỗi có `data.reason` và `docs_url`; danh sách đầy đủ nằm trên [trang lỗi](https://docs.blockvectra.com/vi/errors/).

## Câu hỏi thường gặp

**Endpoint công khai có dùng được cho `eth_getLogs` không?** Không. Nó chỉ phục vụ các phương thức trong `public.methods` của chuỗi; `eth_getLogs` và Data API cần API key.

**Agent có thể truyền API key làm tham số của tool không?** Không. Giữ key trong biến môi trường hoặc header của MCP client; máy chủ MCP từ chối key nằm trong tham số của công cụ.

**Tool có thể nhắm tới chuỗi khác không?** Có. Thay `eth_mainnet` bằng bất kỳ chain slug nào có `public.url` trong `GET /v1/chains`.

## Bước tiếp theo

* [Tổng quan framework Agent](https://docs.blockvectra.com/vi/guides/agent-frameworks/) cho ElizaOS, viem, wagmi và Coinbase AgentKit.
* [Kết nối AI Agent](https://docs.blockvectra.com/vi/guides/ai-agents/) để khám phá endpoint bằng MCP, llms.txt và OpenAPI.
* [Quy tắc thanh toán](https://docs.blockvectra.com/vi/guides/billing-rules/) về đo lường CU, giới hạn tốc độ và các lỗi không bị tính phí.