# RPC blockchain y MCP de documentación para agentes de IA

> Source: https://docs.blockvectra.com/es/guides/ai-agents/

Comience con el [endpoint MCP de documentación](https://docs.blockvectra.com/mcp) sin clave para descubrir métodos RPC blockchain, conjuntos de datos de la Data API, precios y documentación. Los agentes de IA son usuarios de pleno derecho: los desarrolladores y agentes de IA utilizan las mismas APIs, reglas, límites y precios.

1. **Descubrir**: utilice el MCP de documentación, `llms.txt`, OpenAPI y JSON público para elegir una cadena y un método. Las llamadas RPC sin clave se limitan a los `public.methods` de la cadena.
2. **Abrir una cuenta por HTTP**: siga el [registro programático](https://docs.blockvectra.com/en/guides/programmatic-signup/) para iniciar sesión con una firma de billetera y crear una API key. `how_to_get_api_key` de MCP devuelve instrucciones para este flujo HTTP independiente.
3. **Llamar a APIs de datos**: mantenga la clave en `BLOCKVECTRA_API_KEY` y utilícela para solicitudes RPC autenticadas o de Data API. Para las herramientas MCP con clave, configure el encabezado `x-api-key` del cliente; las operaciones permitidas de cada herramienta se enumeran a continuación.

## 1. Contexto y especificaciones legibles por máquinas

BlockVectra publica archivos destinados a agentes LLM y herramientas de desarrollo:

### Índices llms.txt

Siguiendo la convención de [llmstxt.org](https://llmstxt.org), estos archivos ofrecen a los agentes un resumen estructurado del sitio y sus endpoints:

* **Índice del sitio principal**: [llms.txt del sitio principal](https://blockvectra.com/llms.txt) — resumen del sitio principal, cadenas compatibles, precios y APIs públicas.
* **Índice de documentación**: [llms.txt de documentación](https://docs.blockvectra.com/llms.txt) — catálogo de todas las páginas de documentación con su título y descripción.

### Archivo de documentación completa (`llms-full.txt`)

* **Documentación completa**: [llms-full.txt](https://docs.blockvectra.com/llms-full.txt) — el texto completo de todas las páginas de documentación en inglés en un único archivo Markdown de texto plano, adecuado para cargarlo en el prompt de sistema de un agente o incorporarlo a un pipeline de generación aumentada por recuperación (RAG).

### Especificaciones OpenAPI 3.1 descargables

El sitio de documentación ofrece archivos YAML OpenAPI 3.1 que pueden importarse directamente a frameworks de agentes, generadores de herramientas o clientes API:

* **Especificación de la API JSON-RPC**: [/openapi/json-rpc.yaml](https://docs.blockvectra.com/openapi/json-rpc.yaml) — métodos compatibles, política de métodos por cadena, respuestas de error y medición de Compute Units.
* **Especificación de la Data API**: [/openapi/data.yaml](https://docs.blockvectra.com/openapi/data.yaml) — definiciones de endpoints REST para bloques, transacciones, transferencias, saldos, tenedores y conjuntos de datos relacionados indexados.
* **Especificación de la Push API**: [/openapi/push.yaml](https://docs.blockvectra.com/openapi/push.yaml) — gestión HTTP de suscripciones, direcciones de billeteras supervisadas, eventos de webhook, firmas y replay.

Para la actividad de direcciones de billeteras, siga la [guía de la API de Webhooks blockchain](https://docs.blockvectra.com/es/guides/webhook-push/). Para avisos de pagos USDT / USDC ERC-20, utilice el [ejemplo de receptor de pagos](https://docs.blockvectra.com/es/guides/stablecoin-payments/#receive-payments-with-webhooks). Los desarrolladores y agentes de IA crean y gestionan suscripciones mediante la Push API HTTP con `x-api-key`; el MCP de documentación permite descubrir y leer estas guías.

Para conocer las versiones de rutas, las reglas de compatibilidad con versiones anteriores y las recomendaciones para agentes y autores de SDKs, consulte [Versiones y compatibilidad de la API](https://docs.blockvectra.com/en/api/versioning/). Para recetas listas para utilizar con frameworks populares (ElizaOS, viem, wagmi, Coinbase AgentKit), consulte [Recetas para frameworks de agentes](https://docs.blockvectra.com/en/guides/agent-frameworks/).

### Servidor Model Context Protocol (MCP)

BlockVectra ofrece un servidor MCP sin estado y sin clave mediante Streamable HTTP:

* **Endpoint**: [Endpoint MCP](https://docs.blockvectra.com/mcp) (HTTP POST que recibe JSON-RPC 2.0; GET devuelve 405)
* **Transporte**: MCP Streamable HTTP (sin estado, no requiere API key)

#### Herramientas disponibles

1. `read_doc(path, lang?)`: devuelve el contenido Markdown original de cualquier página de documentación desde `/md/{lang}/{path}.md`. Acepta rutas relativas internas (p. ej., `quickstart`, `guides/ai-agents`, `api/json-rpc`, `chains`).
2. `search_docs(query, lang?, limit?)`: busca páginas de documentación por títulos, rutas y resúmenes.
3. `list_chains()`: lee redes blockchain compatibles, parámetros estáticos y políticas de métodos de `GET /v1/chains`.
4. `get_status()`: lee la disponibilidad actual del servicio, el estado de las redes, las últimas alturas de bloques y el retraso de sincronización de `GET /v1/status`.
5. `get_pricing()`: lee los pesos de Compute Units (CU), los parámetros del plan gratuito y los límites predeterminados de las claves de `GET /v1/plans`.
6. `estimate_usage(lines?, method?, calls_per_day?)`: estima Compute Units (CU), el coste bruto de tarifa y el coste neto tras deducir la cuota gratuita del ciclo para uno o varios métodos (admite varias líneas `lines: [{method, calls_per_day}]` o un único `method` y `calls_per_day`). También informa de los límites de tasa por clave de `key_defaults` y sugiere el número de API keys necesarias cuando el tráfico supera los límites de una sola clave.
7. `how_to_get_api_key(lang?)`: devuelve los pasos para obtener una API key y los formatos de autenticación de solicitudes para JSON-RPC y Data API.
8. `get_method_info(method, chain?)`: devuelve la disponibilidad por cadena, el peso de Compute Units (CU), el precio por millón de llamadas y el enlace a la documentación de un método. La disponibilidad JSON-RPC sigue `methods.allow` y `deny` de `GET /v1/chains`; la cobertura de conjuntos de datos de la Data API sigue `data_features` de `GET /v1/status`, con `data: true` en el catálogo de cadenas.
9. `explain_error(reason?, code?, http_status?)`: busca explicaciones de errores, implicaciones de facturación, posibilidad de reintento y acciones de recuperación en el catálogo de errores.
10. `list_docs(lang?)`: enumera todas las páginas de documentación con rutas relativas y títulos del índice de documentación.
11. `rpc_call(chain, method, params?)`: ejecuta una llamada JSON-RPC 2.0 de solo lectura en una cadena compatible con su API key (`readOnlyHint: true`). Los métodos de escritura (como `eth_sendRawTransaction`) se rechazan; utilice `send_raw_transaction` en su lugar. Requiere el encabezado `x-api-key` en la configuración del cliente MCP para acceso completo, o utiliza el endpoint público sin clave si está disponible.
12. `data_api_get(chain, path, query?)`: realiza una solicitud GET a la Data API para una cadena y ruta compatibles con su API key (`readOnlyHint: true`). Requiere el encabezado `x-api-key` en la configuración del cliente MCP.
13. `get_account()`: consulta el saldo de la cuenta, Compute Units (CU), los límites de tasa y los parámetros de la clave de `GET /v1/account` con su API key (`readOnlyHint: true`). Requiere el encabezado `x-api-key` en la configuración del cliente MCP.
14. `get_deposit_address()`: consulta la dirección de depósito on-chain dedicada, las redes abiertas y los tokens de `GET /v1/topup/deposit-address` con su API key (`readOnlyHint: true`). Transfiera únicamente a las redes y tokens enumerados. Requiere el encabezado `x-api-key` en la configuración del cliente MCP.
15. `send_raw_transaction(chain, raw_tx)`: transmite una transacción sin procesar firmada a una cadena compatible mediante `eth_sendRawTransaction` (`destructiveHint: true`). Requiere el encabezado `x-api-key` en la configuración del cliente MCP para acceso completo, o utiliza el endpoint público sin clave si la cadena lo permite.

#### Herramientas con clave

Las herramientas con clave requieren una API key para ejecutar consultas on-chain, transacciones, solicitudes de Data API u operaciones de cuenta.

**Seguridad de la API key**:

* **Leer exclusivamente de los encabezados**: La API key se lee únicamente de los encabezados de solicitud HTTP del cliente MCP (`x-api-key: rgw_...` o `Authorization: Bearer rgw_...`).
* **Nunca incluir claves en el chat**: Nunca pase API keys ni claves privadas en argumentos de herramientas ni las pegue en el chat. Los argumentos de herramientas y el historial del chat entran en los logs y contextos de la conversación; pasar claves en argumentos se rechazará.

Si se llaman sin un encabezado de API key, estas herramientas devuelven `isError: true` y remiten al agente a `how_to_get_api_key` y a la guía de incorporación programática.

### Conectar desde clientes MCP

Puede conectarse al servidor MCP de documentación de BlockVectra en `https://docs.blockvectra.com/mcp` desde entornos y frameworks de desarrollo habituales.

Comience sin una API key. Conéctese al endpoint MCP, llame a list\_chains y después lea quickstart con read\_doc. Añada una API key en los encabezados HTTP de su cliente cuando necesite herramientas de Data API o de cuenta. El acceso RPC sin clave sigue la política de métodos públicos de cada cadena.

El encabezado `x-api-key` es opcional. Sin una API key, los clientes pueden utilizar todas las herramientas de documentación de solo lectura (`read_doc`, `search_docs`, `list_docs`), el descubrimiento de cadenas (`list_chains`), el estado actual (`get_status`), la estimación de precios (`get_pricing`, `estimate_usage`), las explicaciones de errores (`explain_error`) y los métodos permitidos en endpoints públicos. Al utilizar herramientas con clave (`rpc_call` en métodos restringidos, `send_raw_transaction`, `data_api_get`, `get_account` y `get_deposit_address`), configure el encabezado `x-api-key` con su API key.

#### Claude Code

Conéctese al servidor MCP mediante la CLI:

```bash
claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp
```

Para incluir una API key opcional para herramientas autenticadas, pase la opción `--header` (o `-H`):

```bash
claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp \
  --header "x-api-key: YOUR_API_KEY"
```

Documentación oficial: [Documentación MCP de Claude Code](https://code.claude.com/docs/en/mcp).

#### Cursor

Añada el servidor a la configuración MCP de Cursor:

```json
{
  "mcpServers": {
    "blockvectra": {
      "url": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

Cursor también admite la instalación con un clic mediante enlaces profundos utilizando la configuración codificada en base64 `eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9` (que representa `{"url":"https://docs.blockvectra.com/mcp"}`):

```text
cursor://anysphere.cursor-deeplink/mcp/install?name=blockvectra&config=eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9
```

Cuando necesite herramientas autenticadas (Data API o gestión de cuenta), añada el objeto `headers` con su API key:

```json
{
  "mcpServers": {
    "blockvectra": {
      "url": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

Documentación oficial: [Documentación MCP de Cursor](https://cursor.com/docs/context/mcp) y [Enlaces de instalación de Cursor](https://cursor.com/docs/context/mcp/install-links).

#### VS Code

En VS Code, configure el servidor en `.vscode/mcp.json` bajo la clave de nivel superior `servers` con `type: "http"`:

```json
{
  "servers": {
    "blockvectra": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

Cuando necesite herramientas autenticadas, añada el objeto `headers`:

```json
{
  "servers": {
    "blockvectra": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

Al almacenar credenciales sensibles, VS Code permite referenciar variables de entrada o archivos de entorno en lugar de escribir las claves directamente. También puede añadir servidores con la acción `MCP: Add Server` de la paleta de comandos.

Documentación oficial: [Documentación de servidores MCP de VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) y [Referencia de configuración MCP de VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

#### Codex

Añada el servidor mediante la CLI de OpenAI Codex:

```bash
codex mcp add blockvectra --url https://docs.blockvectra.com/mcp
```

En `config.toml`, configure la URL del servidor:

```toml
[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
```

Cuando necesite herramientas autenticadas, configure los encabezados de solicitud en `config.toml`:

```toml
[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
http_headers = { "x-api-key" = "YOUR_API_KEY" }
```

Como alternativa, asocie el encabezado a una variable de entorno:

```toml
[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
env_http_headers = { "x-api-key" = "BLOCKVECTRA_API_KEY" }
```

Documentación oficial: [Documentación MCP de la CLI de OpenAI Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

#### Gemini CLI

En la configuración de Gemini CLI, añada el servidor bajo `mcpServers` utilizando `httpUrl` para Streamable HTTP:

```json
{
  "mcpServers": {
    "blockvectra": {
      "httpUrl": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

Cuando necesite herramientas autenticadas, añada el objeto `headers` con su API key:

```json
{
  "mcpServers": {
    "blockvectra": {
      "httpUrl": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

Documentación oficial: [Documentación de servidores MCP de Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md).

#### OpenAI Responses API

Al llamar a OpenAI Responses API, pase el servidor MCP en el array `tools` con `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": "<model>",
    "tools": [{
      "type": "mcp",
      "server_label": "blockvectra",
      "server_url": "https://docs.blockvectra.com/mcp",
      "require_approval": "never"
    }],
    "input": "..."
  }'
```

Cuando necesite herramientas autenticadas, incluya el campo `headers` en la definición de la herramienta:

```json
{
  "type": "mcp",
  "server_label": "blockvectra",
  "server_url": "https://docs.blockvectra.com/mcp",
  "headers": { "x-api-key": "YOUR_API_KEY" },
  "require_approval": "never"
}
```

Documentación oficial: [Guía de herramientas MCP de OpenAI](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) y [Referencia de OpenAI Responses API](https://developers.openai.com/api/reference/resources/responses/methods/create).

#### Windsurf

En Windsurf, configure el servidor bajo `mcpServers` utilizando el campo `serverUrl`:

```json
{
  "mcpServers": {
    "blockvectra": {
      "serverUrl": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

Cuando necesite herramientas autenticadas, añada el objeto `headers` con su API key:

```json
{
  "mcpServers": {
    "blockvectra": {
      "serverUrl": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

Windsurf también admite referencias a variables de entorno, como `"x-api-key": "${env:BLOCKVECTRA_API_KEY}"`.

Documentación oficial: [Documentación MCP de Windsurf](https://docs.devin.ai/desktop/cascade/mcp).

#### Claude Desktop and claude.ai

Los conectores personalizados se configuran mediante la interfaz de usuario:

* **claude.ai**: Vaya a **Personalizar** > **Conectores**, haga clic en **+ Añadir**, seleccione **Añadir conector personalizado** e introduzca la URL:
  ```text
  https://docs.blockvectra.com/mcp
  ```
* **Claude Desktop**: Abra el menú de configuración de la cuenta y configure los conectores personalizados mediante la interfaz de conectores.

Conectarse a la URL permite a Claude buscar guías, leer documentación Markdown, consultar las cadenas compatibles, comprobar el estado de las redes y calcular estimaciones de precios sin credenciales.

Documentación oficial: [Guía de conectores personalizados de Claude](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).

## 2. Endpoints JSON públicos (no requieren clave)

Un agente puede consultar las cadenas disponibles, el estado actual y los parámetros de planes antes de enviar cualquier solicitud medida. Ninguno de estos endpoints necesita una API key:

* `GET /v1/status` y `GET /v1/chains` no requieren autenticación y no se facturan.
* `GET /v1/plans` es público y no requiere autenticación.

Los tres envían `Access-Control-Allow-Origin: *`.

### Estado del servicio (`GET /v1/status`)

Devuelve la disponibilidad del servicio y el estado de sincronización de cada cadena pública:

```bash
curl -s "https://api.blockvectra.com/v1/status"
```

Campos de respuesta:

* `checked_at`: cuándo se generó la instantánea (RFC 3339 / ISO 8601 UTC).
* `gateway.status`: estado de funcionamiento del servicio. `ok` significa que el servicio está listo; `degraded` significa que las solicitudes de pago se rechazan hasta que se recupere. Este valor es independiente del estado del nodo de cualquier cadena.
* `chains[]`: las cadenas ofrecidas al público:
  * `chain`: slug de la cadena (p. ej., `robinhood_mainnet`).
  * `name`: nombre de visualización legible por humanos.
  * `chain_id`: ID de cadena EIP-155 (entero decimal).
  * `jsonrpc`: si se ofrece JSON-RPC.
  * `data`: si se ofrece la Data API.
  * `data_features`: capacidades de Data API disponibles para esta cadena (un array vacío cuando `data` es `false`).
  * `data_status`: estado de funcionamiento de la Data API (`ok`, `syncing` o `unavailable`; presente solo cuando `data` es `true`).
  * `status`: estado del nodo de la cadena (`ok` o `unavailable`).
  * `head`: información del último bloque — `block` (última altura de bloque), `time` (marca de tiempo del bloque) y `lag_seconds` (cuánto se retrasa la hora del bloque respecto de la hora actual) — o `null` si se desconoce.

Ejemplo de respuesta:

```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 de cadena (`GET /v1/chains`)

Devuelve los parámetros estáticos y la política de métodos de cada cadena pública:

```bash
curl -s "https://api.blockvectra.com/v1/chains"
```

Campos de respuesta:

* `chains[]`: cadenas públicas y sus parámetros estáticos:
  * `chain`: slug de la cadena.
  * `name`: nombre de visualización legible por humanos.
  * `chain_id`: ID de cadena EIP-155.
  * `jsonrpc`: si se ofrece JSON-RPC.
  * `data`: si se ofrece la Data API.
  * `ws`: si se admiten conexiones WebSocket.
  * `subscriptions`: tipos de suscripciones WebSocket compatibles (p. ej., `newHeads`, `logs`).
  * `methods`: política de métodos:
    * `allow`: nombres de métodos permitidos (p. ej., `eth_call`, `debug_traceTransaction`).
    * `deny`: métodos denegados o patrones de comodín de prefijo (p. ej., `eth_newFilter`). Los métodos denegados tienen prioridad sobre los permitidos.
  * `max_logs_block_range`: amplitud máxima de bloques permitida en una solicitud `eth_getLogs`.
  * `state_window_blocks`: ventana de estado histórico en bloques; `null` cuando está disponible el historial completo.
  * `info`: datos públicos de extensión por cadena (reservado; actualmente un objeto vacío `{}`).
  * `public`: configuración del endpoint público sin autenticación (o `null`):
    * `url`: URL base para solicitudes públicas.
    * `methods`: métodos permitidos en el endpoint público.
    * `rate_limit`: límites de tasa (`per_ip_rps`, `burst`, `batch_max`).
    * `history_blocks`: historial de bloques accesible en el endpoint público.
    * `send_raw_rate_limit`: límites de tasa para transmitir transacciones mediante `eth_sendRawTransaction`.

Ejemplo de respuesta:

```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
        }
      }
    }
  ]
}
```

### Planes y pesos de métodos (`GET /v1/plans`)

Los parámetros de planes se ofrecen en `GET https://console-api.blockvectra.com/v1/plans`. Un agente puede consultar este endpoint en tiempo de ejecución para leer los límites activos del plan gratuito y el peso de Compute Units (CU) de cada método:

* `free`: parámetros del plan gratuito — `signup_units` (créditos de registro, en unidades), `monthly_units` (nivel de reposición del ciclo, en unidades), `window_days` (duración del ciclo de uso en días) y `max_calls_per_sec` (límite de llamadas por segundo del plan gratuito).
* `pricing`: parámetros del plan de pago — `units_per_usd` (unidades por 1 USD), `cu_per_unit` (CU por unidad) y `min_topup_usd` (recarga mínima en USD).
* `method_weights`: pesos CU por llamada, cada uno `{ "method": string, "cu_weight": number }`. `method` especifica el nombre o patrón del método JSON-RPC, los pesos predeterminados de métodos no enumerados o una operación Data API como `data.<op>`. Los pesos son por método y no se dividen por cadena.

## 3. Autenticación y seguridad de claves

Los agentes que realizan llamadas RPC deben seguir estas reglas:

* **Autenticación**: pase la API key de una de tres formas. En la ruta: `POST /v1/{chain}/{api_key}` — esta forma utiliza solo la clave de la ruta e ignora ambos encabezados. En el encabezado `x-api-key`: `POST /v1/{chain}` con `x-api-key: $BLOCKVECTRA_API_KEY`. En el encabezado `Authorization`: `POST /v1/{chain}` con `Authorization: Bearer $BLOCKVECTRA_API_KEY`. Cuando ambos encabezados están presentes, un `x-api-key` no vacío tiene prioridad; Bearer se utiliza solo si `x-api-key` falta o está vacío. La misma clave funciona en todas las cadenas compatibles y en la Data API (que acepta la clave solo en el encabezado `x-api-key`).
* **Seguridad de claves**: mantenga las API keys en variables de entorno del servidor (por ejemplo `BLOCKVECTRA_API_KEY`) o en un gestor de secretos. Nunca inserte una clave en código de navegador ni en ningún bundle del cliente. Los endpoints devuelven `Access-Control-Allow-Origin: *`, pero están destinados a servicios backend en lugar del navegador.
* **Medición y mejoras**: el uso se mide en Compute Units (CU): cada método consume CU según su peso, y el saldo, los buckets CU y los límites de tasa del plan gratuito se comparten entre todas las cadenas. Tras una recarga de pago, deja de aplicarse el límite de llamadas por segundo del plan gratuito; cada clave mantiene un límite de tasa CU y una capacidad de ráfaga. Los créditos gratuitos no utilizados permanecen en sus créditos y siguen disponibles. Consulte la [página de precios](https://blockvectra.com/es/pricing/) para conocer los detalles.

> **No API key yet?**
>
> Si tiene una billetera Ethereum: siga la [guía de registro programático](https://docs.blockvectra.com/en/guides/programmatic-signup/) para registrarse y crear una API key mediante una firma de billetera Ethereum sin navegador. La identidad de un agente es su billetera: si pierde un token de sesión o una clave, [vuelva a autenticarse con la misma billetera para recuperarlo](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key). Si no tiene una billetera: pida al usuario que inicie sesión en [console.blockvectra.com](https://console.blockvectra.com/login/?next=%2Fkeys%2F), cree una clave y la establezca como variable de entorno `BLOCKVECTRA_API_KEY`. No pida al usuario que pegue la clave en el chat.


### Consultar el saldo (`GET /v1/account`)

Un agente puede comprobar directamente el saldo actual de su clave, los límites CU y los parámetros de la clave sin consumir Compute Units (CU). Para conocer el formato de solicitud, los límites de tasa y las definiciones completas de campos de respuesta, consulte [Consultar el saldo: GET /v1/account](https://docs.blockvectra.com/en/guides/billing-rules/#query-balance-get-v1account).

## 4. Flujo de selección de cadenas para agentes

Antes de realizar llamadas, un agente puede seguir estos pasos:

1. **Comprobar la cadena y su política de métodos**: llame a `GET /v1/chains`, confirme que la cadena de destino exista y tenga `jsonrpc: true`, y que el método que prevé llamar esté permitido por `methods.allow` y no denegado por `methods.deny` (deny tiene prioridad).
2. **Comprobar el estado actual**: llame a `GET /v1/status` y confirme que `gateway.status` sea `ok` y que el `status` de la cadena de destino sea `ok`; utilice `head.lag_seconds` para decidir si los datos de la cadena son lo bastante recientes para su caso de uso. Cuando el nodo de una cadena no está sincronizado, todos los métodos salvo `eth_chainId` devuelven el error JSON-RPC `-32010` (HTTP 200, no facturado), por lo que el agente puede esperar y reintentar o elegir otra cadena.
3. **Enviar la solicitud**: `POST /v1/{chain}` con el encabezado `x-api-key` y un body JSON-RPC estándar.

## 5. Ejemplo mínimo funcional

El ejemplo siguiente lee `/v1/chains` para elegir una cadena que permita `eth_blockNumber`, comprueba `/v1/status` y después llama una vez a `eth_blockNumber`.

**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)
```


Una llamada exitosa devuelve un objeto de respuesta JSON-RPC estándar:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x45a27f1"
}
```

Para consultar los cargos CU por solicitud y las unidades de saldo restantes en los encabezados de respuesta, incluya `x-bv-meter: 1`. Para conocer el comportamiento de los encabezados y los casos de error, consulte [Encabezados de respuesta de cargos y saldo](https://docs.blockvectra.com/en/guides/billing-rules/#http-status-codes-and-billing-rules).

## Próximos pasos

* [Explore el directorio de conjuntos de datos](https://blockvectra.com/es/data/) para ver todos los conjuntos de datos indexados por BlockVectra.
* [Consulte el plan gratuito y los precios](https://blockvectra.com/es/pricing/#free) para comprobar lo que incluye su cuenta.
* [Siga la guía de registro programático](https://docs.blockvectra.com/en/guides/programmatic-signup/) para registrarse y crear una API key con una firma de billetera, o [inicie sesión en la consola](https://console.blockvectra.com/login/?next=%2Fkeys%2F) para crear una clave.