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

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

ElizaOS Agent 透過 `@elizaos/plugin-evm` 存取 EVM 鏈，外掛從環境變數讀取 RPC 網址。把 `EVM_PROVIDER_URL` 設為 `https://api.blockvectra.com/v1/eth_mainnet/public`，外掛即可在不需要 API key 的情況下使用 BlockVectra 的以太坊主網。加上 key 可使用其餘方法，免費方案每個 30 天視窗含 30,000,000 CU。核對於 2026-10-11。

```bash
# .env (the plugin also needs the wallet key; keep it in your secret store)
EVM_PRIVATE_KEY=your-wallet-private-key
EVM_PROVIDER_URL=https://api.blockvectra.com/v1/eth_mainnet/public
ETHEREUM_PROVIDER_BASE=https://api.blockvectra.com/v1/base_mainnet/public
```

```json
{
  "name": "DeFiAgent",
  "plugins": ["@elizaos/plugin-evm"],
  "settings": { "chains": { "evm": ["base"] } }
}
```

以 `bun add @elizaos/plugin-evm` 安裝外掛。以太坊主網預設啟用；`settings.chains.evm` 中列出的其他鏈必須使用其 `viem/chains` 匯出名稱，對應的網址變數為大寫的 `ETHEREUM_PROVIDER_<CHAIN_NAME>`，見外掛在 [npm 上的 README](https://www.npmjs.com/package/@elizaos/plugin-evm)。

## 使用 API key

公共端點只涵蓋各鏈 `public.methods` 中的方法。其餘方法請把 key 放進 URL 路徑（`/v1/{chain}/{api_key}`）。該外掛只接受 URL，所以這裡是 key 唯一必須放在路徑中的地方。在啟動 Agent 的 shell 中匯出變數，key 就不會落進會提交的檔案：

```bash
export EVM_PROVIDER_URL=https://api.blockvectra.com/v1/eth_mainnet/${BLOCKVECTRA_API_KEY}
export ETHEREUM_PROVIDER_BASE=https://api.blockvectra.com/v1/base_mainnet/${BLOCKVECTRA_API_KEY}
```

URL 可能出現在日誌、代理與錯誤訊息中，建議為 Agent 另外建立一把 `cu_cap` 較低的 key，洩漏後在控制台撤銷即可。

不用瀏覽器建立 key，請依[程式化建立帳戶指南](https://docs.blockvectra.com/zh-hant/guides/programmatic-signup/?ref=docs-elizaos)的四個步驟操作：challenge、簽章、login，再 `POST /keys`。開發者也可以[在控制台建立 key](https://console.blockvectra.com/login/?next=%2Fkeys%2F\&ref=docs-elizaos)。同一把 key 適用於所有鏈，因此每個 `ETHEREUM_PROVIDER_*` 變數使用同一把 key 即可。

## 接入文件 MCP 伺服器

`@elizaos/plugin-mcp` 讓角色透過 Streamable HTTP 使用遠端 MCP 伺服器。以 `bun add @elizaos/plugin-mcp` 安裝，然後在角色設定中登記 BlockVectra 文件伺服器：

```json
{
  "plugins": ["@elizaos/plugin-evm", "@elizaos/plugin-mcp"],
  "settings": {
    "mcp": {
      "servers": {
        "blockvectra": { "type": "streamable-http", "url": "https://docs.blockvectra.com/mcp" }
      }
    }
  }
}
```

之後 Agent 即可免 key 呼叫 `list_chains`、`get_status`、`rpc_call`、`read_doc` 等 [MCP 伺服器頁面](https://docs.blockvectra.com/zh-hant/guides/mcp-server/)列出的工具。外掛文件中的 HTTP 選項只有 `type`、`url` 與 `timeout`，沒有標頭選項，因此這種設定下無法使用需要 key 的 MCP 工具。需要 key 的讀取請如上所述交給 `plugin-evm`。

## 可能遇到的錯誤

| 回應                                  | 含義                                              | 處理方式                           |
| ----------------------------------- | ----------------------------------------------- | ------------------------------ |
| 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` 中                     | 把該鏈的網址從 `/public` 換成需要 key 的形式 |
| 鏈未被識別                               | `settings.chains.evm` 中的名稱與 `viem/chains` 名稱不一致 | 使用準確的 `viem/chains` 名稱         |

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

## 官方文件

* [ElizaOS 文件](https://elizaos.github.io/eliza/)
* [GitHub 上的 elizaos/eliza](https://github.com/elizaos/eliza)
* [npm 上的 `@elizaos/plugin-evm`](https://www.npmjs.com/package/@elizaos/plugin-evm)
* [npm 上的 `@elizaos/plugin-mcp`](https://www.npmjs.com/package/@elizaos/plugin-mcp)

## 常見問題

**`EVM_PROVIDER_URL` 對 Base 有效嗎？** 無效。它只設定以太坊主網；其他鏈使用 `ETHEREUM_PROVIDER_<CHAIN_NAME>`。

**Agent 能透過公共端點簽章並傳送交易嗎？** 列出 `eth_sendRawTransaction` 的鏈，其 `public.methods` 中包含該方法，並在 `GET /v1/chains` 的 `public.send_raw_rate_limit` 中有單獨且較低的單 IP 速率限制。建置前請先在那裡確認限額。

**使用 MCP 伺服器需要 key 嗎？** 不需要。連線以及文件、鏈與定價工具皆免 key。

## 下一步

* [Agent 框架總覽](https://docs.blockvectra.com/zh-hant/guides/agent-frameworks/)：LangChain、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 計量、速率限制與不計費的錯誤。