# 在 ElizaOS Agent 中用 BlockVectra 调用区块链 RPC

> 原文地址: https://docs.blockvectra.com/zh/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-10。

```bash
# .env（插件还需要钱包密钥；请放在你的密钥库里）
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/guides/programmatic-signup/)的四步操作：challenge、签名、login，再 `POST /keys`。开发者也可以[在控制台创建 key](https://console.blockvectra.com/login/?next=%2Fkeys%2F)。同一个 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/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/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/guides/agent-frameworks/)：LangChain、viem、wagmi 与 Coinbase AgentKit。
* [接入 AI Agent](https://docs.blockvectra.com/zh/guides/ai-agents/)：通过 MCP、llms.txt 和 OpenAPI 自动发现接口。
* [计费规则](https://docs.blockvectra.com/zh/guides/billing-rules/)：CU 计量、速率限制与不计费错误。