# RPC de blockchain e MCP de documentação para agentes de IA > Source: https://docs.blockvectra.com/pt-br/guides/ai-agents/ Comece pelo [endpoint MCP de documentação](https://docs.blockvectra.com/mcp) sem chave para descobrir métodos RPC de blockchain, conjuntos de dados da Data API, preços e documentação. Agentes de IA são usuários de primeira classe: desenvolvedores e agentes de IA utilizam as mesmas APIs, regras, limites e preços. 1. **Descobrir**: use o MCP de documentação, `llms.txt`, OpenAPI e JSON público para escolher uma rede e um método. Chamadas RPC sem chave são limitadas aos `public.methods` da rede. 2. **Abrir uma conta via HTTP**: siga o [cadastro programático](https://docs.blockvectra.com/en/guides/programmatic-signup/) para entrar com uma assinatura de carteira e criar uma API key. A ferramenta `how_to_get_api_key` do MCP retorna instruções para esse fluxo HTTP separado. 3. **Chamar APIs de dados**: mantenha a chave em `BLOCKVECTRA_API_KEY` e use-a para requisições autenticadas de RPC ou Data API. Para ferramentas MCP autenticadas, configure o cabeçalho `x-api-key` no cliente; as operações permitidas de cada ferramenta estão listadas abaixo. ## 1. Contexto legível por máquina e especificações A BlockVectra publica arquivos voltados para agentes LLM e ferramentas de desenvolvedor: ### Índices llms.txt Seguindo a convenção [llmstxt.org](https://llmstxt.org), estes arquivos fornecem aos agentes um resumo estruturado do site e de seus endpoints: * **Índice do site principal**: [llms.txt do site principal](https://blockvectra.com/llms.txt) — visão geral do site principal, redes suportadas, preços e APIs públicas. * **Índice da documentação**: [llms.txt da documentação](https://docs.blockvectra.com/llms.txt) — catálogo de cada página da documentação com título e descrição. ### Arquivo completo de documentação (`llms-full.txt`) * **Documentação completa**: [llms-full.txt](https://docs.blockvectra.com/llms-full.txt) — o texto completo de cada página da documentação em inglês em um único arquivo Markdown em texto simples, adequado para carregamento no system prompt de um agente ou para ingestão em pipelines de RAG (Retrieval-Augmented Generation). ### Especificações OpenAPI 3.1 para download O site de documentação disponibiliza arquivos YAML OpenAPI 3.1 que podem ser importados diretamente em frameworks de agentes, geradores de ferramentas ou clientes de API: * **Especificação da API JSON-RPC**: [/openapi/json-rpc.yaml](https://docs.blockvectra.com/openapi/json-rpc.yaml) — métodos suportados, política de métodos por rede, respostas de erro e medição em Unidades de Computação (CU). * **Especificação da Data API**: [/openapi/data.yaml](https://docs.blockvectra.com/openapi/data.yaml) — definições de endpoints REST para blocos indexados, transações, transferências, saldos, detentores e conjuntos de dados relacionados. * **Especificação da Push API**: [/openapi/push.yaml](https://docs.blockvectra.com/openapi/push.yaml) — gerenciamento de inscrições HTTP, endereços de carteiras monitorados, eventos de webhook, assinaturas e repetição (replay). Para atividade de endereços de carteira, siga o [guia da API Webhook de blockchain](https://docs.blockvectra.com/en/guides/webhook-push/). Para notificações de pagamentos ERC-20 USDT / USDC, utilize o [exemplo de receptor de pagamentos](https://docs.blockvectra.com/en/guides/stablecoin-payments/#receive-payments-with-webhooks). Desenvolvedores e agentes de IA criam e gerenciam inscrições por meio da Push API HTTP com `x-api-key`; o MCP de documentação permite a descoberta e leitura desses guias. Para controle de versões no caminho, regras de compatibilidade com versões anteriores e recomendações para autores de agentes e SDKs, consulte [Versionamento e compatibilidade de API](https://docs.blockvectra.com/en/api/versioning/). Para receitas prontas para uso nos principais frameworks (ElizaOS, viem, wagmi, Coinbase AgentKit), consulte [Receitas de integração com frameworks de agentes](https://docs.blockvectra.com/en/guides/agent-frameworks/). ### Servidor do Model Context Protocol (MCP) A BlockVectra expõe um servidor MCP sem estado e sem necessidade de chave via Streamable HTTP: * **Endpoint**: [Endpoint MCP](https://docs.blockvectra.com/mcp) (HTTP POST recebendo JSON-RPC 2.0; GET retorna 405) * **Transporte**: MCP Streamable HTTP (sem estado, nenhuma API key exigida) #### Ferramentas disponíveis 1. `read_doc(path, lang?)`: retorna o conteúdo Markdown bruto de qualquer página da documentação a partir de `/md/{lang}/{path}.md`. Aceita caminhos relativos internos (por exemplo, `quickstart`, `guides/ai-agents`, `api/json-rpc`, `chains`). 2. `search_docs(query, lang?, limit?)`: pesquisa páginas da documentação por títulos, caminhos e resumos. 3. `list_chains()`: lê as redes de blockchain suportadas, parâmetros estáticos e políticas de métodos de `GET /v1/chains`. 4. `get_status()`: lê a prontidão do serviço em tempo real, o status das redes, as alturas dos blocos mais recentes e o atraso de sincronização de `GET /v1/status`. 5. `get_pricing()`: lê os pesos de Unidades de Computação (CU), parâmetros do Plano Gratuito e limites padrão de chave de `GET /v1/plans`. 6. `estimate_usage(lines?, method?, calls_per_day?)`: estima Unidades de Computação (CU), custo bruto de tabela e custo líquido após a dedução da cota gratuita do ciclo para um ou mais métodos (suporta formato multilinhas `lines: [{method, calls_per_day}]` ou `method` e `calls_per_day` únicos). Também relata limites de taxa por chave de `key_defaults` e sugere o número de chaves de API necessárias quando o tráfego ultrapassar os limites de uma única chave. 7. `how_to_get_api_key(lang?)`: retorna as etapas de obtenção de API key e os formatos de autenticação de requisições para JSON-RPC e Data API. 8. `get_method_info(method, chain?)`: retorna a disponibilidade na rede, o peso em Unidades de Computação (CU), o preço por milhão de chamadas e o link da documentação para um método. A disponibilidade de JSON-RPC segue `methods.allow` e `deny` em `GET /v1/chains`; a cobertura de conjuntos de dados da Data API segue `data_features` em `GET /v1/status`, com `data: true` no catálogo de redes. 9. `explain_error(reason?, code?, http_status?)`: consulta explicações sobre erros, implicações de faturamento, possibilidade de nova tentativa e ações de recuperação no catálogo de erros. 10. `list_docs(lang?)`: lista todas as páginas da documentação com caminhos relativos e títulos a partir do índice da documentação. 11. `rpc_call(chain, method, params?)`: executa uma chamada JSON-RPC 2.0 somente leitura em uma rede suportada com sua API key (`readOnlyHint: true`). Métodos de escrita (como `eth_sendRawTransaction`) são rejeitados; use `send_raw_transaction` em vez disso. Requer o cabeçalho `x-api-key` na configuração do cliente MCP para acesso completo, ou usa o endpoint público sem chave se disponível. 12. `data_api_get(chain, path, query?)`: emite uma requisição GET para a Data API para uma rede e caminho suportados com sua API key (`readOnlyHint: true`). Requer o cabeçalho `x-api-key` na configuração do cliente MCP. 13. `get_account()`: consulta o saldo da conta, Unidades de Computação (CU), limites de taxa e parâmetros da chave a partir de `GET /v1/account` com sua API key (`readOnlyHint: true`). Requer o cabeçalho `x-api-key` na configuração do cliente MCP. 14. `get_deposit_address()`: consulta o endereço exclusivo de depósito on-chain, as redes abertas e os tokens a partir de `GET /v1/topup/deposit-address` com sua API key (`readOnlyHint: true`). Transfira fundos apenas para as redes e tokens listados. Requer o cabeçalho `x-api-key` na configuração do cliente MCP. 15. `send_raw_transaction(chain, raw_tx)`: transmite uma transação bruta assinada para uma rede suportada via `eth_sendRawTransaction` (`destructiveHint: true`). Requer o cabeçalho `x-api-key` na configuração do cliente MCP para acesso completo, ou usa o endpoint público sem chave se permitido na rede. #### Ferramentas autenticadas Ferramentas autenticadas exigem uma API key para executar consultas on-chain, transações, requisições à Data API ou operações de conta. **Segurança da API key**: * **Leitura estrita a partir dos cabeçalhos**: A API key é lida exclusivamente dos cabeçalhos de requisição HTTP do cliente MCP (`x-api-key: rgw_...` ou `Authorization: Bearer rgw_...`). * **Nunca insira chaves no chat**: Nunca passe chaves de API ou chaves privadas em argumentos de ferramentas nem as cole no chat. Argumentos de ferramentas e histórico de chat entram em logs e contextos de conversas; passar chaves em argumentos será rejeitado. Se chamadas sem um cabeçalho de API key, estas ferramentas retornam `isError: true` e direcionam o agente para `how_to_get_api_key` e o guia de integração programática. ### Conectar-se a partir de clientes MCP Você pode se conectar ao servidor MCP de documentação da BlockVectra em `https://docs.blockvectra.com/mcp` nos ambientes de desenvolvimento e frameworks mais comuns. Comece sem uma API key. Conecte-se ao endpoint MCP, chame list\_chains e, em seguida, leia o quickstart com read\_doc. Adicione uma API key nos cabeçalhos HTTP do seu cliente quando precisar da Data API ou de ferramentas de conta. O acesso RPC sem chave segue a política de métodos públicos de cada rede. O cabeçalho `x-api-key` é opcional. Sem uma API key, os clientes podem usar todas as ferramentas de documentação somente leitura (`read_doc`, `search_docs`, `list_docs`), descoberta de redes (`list_chains`), status em tempo real (`get_status`), estimativa de preços (`get_pricing`, `estimate_usage`), explicações de erros (`explain_error`) e métodos permitidos em endpoints públicos. Ao usar ferramentas autenticadas (`rpc_call` em métodos restritos, `send_raw_transaction`, `data_api_get`, `get_account` e `get_deposit_address`), configure o cabeçalho `x-api-key` com sua API key. #### Claude Code Conecte-se ao servidor MCP usando a CLI: ```bash claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp ``` Para incluir uma API key opcional para ferramentas autenticadas, passe a opção `--header` (ou `-H`): ```bash claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp \ --header "x-api-key: YOUR_API_KEY" ``` Documentação oficial: [documentação de MCP do Claude Code](https://code.claude.com/docs/en/mcp). #### Cursor Adicione o servidor à configuração de MCP do Cursor: ```json { "mcpServers": { "blockvectra": { "url": "https://docs.blockvectra.com/mcp" } } } ``` O Cursor também suporta instalação em um clique por meio de deep links usando a configuração codificada em base64 `eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9` (representando `{"url":"https://docs.blockvectra.com/mcp"}`): ```text cursor://anysphere.cursor-deeplink/mcp/install?name=blockvectra&config=eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9 ``` Quando precisar de ferramentas autenticadas (Data API ou gerenciamento de conta), adicione o objeto `headers` com sua API key: ```json { "mcpServers": { "blockvectra": { "url": "https://docs.blockvectra.com/mcp", "headers": { "x-api-key": "YOUR_API_KEY" } } } } ``` Documentação oficial: [documentação de MCP do Cursor](https://cursor.com/docs/context/mcp) e [links de instalação do Cursor](https://cursor.com/docs/context/mcp/install-links). #### VS Code No VS Code, configure o servidor em `.vscode/mcp.json` sob a chave de nível superior `servers` com `type: "http"`: ```json { "servers": { "blockvectra": { "type": "http", "url": "https://docs.blockvectra.com/mcp" } } } ``` Quando precisar de ferramentas autenticadas, adicione o objeto `headers`: ```json { "servers": { "blockvectra": { "type": "http", "url": "https://docs.blockvectra.com/mcp", "headers": { "x-api-key": "YOUR_API_KEY" } } } } ``` Ao armazenar credenciais confidenciais, o VS Code permite referenciar variáveis de entrada ou arquivos de ambiente em vez de fixar as chaves no código. Você também pode adicionar servidores usando a ação `MCP: Add Server` da Paleta de Comandos. Documentação oficial: [documentação de servidores MCP do VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) e [referência de configuração MCP do VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration). #### Codex Adicione o servidor usando a CLI do OpenAI Codex: ```bash codex mcp add blockvectra --url https://docs.blockvectra.com/mcp ``` Em `config.toml`, configure a URL do servidor: ```toml [mcp_servers.blockvectra] url = "https://docs.blockvectra.com/mcp" ``` Quando precisar de ferramentas autenticadas, configure os cabeçalhos de requisição em `config.toml`: ```toml [mcp_servers.blockvectra] url = "https://docs.blockvectra.com/mcp" http_headers = { "x-api-key" = "YOUR_API_KEY" } ``` Alternativamente, mapeie o cabeçalho a partir de uma variável de ambiente: ```toml [mcp_servers.blockvectra] url = "https://docs.blockvectra.com/mcp" env_http_headers = { "x-api-key" = "BLOCKVECTRA_API_KEY" } ``` Documentação oficial: [documentação de MCP da CLI do OpenAI Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). #### Gemini CLI Na configuração da Gemini CLI, adicione o servidor sob `mcpServers` usando `httpUrl` para Streamable HTTP: ```json { "mcpServers": { "blockvectra": { "httpUrl": "https://docs.blockvectra.com/mcp" } } } ``` Quando precisar de ferramentas autenticadas, adicione o objeto `headers` com sua API key: ```json { "mcpServers": { "blockvectra": { "httpUrl": "https://docs.blockvectra.com/mcp", "headers": { "x-api-key": "YOUR_API_KEY" } } } } ``` Documentação oficial: [documentação de servidor MCP da Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md). #### OpenAI Responses API Ao chamar a OpenAI Responses API, passe o servidor MCP no array `tools` com `type: "mcp"`: ```bash OPENAI_API_BASE="https://api.openai.com/v1" curl "$OPENAI_API_BASE/responses" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "", "tools": [{ "type": "mcp", "server_label": "blockvectra", "server_url": "https://docs.blockvectra.com/mcp", "require_approval": "never" }], "input": "..." }' ``` Quando precisar de ferramentas autenticadas, inclua o campo `headers` na definição da ferramenta: ```json { "type": "mcp", "server_label": "blockvectra", "server_url": "https://docs.blockvectra.com/mcp", "headers": { "x-api-key": "YOUR_API_KEY" }, "require_approval": "never" } ``` Documentação oficial: [guia de ferramentas MCP da OpenAI](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) e [referência da OpenAI Responses API](https://developers.openai.com/api/reference/resources/responses/methods/create). #### Windsurf No Windsurf, configure o servidor sob `mcpServers` usando o campo `serverUrl`: ```json { "mcpServers": { "blockvectra": { "serverUrl": "https://docs.blockvectra.com/mcp" } } } ``` Quando precisar de ferramentas autenticadas, adicione o objeto `headers` com sua API key: ```json { "mcpServers": { "blockvectra": { "serverUrl": "https://docs.blockvectra.com/mcp", "headers": { "x-api-key": "YOUR_API_KEY" } } } } ``` O Windsurf também suporta referenciar variáveis de ambiente, como `"x-api-key": "${env:BLOCKVECTRA_API_KEY}"`. Documentação oficial: [documentação de MCP do Windsurf](https://docs.devin.ai/desktop/cascade/mcp). #### Claude Desktop e claude.ai Os conectores personalizados são configurados pela interface do usuário: * **claude.ai**: Navegue até **Customize** > **Connectors**, clique em **+ Add**, selecione **Add custom connector** e insira a URL: ```text https://docs.blockvectra.com/mcp ``` * **Claude Desktop**: Abra o menu de configurações da conta e configure conectores personalizados por meio da interface de conectores. Conectar-se à URL permite que o Claude pesquise guias, leia a documentação em Markdown, inspecione as redes suportadas, verifique o status da rede e calcule estimativas de preço sem necessidade de credenciais. Documentação oficial: [guia de conectores personalizados do Claude](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp). ## 2. Endpoints JSON públicos (nenhuma chave necessária) Um agente pode inspecionar redes disponíveis, status em tempo real e parâmetros de planos antes de enviar qualquer requisição tarifada. Nenhum desses endpoints precisa de uma API key: * `GET /v1/status` e `GET /v1/chains` não exigem autenticação e não são tarifados. * `GET /v1/plans` é público e não exige autenticação. Todos os três enviam `Access-Control-Allow-Origin: *`. ### Status do serviço (`GET /v1/status`) Retorna a prontidão do serviço e o status de sincronização de cada rede pública: ```bash curl -s "https://api.blockvectra.com/v1/status" ``` Campos da resposta: * `checked_at`: quando o snapshot foi gerado (RFC 3339 / ISO 8601 UTC). * `gateway.status`: status de execução do serviço. `ok` significa que o serviço está pronto; `degraded` significa que requisições pagas são rejeitadas até a recuperação. Este valor independe do status do nó de qualquer rede. * `chains[]`: as redes disponibilizadas ao público: * `chain`: slug da rede (por exemplo, `robinhood_mainnet`). * `name`: nome legível para exibição. * `chain_id`: EIP-155 chain ID (inteiro decimal). * `jsonrpc`: se o JSON-RPC é disponibilizado. * `data`: se a Data API é disponibilizada. * `data_features`: capacidades da Data API disponíveis para esta rede (um array vazio quando `data` é `false`). * `data_status`: status de execução da Data API (`ok`, `syncing` ou `unavailable`; presente apenas quando `data` é `true`). * `status`: status do nó da rede (`ok` ou `unavailable`). * `head`: informações do bloco mais recente — `block` (altura do bloco mais recente), `time` (timestamp do bloco) e `lag_seconds` (quanto tempo o bloco está atrasado em relação ao horário atual) — ou `null` quando desconhecido. Exemplo de resposta: ```json { "checked_at": "2026-09-28T12:00:00Z", "gateway": { "status": "ok" }, "chains": [ { "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663, "jsonrpc": true, "data": true, "data_features": [ "blocks", "transactions", "address_transactions", "transfers", "token_metadata", "freshness" ], "status": "ok", "head": { "block": 73017329, "time": "2026-09-28T11:59:58Z", "lag_seconds": 2 } } ] } ``` ### Parâmetros da rede (`GET /v1/chains`) Retorna os parâmetros estáticos e a política de métodos de cada rede pública: ```bash curl -s "https://api.blockvectra.com/v1/chains" ``` Campos da resposta: * `chains[]`: redes públicas e seus parâmetros estáticos: * `chain`: slug da rede. * `name`: nome legível para exibição. * `chain_id`: EIP-155 chain ID. * `jsonrpc`: se o JSON-RPC é disponibilizado. * `data`: se a Data API é disponibilizada. * `ws`: se há suporte a conexões WebSocket. * `subscriptions`: tipos de inscrição WebSocket suportados (por exemplo, `newHeads`, `logs`). * `methods`: política de métodos: * `allow`: nomes de métodos permitidos (por exemplo, `eth_call`, `debug_traceTransaction`). * `deny`: métodos negados ou padrões curinga de prefixo (por exemplo, `eth_newFilter`). Métodos negados têm precedência sobre os permitidos. * `max_logs_block_range`: intervalo máximo de blocos permitido em uma única requisição `eth_getLogs`. * `state_window_blocks`: janela de estado histórico em blocos; `null` quando o histórico completo está disponível. * `info`: dados públicos de extensão por rede (reservado; atualmente um objeto vazio `{}`). * `public`: configuração do endpoint público não autenticado (ou `null`): * `url`: URL base para requisições públicas. * `methods`: métodos permitidos no endpoint público. * `rate_limit`: limites de taxa (`per_ip_rps`, `burst`, `batch_max`). * `history_blocks`: histórico de blocos acessível no endpoint público. * `send_raw_rate_limit`: limites de taxa para transmissão de transações via `eth_sendRawTransaction`. Exemplo de resposta: ```json { "chains": [ { "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663, "jsonrpc": true, "data": true, "ws": true, "subscriptions": [ "newHeads", "logs" ], "methods": { "allow": [ "eth_blockNumber", "eth_call", "eth_chainId", "debug_traceTransaction" ], "deny": [ "eth_newFilter", "eth_newBlockFilter", "eth_newPendingTransactionFilter", "eth_getFilterLogs", "eth_getFilterChanges", "eth_uninstallFilter", "eth_subscribe", "eth_unsubscribe" ] }, "max_logs_block_range": 1000, "state_window_blocks": 900, "info": {}, "public": { "url": "https://api.blockvectra.com/v1/robinhood_mainnet/public", "methods": [ "eth_chainId", "net_version", "eth_blockNumber", "eth_call" ], "rate_limit": { "per_ip_rps": 3, "burst": 20, "batch_max": 10 }, "history_blocks": 128, "send_raw_rate_limit": { "per_ip_rps": 1, "burst": 3 } } } ] } ``` ### Planos e pesos de métodos (`GET /v1/plans`) Os parâmetros dos planos são disponibilizados em `GET https://console-api.blockvectra.com/v1/plans`. Um agente pode consultar esse endpoint em tempo de execução para ler os limites ativos do plano gratuito e o peso em Unidades de Computação (CU) de cada método: * `free`: parâmetros do Plano Gratuito — `signup_units` (concessão de cadastro, em unidades), `monthly_units` (nível de recarga do ciclo, em unidades), `window_days` (duração do ciclo de uso em dias) e `max_calls_per_sec` (limite de chamadas por segundo do plano gratuito). * `pricing`: parâmetros de planos pagos — `units_per_usd` (unidades por 1 USD), `cu_per_unit` (CU por unidade) e `min_topup_usd` (recarga mínima em USD). * `method_weights`: pesos em CU por chamada, cada um `{ "method": string, "cu_weight": number }`. `method` especifica o nome ou padrão do método JSON-RPC, pesos padrão para métodos não listados ou uma operação da Data API como `data.`. Os pesos são definidos por método e não são divididos por rede. ## 3. Autenticação e segurança de chaves Agentes que emitem chamadas RPC devem seguir estas regras: * **Autenticação**: forneça a API key de uma das três maneiras. No caminho: `POST /v1/{chain}/{api_key}` — o formato de caminho usa exclusivamente a chave contida na URL e ignora ambos os cabeçalhos. No cabeçalho `x-api-key`: `POST /v1/{chain}` com `x-api-key: $BLOCKVECTRA_API_KEY`. No cabeçalho `Authorization`: `POST /v1/{chain}` com `Authorization: Bearer $BLOCKVECTRA_API_KEY`. Quando ambos os cabeçalhos estão presentes, um `x-api-key` não vazio tem prioridade; Bearer só é usado se `x-api-key` estiver ausente ou vazio. A mesma chave funciona em todas as redes suportadas e na Data API (que aceita a chave somente no cabeçalho `x-api-key`). * **Segurança de chaves**: mantenha as chaves de API em variáveis de ambiente no servidor (por exemplo, `BLOCKVECTRA_API_KEY`) ou em um gerenciador de segredos. Nunca incorpore uma chave em código de navegador ou em qualquer bundle do lado do cliente. Embora os endpoints retornem `Access-Control-Allow-Origin: *`, eles foram projetados para serem chamados por serviços de backend, e não a partir do navegador. * **Tarifação e upgrades**: o uso é tarifado em Unidades de Computação (CU): cada método consome CU de acordo com seu peso, e o saldo, os baldes de CU e os limites de taxa do plano gratuito são compartilhados entre todas as redes. Após uma recarga paga, o limite de chamadas por segundo do plano gratuito deixa de ser aplicado; cada chave ainda mantém seu limite de taxa e capacidade de pico de CU. Os Créditos Gratuitos não utilizados permanecem no seu saldo de Créditos e ainda podem ser usados. Consulte a [página de preços](https://blockvectra.com/en/pricing/) para obter detalhes. > **Ainda não tem uma API key?** > > Se você tiver uma carteira Ethereum: siga o [guia de cadastro programático](https://docs.blockvectra.com/en/guides/programmatic-signup/) para se cadastrar e criar uma API key usando uma assinatura de carteira Ethereum sem navegador. A identidade de um agente é sua carteira: caso um token de sessão ou chave seja perdido, [autentique-se novamente com a mesma carteira para recuperá-lo](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key). Se você não tiver uma carteira: peça ao usuário para entrar em [console.blockvectra.com](https://console.blockvectra.com/login/?next=%2Fkeys%2F), criar uma chave e defini-la como a variável de ambiente `BLOCKVECTRA_API_KEY`. Não peça ao usuário para colar a chave no chat. ### Consultar saldo (`GET /v1/account`) Um agente pode verificar o saldo atual de sua chave, limites de CU e parâmetros de chave diretamente sem consumir Unidades de Computação (CU). Para o formato de requisição, limites de taxa e definições completas dos campos de resposta, consulte [Consultar saldo: GET /v1/account](https://docs.blockvectra.com/en/guides/billing-rules/#query-balance-get-v1account). ## 4. Fluxo de seleção de redes para agentes Antes de disparar chamadas, um agente pode seguir estes passos: 1. **Verificar a rede e sua política de métodos**: chame `GET /v1/chains`, confirme se a rede de destino existe e tem `jsonrpc: true`, e se o método que pretende chamar é permitido por `methods.allow` e não está negado em `methods.deny` (a negação tem prioridade). 2. **Verificar o status em tempo real**: chame `GET /v1/status` e confirme se `gateway.status` está `ok` e se o `status` da rede de destino é `ok`; use `head.lag_seconds` para decidir se os dados da rede estão recentes o suficiente para seu caso de uso. Quando o nó de uma rede não estiver sincronizado, todos os métodos exceto `eth_chainId` retornam o erro JSON-RPC `-32010` (HTTP 200, não tarifado), permitindo ao agente aguardar e tentar novamente ou escolher outra rede. 3. **Enviar a requisição**: `POST /v1/{chain}` com o cabeçalho `x-api-key` e um corpo JSON-RPC padrão. ## 5. Exemplo funcional mínimo O exemplo abaixo lê `/v1/chains` para escolher uma rede que permita `eth_blockNumber`, verifica `/v1/status` e depois chama `eth_blockNumber` uma vez. **cURL** ```bash export BLOCKVECTRA_API_KEY="rgw_your_api_key" # 1. List public chains and their method policy curl -s "https://api.blockvectra.com/v1/chains" # 2. Check the service and per-chain status curl -s "https://api.blockvectra.com/v1/status" # 3. Call eth_blockNumber on the chain you selected (e.g. robinhood_mainnet) curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \ -H "x-api-key: $BLOCKVECTRA_API_KEY" \ -H "x-bv-meter: 1" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' ``` **TypeScript** ```typescript const apiKey = process.env.BLOCKVECTRA_API_KEY; if (!apiKey) { throw new Error("Missing BLOCKVECTRA_API_KEY"); } type ChainFacts = { chain: string; jsonrpc: boolean; methods: { allow: string[]; deny: string[] }; }; function matches(pattern: string, method: string): boolean { if (pattern === "*") return true; if (pattern.endsWith("*")) return method.startsWith(pattern.slice(0, -1)); return pattern === method; } // 1. Fetch the public chain directory const chainsRes = await fetch("https://api.blockvectra.com/v1/chains"); const { chains } = (await chainsRes.json()) as { chains: ChainFacts[] }; // 2. Select a chain that serves JSON-RPC and allows eth_blockNumber const selected = chains.find( (chain) => chain.jsonrpc && !chain.methods.deny.some((pattern) => matches(pattern, "eth_blockNumber")) && chain.methods.allow.some((pattern) => matches(pattern, "eth_blockNumber")), ); if (!selected) { throw new Error("No chain found that allows eth_blockNumber"); } // 3. Confirm the service and the selected chain are ready const statusRes = await fetch("https://api.blockvectra.com/v1/status"); const status = await statusRes.json(); const chainStatus = status.chains?.find( (chain: { chain: string }) => chain.chain === selected.chain, ); if (status.gateway?.status !== "ok" || chainStatus?.status !== "ok") { throw new Error(`Chain ${selected.chain} is currently unavailable`); } // 4. Call eth_blockNumber on the selected chain const defaultEndpoint = "https://api.blockvectra.com/v1/robinhood_mainnet"; const rpcUrl = `${defaultEndpoint.slice(0, defaultEndpoint.lastIndexOf("/"))}/${selected.chain}`; const rpcRes = await fetch(rpcUrl, { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": apiKey, "x-bv-meter": "1", }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_blockNumber", params: [], }), }); console.log("Response:", await rpcRes.json()); ``` **Python** ```python import os import requests api_key = os.environ["BLOCKVECTRA_API_KEY"] def matches(pattern: str, method: str) -> bool: if pattern == "*": return True if pattern.endswith("*"): return method.startswith(pattern[:-1]) return pattern == method # 1. Fetch the public chain directory chains = requests.get("https://api.blockvectra.com/v1/chains").json()["chains"] # 2. Select a chain that serves JSON-RPC and allows eth_blockNumber selected = next( ( chain for chain in chains if chain["jsonrpc"] and not any(matches(p, "eth_blockNumber") for p in chain["methods"]["deny"]) and any(matches(p, "eth_blockNumber") for p in chain["methods"]["allow"]) ), None, ) if selected is None: raise RuntimeError("No chain found that allows eth_blockNumber") # 3. Confirm the service and the selected chain are ready status = requests.get("https://api.blockvectra.com/v1/status").json() chain_status = next( (c for c in status["chains"] if c["chain"] == selected["chain"]), None, ) if ( status["gateway"]["status"] != "ok" or chain_status is None or chain_status["status"] != "ok" ): raise RuntimeError(f"Chain {selected['chain']} is currently unavailable") # 4. Call eth_blockNumber on the selected chain default_endpoint = "https://api.blockvectra.com/v1/robinhood_mainnet" rpc_url = f"{default_endpoint.rsplit('/', 1)[0]}/{selected['chain']}" rpc_response = requests.post( rpc_url, headers={ "Content-Type": "application/json", "x-api-key": api_key, "x-bv-meter": "1", }, json={"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []}, ).json() print("Response:", rpc_response) ``` Uma chamada bem-sucedida retorna um objeto de resposta JSON-RPC padrão: ```json { "jsonrpc": "2.0", "id": 1, "result": "0x45a27f1" } ``` Para inspecionar as tarifas de CU por requisição e as unidades de saldo restantes nos cabeçalhos de resposta, inclua `x-bv-meter: 1`. Para o comportamento dos cabeçalhos e casos de erro, consulte [Cabeçalhos de resposta de cobrança e saldo](https://docs.blockvectra.com/en/guides/billing-rules/#http-status-codes-and-billing-rules). ## Próximos passos * [Navegue pelo diretório de conjuntos de dados](https://blockvectra.com/en/data/) para ver todos os conjuntos de dados indexados pela BlockVectra. * [Veja o plano gratuito e os preços](https://blockvectra.com/en/pricing/#free) para verificar o que sua conta inclui. * [Siga o guia de cadastro programático](https://docs.blockvectra.com/en/guides/programmatic-signup/) para se cadastrar e criar uma API key com uma assinatura de carteira, ou [entre no console](https://console.blockvectra.com/login/?next=%2Fkeys%2F) para criar uma chave.