# 在 LangChain Agent 中用 BlockVectra 呼叫區塊鏈 RPC

> Source: https://docs.blockvectra.com/zh-hant/guides/langchain/

LangChain Agent 透過一個工具向 `https://api.blockvectra.com/v1/eth_mainnet/public` 發送 JSON-RPC 請求，即可讀取即時鏈上資料。該端點對各鏈 `public.methods` 中的方法不需要 API key 或註冊；加上 key 可使用其餘方法，免費方案每個 30 天視窗含 30,000,000 CU。核對於 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)
```

以 `pip install langchain httpx` 安裝；模型字串及其供應商 key 依 [LangChain 快速入門](https://docs.langchain.com/oss/python/langchain/quickstart)設定。工具使用 LangChain 的 [`@tool` 裝飾器](https://docs.langchain.com/oss/python/langchain/tools)與 [`create_agent`](https://reference.langchain.com/python/langchain/agents/factory/create_agent)。

## 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] });
```

`tool()` 的簽章請參閱 LangChain JS 的[工具指南](https://docs.langchain.com/oss/javascript/langchain/tools)。

## 攜帶 API key 呼叫任意方法

不在 `public.methods` 中的方法（例如 `eth_getLogs`）需要 key。從環境變數讀取 key，放在 `x-api-key` 標頭；鏈識別碼（`eth_mainnet`、`base_mainnet` 等）取自 `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()
```

回傳完整的 JSON-RPC 回應，模型就能讀到 `error` 物件並調整下一次呼叫。不用瀏覽器建立 key，請依[程式化建立帳戶指南](https://docs.blockvectra.com/zh-hant/guides/programmatic-signup/?ref=docs-langchain)的四個步驟操作：challenge、簽章、login，再 `POST /keys`。開發者也可以[在控制台建立 key](https://console.blockvectra.com/login/?next=%2Fkeys%2F\&ref=docs-langchain)。

## 接入文件 MCP 伺服器

LangChain Agent 透過 `MCPAdapter` 連線到 MCP 伺服器。把它指向 `https://docs.blockvectra.com/mcp`，Agent 即可使用 `list_chains`、`get_status`、`rpc_call`、`read_doc` 等 [MCP 伺服器頁面](https://docs.blockvectra.com/zh-hant/guides/mcp-server/)列出的工具。連線不需要 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."}]})
```

以 `pip install "langchain[mcp]"` 安裝（需要 `langchain>=1.4.0`，目前為 beta）。要使用需要 key 的工具，把 key 作為 bearer token 傳入：`MCPAdapter(Client(url, auth=os.environ["BLOCKVECTRA_API_KEY"]))`，其中 `from fastmcp.client import Client`，寫法見 LangChain 的 [MCP 認證指南](https://docs.langchain.com/oss/python/langchain/mcp/auth)。

在 TypeScript 中，安裝 `@langchain/mcp-adapters@^2.0.0` 並傳入 headers：

```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();
}
```

去掉 `headers` 那一行即為免 key 連線。官方參考：[LangChain MCP（Python）](https://docs.langchain.com/oss/python/langchain/mcp)與 [LangChain MCP（JavaScript）](https://docs.langchain.com/oss/javascript/langchain/mcp)。

## 工具會遇到的錯誤

| 回應                                  | 含義                          | Agent 應該怎麼做                           |
| ----------------------------------- | --------------------------- | ------------------------------------- |
| HTTP 401，`-32024`，`missing_api_key` | 呼叫需要 key 的網址時沒帶 key         | 把 key 放進 `x-api-key` 或路徑              |
| HTTP 401，`-32024`，`invalid_api_key` | key 不存在、已停用或已撤銷             | 在控制台核對 key；新 key 需要幾秒鐘生效              |
| `-32601`，`method_not_public`        | 該方法不在該鏈的 `public.methods` 中 | 改用帶 key 的網址，不再使用 `/public`            |
| `-32601`，method not available       | 該鏈未開放此方法                    | 查看 `GET /v1/chains` 的 `methods.allow` |

每個錯誤都帶有 `data.reason` 與 `docs_url`；完整清單見[錯誤碼頁面](https://docs.blockvectra.com/zh-hant/errors/)。

## 常見問題

**公共端點能呼叫 `eth_getLogs` 嗎？** 不能。它只提供該鏈 `public.methods` 中的方法；`eth_getLogs` 與 Data API 需要 API key。

**Agent 可以把 API key 當作工具參數傳入嗎？** 不可以。把 key 放在環境變數或 MCP 用戶端標頭中；MCP 伺服器會拒絕工具參數中的 key。

**工具能指向其他鏈嗎？** 可以。把 `eth_mainnet` 換成 `GET /v1/chains` 中帶有 `public.url` 的任意鏈識別碼。

## 下一步

* [Agent 框架總覽](https://docs.blockvectra.com/zh-hant/guides/agent-frameworks/)：ElizaOS、viem、wagmi 與 Coinbase AgentKit。
* [連線 AI Agent](https://docs.blockvectra.com/zh-hant/guides/ai-agents/)：透過 MCP、llms.txt 與 OpenAPI 探索端點。
* [計費規則](https://docs.blockvectra.com/zh-hant/guides/billing-rules/)：CU 計量、速率限制與不計費的錯誤。