# BlockVectra로 ElizaOS 에이전트에서 블록체인 RPC 사용하기

> Source: https://docs.blockvectra.com/ko/guides/elizaos/

ElizaOS 에이전트는 환경에서 RPC URL을 읽는 `@elizaos/plugin-evm`을 통해 EVM 체인에 접근합니다. `EVM_PROVIDER_URL`을 `https://api.blockvectra.com/v1/eth_mainnet/public`으로 설정하면 플러그인이 API key 없이 이더리움 메인넷에 BlockVectra를 사용합니다. 무료 플랜은 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` 내보내기 이름을 사용해야 하며, 해당 URL 변수는 플러그인의 [npm README](https://www.npmjs.com/package/@elizaos/plugin-evm)에 나온 것처럼 대문자로 된 `ETHEREUM_PROVIDER_<CHAIN_NAME>`입니다.

## API key 사용하기

퍼블릭 엔드포인트는 각 체인의 `public.methods`에 있는 메서드만 다룹니다. 나머지 메서드에는 키를 URL 경로(`/v1/{chain}/{api_key}`)에 넣으세요. 플러그인은 URL만 받으므로, 이곳이 키가 경로로 전달되는 유일한 경우입니다. 키가 커밋하는 파일에 남지 않도록 에이전트를 시작하는 셸에서 변수를 export하세요:

```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은 로그, 프록시, 오류 메시지에 나타날 수 있으므로 에이전트에는 `cu_cap`이 낮은 별도의 키를 사용하고, 유출되면 콘솔에서 폐기하세요.

브라우저 없이 키를 생성하려면 [프로그래밍 방식 회원가입 가이드](https://docs.blockvectra.com/ko/guides/programmatic-signup/?ref=docs-elizaos)의 네 단계(챌린지, 서명, 로그인, 그다음 `POST /keys`)를 따르세요. 개발자는 [콘솔에서 키를 생성](https://console.blockvectra.com/login/?next=%2Fkeys%2F\&ref=docs-elizaos)할 수도 있습니다. 동일한 키가 모든 체인에서 작동하므로 키 하나로 각 `ETHEREUM_PROVIDER_*` 변수를 처리할 수 있습니다.

## docs 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" }
      }
    }
  }
}
```

그러면 에이전트가 키 없이 `list_chains`, `get_status`, `rpc_call`, `read_doc` 및 [MCP 서버 페이지](https://docs.blockvectra.com/ko/guides/mcp-server/)에 나열된 다른 도구를 호출할 수 있습니다. 플러그인이 문서화한 HTTP 옵션은 `type`, `url`, `timeout`이며 헤더 옵션은 문서화되어 있지 않으므로, 이 구성으로는 키가 필요한 MCP 도구에 접근할 수 없습니다. 키가 필요한 읽기는 위와 같이 `plugin-evm`에서 처리하세요.

## 발생할 수 있는 오류

| 응답                                    | 의미                                                   | 해야 할 일                                 |
| ------------------------------------- | ---------------------------------------------------- | -------------------------------------- |
| HTTP 401, `-32024`, `missing_api_key` | 키가 필요한 URL을 키 없이 호출함                                 | 경로 또는 `x-api-key` 헤더에 키를 넣기            |
| HTTP 401, `-32024`, `invalid_api_key` | 키를 알 수 없거나 비활성화되었거나 폐기됨                              | 콘솔에서 키를 확인. 새 키는 활성화되는 데 몇 초가 걸림       |
| `-32601`, `method_not_public`         | 메서드가 체인의 `public.methods`에 없음                        | 해당 체인의 URL을 `/public`에서 키가 필요한 형식으로 변경 |
| 체인을 인식하지 못함                           | `settings.chains.evm`의 이름이 `viem/chains` 이름과 일치하지 않음 | 정확한 `viem/chains` 이름을 사용               |

각 BlockVectra 오류에는 `data.reason`과 `docs_url`이 포함됩니다. 전체 목록은 [오류 페이지](https://docs.blockvectra.com/ko/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>`을 사용합니다.

**에이전트가 퍼블릭 엔드포인트를 통해 트랜잭션에 서명하고 전송할 수 있나요?** `eth_sendRawTransaction`은 이를 나열하는 체인의 `public.methods`에 포함되어 있으며, `GET /v1/chains`의 `public.send_raw_rate_limit`에 IP당 더 낮은 별도의 속도 제한이 있습니다. 이를 기반으로 구축하기 전에 해당 제한을 확인하세요.

**MCP 서버에 키가 필요한가요?** 아니요. 연결과 문서, 체인, 요금 도구는 키가 필요 없습니다.

## 다음 단계

* [에이전트 프레임워크 개요](https://docs.blockvectra.com/ko/guides/agent-frameworks/): LangChain, viem, wagmi, Coinbase AgentKit.
* [AI 에이전트 연결](https://docs.blockvectra.com/ko/guides/ai-agents/): MCP, llms.txt, OpenAPI로 엔드포인트를 탐색합니다.
* [과금 규칙](https://docs.blockvectra.com/ko/guides/billing-rules/): CU 측정, 속도 제한 및 비과금 오류.