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

> Source: https://docs.blockvectra.com/ko/guides/coinbase-agentkit/

Coinbase AgentKit은 지갑 공급자(wallet provider)를 통해 온체인 작업을 전송하며, `ViemWalletProvider`는 모든 viem `WalletClient`를 받습니다. 해당 클라이언트에 `https://api.blockvectra.com/v1/base_mainnet/public`을 전송 계층으로 지정하면 AgentKit의 RPC 트래픽이 API key 없이 BlockVectra를 사용합니다. 키를 사용하면 나머지 메서드도 쓸 수 있으며, 무료 플랜은 30일 주기마다 30,000,000 CU를 제공합니다. 확인일 2026-10-11.

```typescript
import { AgentKit, ViemWalletProvider } from "@coinbase/agentkit";
import { getLangChainTools } from "@coinbase/agentkit-langchain";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const client = createWalletClient({
  account: privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`),
  chain: base,
  transport: http("https://api.blockvectra.com/v1/base_mainnet/public"),
});

const agentKit = await AgentKit.from({ walletProvider: new ViemWalletProvider(client) });
const tools = await getLangChainTools(agentKit);
```

`npm install @coinbase/agentkit @coinbase/agentkit-langchain viem`으로 설치하세요. `tools`는 AgentKit의 [LangChain 통합](https://github.com/coinbase/agentkit/blob/main/typescript/agentkit/README.md)이 `createAgent({ model, tools })`에 전달하는 목록이며, 지갑 키는 사용자의 환경에 그대로 남습니다.

## API key 사용하기

퍼블릭 엔드포인트는 각 체인의 `public.methods`에 있는 메서드만 제공합니다. 다른 메서드에는 키를 `x-api-key` 헤더로 전송하고 환경에 보관하여 URL에 나타나지 않도록 하세요:

```typescript
const transport = http("https://api.blockvectra.com/v1/base_mainnet", {
  fetchOptions: { headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! } },
});
```

클라이언트가 헤더를 설정할 수 없다면 대신 키를 URL 경로(`/v1/{chain}/{api_key}`)에 넣을 수 있습니다. URL은 액세스 로그에 남을 수 있으므로 헤더를 권장합니다.

[프로그래밍 방식 회원가입 가이드](https://docs.blockvectra.com/ko/guides/programmatic-signup/?ref=docs-agentkit)의 네 단계(챌린지, 서명, 로그인, 그다음 `POST /keys`)로 브라우저 없이 키를 생성하세요. 개발자는 [콘솔에서 키를 생성](https://console.blockvectra.com/login/?next=%2Fkeys%2F\&ref=docs-agentkit)할 수도 있습니다. 키 하나가 모든 체인에서 작동하므로, 에이전트를 다른 네트워크로 전환할 때는 체인 슬러그와 viem 체인 객체만 바꾸면 됩니다.

## AgentKit 액션과 docs MCP 서버 결합하기

AgentKit의 TypeScript 패키지는 액션을 LangChain 도구로 노출하므로, LangChain 어댑터의 MCP 도구도 같은 `tools` 배열에 들어갑니다. [LangChain 가이드](https://docs.blockvectra.com/ko/guides/langchain/#docs-mcp-서버-추가하기)를 따라 `https://docs.blockvectra.com/mcp`를 로드한 다음 병합하세요:

```typescript
const agent = createAgent({ model: "claude-sonnet-5", tools: [...tools, ...(await adapter.listTools())] });
```

에이전트는 AgentKit의 지갑 액션과 함께 [MCP 서버 페이지](https://docs.blockvectra.com/ko/guides/mcp-server/)에 나열된 BlockVectra의 `list_chains`, `get_status`, `rpc_call`, `read_doc`을 사용할 수 있습니다. 연결에는 키가 필요하지 않습니다.

## 발생할 수 있는 오류

| 응답                                    | 의미                            | 해야 할 일                               |
| ------------------------------------- | ----------------------------- | ------------------------------------ |
| HTTP 401, `-32024`, `missing_api_key` | 키가 필요한 요청을 키 없이 전송함           | `x-api-key` 헤더(또는 URL 경로)에 키를 넣기     |
| HTTP 401, `-32024`, `invalid_api_key` | 키를 알 수 없거나 비활성화되었거나 폐기됨       | 콘솔에서 키를 확인. 새 키는 활성화되는 데 몇 초가 걸림     |
| `-32601`, `method_not_public`         | 메서드가 체인의 `public.methods`에 없음 | 해당 전송 계층을 `/public`에서 키가 필요한 URL로 변경 |

각 BlockVectra 오류에는 `data.reason`과 `docs_url`이 포함됩니다. 전체 목록은 [오류 페이지](https://docs.blockvectra.com/ko/errors/)에 있습니다.

## 공식 문서

* [GitHub의 coinbase/agentkit](https://github.com/coinbase/agentkit)
* [viem HTTP 전송 계층](https://viem.sh/docs/clients/transports/http.html)

## 자주 묻는 질문

**BlockVectra가 지갑 개인키를 볼 수 있나요?** 아니요. viem 계정이 로컬에서 서명하며, 엔드포인트는 읽기 요청과 서명된 원시 트랜잭션만 받습니다.

**에이전트가 퍼블릭 엔드포인트로 로그를 읽을 수 있나요?** 아니요. `eth_getLogs`와 Data API에는 API key가 필요합니다.

**키를 MCP 도구 인수에 넣나요?** 아니요. 키는 환경 또는 MCP 클라이언트 헤더에 두세요.

## 다음 단계

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