# Use blockchain RPC in ElizaOS agents with BlockVectra

> Original page: https://docs.blockvectra.com/en/guides/elizaos/

ElizaOS agents reach EVM chains through `@elizaos/plugin-evm`, which reads its RPC URLs from the environment. Set `EVM_PROVIDER_URL` to `https://api.blockvectra.com/v1/eth_mainnet/public` and the plugin uses BlockVectra for Ethereum mainnet with no API key. The Free Plan adds keyed methods with 30,000,000 CU per 30-day window. Checked 2026-10-10.

```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"] } }
}
```

Install the plugin with `bun add @elizaos/plugin-evm`. Ethereum mainnet is enabled by default; every other chain you list in `settings.chains.evm` must use its `viem/chains` export name, and its URL variable is `ETHEREUM_PROVIDER_<CHAIN_NAME>` in upper case, as in the plugin's [README on npm](https://www.npmjs.com/package/@elizaos/plugin-evm).

## Use an API key

Public endpoints cover only the methods in each chain's `public.methods`. For the rest, put the key in the URL path (`/v1/{chain}/{api_key}`). The plugin takes only a URL, so this is the one place the key travels in the path. Export the variables in the shell that starts the agent so the key never lands in a file you commit:

```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}
```

URLs can show up in logs, proxies and error messages, so use a separate key with a low `cu_cap` for the agent, and revoke it in the console if it leaks.

To create the key without a browser, follow the four steps in the [programmatic sign-up guide](https://docs.blockvectra.com/en/guides/programmatic-signup/): challenge, signature, login, then `POST /keys`. Developers can also [create a key in the console](https://console.blockvectra.com/login/?next=%2Fkeys%2F). The same key works on every chain, so one key serves each `ETHEREUM_PROVIDER_*` variable.

## Add the docs MCP server

`@elizaos/plugin-mcp` lets a character use remote MCP servers over Streamable HTTP. Install it with `bun add @elizaos/plugin-mcp`, then register the BlockVectra docs server in the character settings:

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

The agent can then call `list_chains`, `get_status`, `rpc_call`, `read_doc` and the other tools listed on the [MCP server page](https://docs.blockvectra.com/en/guides/mcp-server/), keyless. The plugin's documented HTTP options are `type`, `url` and `timeout`; it documents no header option, so keyed MCP tools are out of reach from this config. Keep keyed reads in `plugin-evm` as above.

## Errors you may see

| Response                              | Meaning                                                           | What to do                                                              |
| ------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
| HTTP 401, `-32024`, `missing_api_key` | A keyed URL was called without a key                              | Put the key in the path or the `x-api-key` header                       |
| HTTP 401, `-32024`, `invalid_api_key` | Key unknown, disabled or revoked                                  | Check the key in the console; a new key takes a few seconds to activate |
| `-32601`, `method_not_public`         | Method is not in the chain's `public.methods`                     | Switch that chain's URL from `/public` to the keyed form                |
| Chain not recognised                  | Name in `settings.chains.evm` does not match a `viem/chains` name | Use the exact `viem/chains` name                                        |

Each BlockVectra error includes `data.reason` and a `docs_url`; the full list is on the [errors page](https://docs.blockvectra.com/en/errors/).

## Official documentation

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

## Common questions

**Does `EVM_PROVIDER_URL` apply to Base?** No. It sets Ethereum mainnet only; other chains use `ETHEREUM_PROVIDER_<CHAIN_NAME>`.

**Can an agent sign and send transactions through the public endpoint?** `eth_sendRawTransaction` is in `public.methods` for the chains that list it, with its own lower per-IP rate limit under `public.send_raw_rate_limit` in `GET /v1/chains`. Read the limit there before building on it.

**Do I need a key for the MCP server?** No. Connecting and the documentation, chain and pricing tools are keyless.

## Next steps

* [Agent framework overview](https://docs.blockvectra.com/en/guides/agent-frameworks/) for LangChain, viem, wagmi and Coinbase AgentKit.
* [Connect an AI agent](https://docs.blockvectra.com/en/guides/ai-agents/) to discover endpoints with MCP, llms.txt and OpenAPI.
* [Billing rules](https://docs.blockvectra.com/en/guides/billing-rules/) for CU metering, rate limits and non-billed errors.