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

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

LangChain 에이전트는 `https://api.blockvectra.com/v1/eth_mainnet/public`으로 JSON-RPC를 POST하는 도구 하나로 실시간 블록체인 데이터를 읽습니다. 이 엔드포인트는 각 체인의 `public.methods`에 있는 메서드에 대해 API key나 가입이 필요하지 않습니다. 키를 사용하면 나머지 메서드도 쓸 수 있으며, 무료 플랜은 30일 주기마다 30,000,000 CU를 제공합니다. 확인일 2026-10-11.

```python
import httpx
from langchain.agents import create_agent
from langchain.tools import tool

RPC = "https://api.blockvectra.com/v1/eth_mainnet/public"

@tool
def eth_block_number() -> str:
    """Return the latest Ethereum mainnet block number as a hex string."""
    body = {"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []}
    return httpx.post(RPC, json=body, timeout=10).json()["result"]

agent = create_agent("claude-sonnet-5", tools=[eth_block_number])
result = agent.invoke({"messages": [{"role": "user", "content": "What is the latest block?"}]})
print(result["messages"][-1].content)
```

`pip install langchain httpx`로 설치하세요. 모델 문자열과 해당 공급자 키는 [LangChain 빠른 시작](https://docs.langchain.com/oss/python/langchain/quickstart)을 따릅니다. 이 도구는 LangChain의 [`@tool` 데코레이터](https://docs.langchain.com/oss/python/langchain/tools)와 [`create_agent`](https://reference.langchain.com/python/langchain/agents/factory/create_agent)를 사용합니다.

## TypeScript로 작성한 동일한 도구

```typescript
import * as z from "zod";
import { createAgent, tool } from "langchain";

const ethBlockNumber = tool(
  async () => {
    const res = await fetch("https://api.blockvectra.com/v1/eth_mainnet/public", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_blockNumber", params: [] }),
    });
    return (await res.json()).result as string;
  },
  { name: "eth_block_number", description: "Latest Ethereum mainnet block number (hex).", schema: z.object({}) },
);

const agent = createAgent({ model: "claude-sonnet-5", tools: [ethBlockNumber] });
```

`tool()` 시그니처는 LangChain JS [도구 가이드](https://docs.langchain.com/oss/javascript/langchain/tools)를 참조하세요.

## API key로 모든 메서드 호출하기

`eth_getLogs`처럼 `public.methods`에 없는 메서드에는 키가 필요합니다. 환경에서 키를 읽어 `x-api-key` 헤더로 전송하세요. 체인 슬러그(`eth_mainnet`, `base_mainnet` 등)는 `GET /v1/chains`에서 가져옵니다:

```python
import os
import httpx
from langchain.tools import tool

@tool
def rpc_call(chain: str, method: str, params: list) -> dict:
    """Call a JSON-RPC method on a BlockVectra chain slug such as base_mainnet."""
    headers = {"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]}
    body = {"jsonrpc": "2.0", "id": 1, "method": method, "params": params}
    return httpx.post(f"https://api.blockvectra.com/v1/{chain}", json=body, headers=headers, timeout=15).json()
```

JSON-RPC 응답 전체를 반환하면 모델이 `error` 객체를 읽고 다음 호출을 바꿀 수 있습니다. 브라우저 없이 키를 생성하려면 [프로그래밍 방식 회원가입 가이드](https://docs.blockvectra.com/ko/guides/programmatic-signup/?ref=docs-langchain)의 4단계 흐름(챌린지, 서명, 로그인, 그다음 `POST /keys`)을 실행하세요. 개발자는 [콘솔에서 키를 생성](https://console.blockvectra.com/login/?next=%2Fkeys%2F\&ref=docs-langchain)할 수도 있습니다.

## docs MCP 서버 추가하기

LangChain 에이전트는 `MCPAdapter`를 통해 MCP 서버에 연결합니다. 이를 `https://docs.blockvectra.com/mcp`로 지정하면 에이전트가 `list_chains`, `get_status`, `rpc_call`, `read_doc` 및 [MCP 서버 페이지](https://docs.blockvectra.com/ko/guides/mcp-server/)에 나열된 다른 도구를 사용할 수 있습니다. 연결에는 키가 필요하지 않습니다.

```python
from langchain.agents import create_agent
from langchain.mcp import MCPAdapter

async def main():
    async with MCPAdapter("https://docs.blockvectra.com/mcp") as adapter:
        tools = await adapter.list_tools()
        agent = create_agent("claude-sonnet-5", tools)
        return await agent.ainvoke({"messages": [{"role": "user", "content": "List the supported chains."}]})
```

`pip install "langchain[mcp]"`로 설치하세요(`langchain>=1.4.0`, 베타). 키가 필요한 도구를 사용하려면 키를 베어러 토큰으로 전달하세요. LangChain의 [MCP 인증 가이드](https://docs.langchain.com/oss/python/langchain/mcp/auth)처럼 `from fastmcp.client import Client`와 함께 `MCPAdapter(Client(url, auth=os.environ["BLOCKVECTRA_API_KEY"]))`를 사용합니다.

TypeScript에서는 `@langchain/mcp-adapters@^2.0.0`을 설치하고 헤더 맵을 전달하세요:

```typescript
import { MCPAdapter } from "@langchain/mcp-adapters";
import { createAgent } from "langchain";

const adapter = new MCPAdapter({
  servers: {
    blockvectra: {
      url: "https://docs.blockvectra.com/mcp",
      headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! },
    },
  },
});

try {
  const agent = createAgent({ model: "claude-sonnet-5", tools: await adapter.listTools() });
  // agent.invoke(...)
} finally {
  await adapter.close();
}
```

키 없이 연결하려면 `headers` 줄을 제거하세요. 공식 레퍼런스: [LangChain MCP (Python)](https://docs.langchain.com/oss/python/langchain/mcp) 및 [LangChain MCP (JavaScript)](https://docs.langchain.com/oss/javascript/langchain/mcp).

## 도구에서 볼 수 있는 오류

| 응답                                    | 의미                            | 에이전트가 해야 할 일                          |
| ------------------------------------- | ----------------------------- | ------------------------------------- |
| HTTP 401, `-32024`, `missing_api_key` | 키가 필요한 URL을 키 없이 호출함          | `x-api-key` 또는 경로에 키를 전송              |
| HTTP 401, `-32024`, `invalid_api_key` | 키를 알 수 없거나 비활성화되었거나 폐기됨       | 콘솔에서 키를 확인. 새 키는 활성화되는 데 몇 초가 걸림      |
| `-32601`, `method_not_public`         | 메서드가 체인의 `public.methods`에 없음 | `/public` 대신 키가 필요한 URL을 사용           |
| `-32601`, method not available        | 해당 체인에서 메서드가 활성화되지 않음         | `GET /v1/chains`의 `methods.allow`를 확인 |

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

## 자주 묻는 질문

**퍼블릭 엔드포인트에서 `eth_getLogs`가 작동하나요?** 아니요. 체인의 `public.methods`에 있는 메서드만 제공합니다. `eth_getLogs`와 Data API에는 API key가 필요합니다.

**에이전트가 API key를 도구 인수로 전달할 수 있나요?** 아니요. 키는 환경 또는 MCP 클라이언트 헤더에 두세요. MCP 서버는 도구 인수에 담긴 키를 거부합니다.

**도구가 다른 체인을 대상으로 할 수 있나요?** 네. `eth_mainnet`을 `GET /v1/chains`에서 `public.url`이 있는 아무 체인 슬러그로 바꾸세요.

## 다음 단계

* [에이전트 프레임워크 개요](https://docs.blockvectra.com/ko/guides/agent-frameworks/): ElizaOS, 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 측정, 속도 제한 및 비과금 오류.