# Use RPC de blockchain em agentes LangChain com a BlockVectra

> Source: https://docs.blockvectra.com/pt-br/guides/langchain/

Um agente LangChain lê dados de blockchain em tempo real por meio de uma tool que envia JSON-RPC via POST para `https://api.blockvectra.com/v1/eth_mainnet/public`. Esse endpoint não precisa de API key nem de cadastro para os métodos em `public.methods` de cada rede. Uma chave libera o restante, e o Plano Gratuito oferece 30,000,000 CU por janela de 30 dias. Verificado em 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)
```

Instale com `pip install langchain httpx`; a string do modelo e a chave do provedor seguem o [quickstart do LangChain](https://docs.langchain.com/oss/python/langchain/quickstart). A tool usa o [decorador `@tool`](https://docs.langchain.com/oss/python/langchain/tools) e o [`create_agent`](https://reference.langchain.com/python/langchain/agents/factory/create_agent) do LangChain.

## A mesma tool em 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] });
```

Consulte o [guia de tools](https://docs.langchain.com/oss/javascript/langchain/tools) do LangChain JS para a assinatura de `tool()`.

## Chame qualquer método com uma API key

Métodos fora de `public.methods`, como `eth_getLogs`, precisam de uma chave. Leia-a do ambiente e envie-a no cabeçalho `x-api-key`; o slug da rede (`eth_mainnet`, `base_mainnet` e assim por diante) vem de `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()
```

Retornar a resposta JSON-RPC completa permite que o modelo leia um objeto `error` e mude a próxima chamada. Para criar a chave sem navegador, siga o fluxo de quatro etapas no [guia de cadastro programático](https://docs.blockvectra.com/pt-br/guides/programmatic-signup/?ref=docs-langchain): desafio, assinatura, login e, depois, `POST /keys`. Desenvolvedores também podem [criar uma chave no console](https://console.blockvectra.com/login/?next=%2Fkeys%2F\&ref=docs-langchain).

## Adicione o servidor MCP de documentação

Agentes LangChain se conectam a servidores MCP por meio do `MCPAdapter`. Aponte-o para `https://docs.blockvectra.com/mcp` para dar ao agente `list_chains`, `get_status`, `rpc_call`, `read_doc` e as demais ferramentas listadas na [página do servidor MCP](https://docs.blockvectra.com/pt-br/guides/mcp-server/). Conectar não exige chave.

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

Instale com `pip install "langchain[mcp]"` (`langchain>=1.4.0`, em beta). Para usar ferramentas autenticadas, passe a chave como bearer token: `MCPAdapter(Client(url, auth=os.environ["BLOCKVECTRA_API_KEY"]))` com `from fastmcp.client import Client`, como no [guia de autenticação MCP](https://docs.langchain.com/oss/python/langchain/mcp/auth) do LangChain.

Em TypeScript, instale `@langchain/mcp-adapters@^2.0.0` e passe um mapa de cabeçalhos:

```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();
}
```

Remova a linha `headers` para se conectar sem chave. Referências oficiais: [LangChain MCP (Python)](https://docs.langchain.com/oss/python/langchain/mcp) e [LangChain MCP (JavaScript)](https://docs.langchain.com/oss/javascript/langchain/mcp).

## Erros que a sua tool verá

| Resposta                              | Significado                                   | O que o agente deve fazer                                                     |
| ------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------- |
| HTTP 401, `-32024`, `missing_api_key` | URL autenticada chamada sem chave             | Enviar a chave em `x-api-key` ou no caminho                                   |
| HTTP 401, `-32024`, `invalid_api_key` | Chave desconhecida, desativada ou revogada    | Verificar a chave no console; uma chave nova leva alguns segundos para ativar |
| `-32601`, `method_not_public`         | O método não está em `public.methods` da rede | Usar uma URL autenticada em vez de `/public`                                  |
| `-32601`, método não disponível       | O método não está habilitado nessa rede       | Verificar `methods.allow` em `GET /v1/chains`                                 |

Cada erro traz `data.reason` e um `docs_url`; a lista completa está na [página de erros](https://docs.blockvectra.com/pt-br/errors/).

## Perguntas frequentes

**O endpoint público funciona para `eth_getLogs`?** Não. Ele serve apenas os métodos em `public.methods` da rede; `eth_getLogs` e a Data API precisam de uma API key.

**O agente pode passar a API key como argumento de tool?** Não. Mantenha-a no ambiente ou nos cabeçalhos do cliente MCP; o servidor MCP rejeita chaves em argumentos de ferramentas.

**A tool pode apontar para outra rede?** Sim. Substitua `eth_mainnet` por qualquer slug de rede que tenha um `public.url` em `GET /v1/chains`.

## Próximos passos

* [Visão geral dos frameworks de agentes](https://docs.blockvectra.com/pt-br/guides/agent-frameworks/) para ElizaOS, viem, wagmi e Coinbase AgentKit.
* [Conecte um agente de IA](https://docs.blockvectra.com/pt-br/guides/ai-agents/) para descobrir endpoints com MCP, llms.txt e OpenAPI.
* [Regras de cobrança](https://docs.blockvectra.com/pt-br/guides/billing-rules/) para a medição de CU, limites de taxa e erros não cobrados.