# Pague RPC con USDC / USDT / USDG: recarga programática para agentes de IA

> Source: https://docs.blockvectra.com/es/guides/agent-topup/

Los desarrolladores y Agentes de IA pueden recargar una cuenta de RPC y Data API a través de HTTP: verifique las redes y tokens habilitados, use una API key existente para obtener la dirección de depósito EVM de la cuenta, y luego sondee el estado de la acreditación después de transferir fondos. Antes de transferir fondos, consulte la [página de precios](https://blockvectra.com/en/pricing/) y [estime los costos de RPC y Data API a partir de los pesos de CU](https://docs.blockvectra.com/en/guides/reading-cu-pricing/).

## Obtenga su dirección de depósito en Billing

Inicie sesión, [abra Billing para obtener su dirección de depósito](https://console.blockvectra.com/login/?next=%2Fbilling%2F), y use la dirección de depósito y los detalles del token mostrados para su cuenta. Verifique las redes actuales, los tokens y el depósito mínimo en [GET /v1/topup/status](https://api.blockvectra.com/v1/topup/status) antes de transferir fondos.

> **Seguridad de la API key y requisito de uso del lado del servidor**
>
> El encabezado `x-api-key` **solo se puede utilizar en llamadas desde entornos del lado del servidor**. Nunca llame a los endpoints de recarga desde código que se ejecute en el navegador del cliente, y nunca exponga su API key en paquetes de frontend, repositorios públicos o conversaciones de chat con IA.


## Requisitos previos

* **API key existente**: Llamar a endpoints autenticados de recarga requiere una API key RPC activa de BlockVectra. Si aún no tiene una API key, siga la [Guía de registro programático](https://docs.blockvectra.com/en/guides/programmatic-signup/) para registrarse y crear una clave mediante una firma de billetera Ethereum, o cree una en la [consola](https://console.blockvectra.com/login/?next=%2Fkeys%2F).
* **Activos on-chain**: El entorno de su agente o la billetera de financiamiento debe tener USDC / USDT / USDG listadas por `GET /v1/topup/status` en una red compatible, junto con suficientes tokens de gas nativos para difundir transacciones.
* **Variable de entorno**: Guarde su clave en la variable de entorno `BLOCKVECTRA_API_KEY`.

Los endpoints de recarga autenticados aceptan directamente el encabezado `x-api-key` utilizando la misma API key empleada para las llamadas RPC. No se requiere sesión de navegador.

## Flujo de trabajo de recarga en cuatro pasos

Una vez acreditada la primera recarga de pago, se detienen las recargas de ciclos gratuitos, los créditos gratuitos no utilizados siguen disponibles y se elimina el límite de tasa de llamadas a nivel de cuenta; los límites de tasa por clave permanecen sin cambios. Consulte las [reglas de precios](https://blockvectra.com/en/pricing/) y las [reglas del plan gratuito](https://blockvectra.com/en/free/#rules); consulte los límites actuales y la recarga mínima en [GET /v1/plans](https://console-api.blockvectra.com/v1/plans) (`free`, `key_defaults` y `pricing.min_topup_usd`).

Los endpoints de recarga (estado, dirección de depósito y depósitos) utilizan el host de API de producción:

```
https://api.blockvectra.com
```

Los límites del plan y los parámetros de precios son proporcionados por la Console API en `https://console-api.blockvectra.com` (como [GET https://console-api.blockvectra.com/v1/plans](https://console-api.blockvectra.com/v1/plans)).

### 1. Verificar la disponibilidad (GET /v1/topup/status)

Antes de iniciar una transferencia, verifique el estado global de recarga, consulte qué redes y tokens están habilitados actualmente y lea el umbral de depósito mínimo activo. Este endpoint es público y no requiere credenciales.

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

Ejemplo de respuesta (redes y tokens seleccionados):

```json
{
  "enabled": true,
  "networks": [
    {
      "network": "base_mainnet",
      "chain_id": 8453,
      "token": "USDC",
      "enabled": true
    },
    {
      "network": "bsc_mainnet",
      "chain_id": 56,
      "token": "USDT",
      "enabled": true
    },
    {
      "network": "bsc_mainnet",
      "chain_id": 56,
      "token": "USDC",
      "enabled": true
    }
  ]
}
```

* `enabled`: Interruptor global. Si es `false`, la recarga está cerrada en todas las redes.
* `networks`: Estado habilitado por red y token. Cuando `enabled` sea `false` para una red o token, **no transfiera fondos en esa red**.
* `min_deposit_usd`: Monto mínimo de depósito global en USD formateado a 6 decimales. El umbral mínimo de depósito es dinámico: consulte siempre `min_deposit_usd` devuelto en tiempo real por `GET https://api.blockvectra.com/v1/topup/status`.

Para leer directamente el `min_deposit_usd` activo:

```bash
curl -s https://api.blockvectra.com/v1/topup/status | jq -r .min_deposit_usd
```

### 2. Obtener dirección de depósito y parámetros (GET /v1/topup/deposit-address)

Obtenga o asigne la dirección de depósito EVM del cliente e inspeccione las redes compatibles y los contratos de tokens. Este endpoint requiere autenticación con `x-api-key` y solo debe llamarse desde entornos del lado del servidor.

```bash
curl -s \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  https://api.blockvectra.com/v1/topup/deposit-address
```

Ejemplo de respuesta (redes y tokens seleccionados):

```json
{
  "address": "0x<your-dedicated-deposit-address>",
  "deposits_url": "https://api.blockvectra.com/v1/topup/deposits",
  "networks": [
    {
      "chain": "base_mainnet",
      "chain_id": 8453,
      "name": "Base",
      "typical_credit_seconds": 30,
      "explorer_tx_url": "https://basescan.org/tx/{tx_hash}",
      "tokens": [
        {
          "symbol": "USDC",
          "contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "decimals": 6,
          "min_amount_raw": "1000000"
        }
      ]
    },
    {
      "chain": "bsc_mainnet",
      "chain_id": 56,
      "name": "BNB Smart Chain",
      "typical_credit_seconds": 60,
      "explorer_tx_url": "https://bscscan.com/tx/{tx_hash}",
      "tokens": [
        {
          "symbol": "USDT",
          "contract": "0x55d398326f99059fF775485246999027B3197955",
          "decimals": 18,
          "min_amount_raw": "1000000000000000000"
        },
        {
          "symbol": "USDC",
          "contract": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
          "decimals": 18,
          "min_amount_raw": "1000000000000000000"
        }
      ]
    }
  ]
}
```

* `address`: Dirección de depósito EVM con suma de comprobación EIP-55 dedicada a su cuenta.
* `deposits_url`: URL para consultar los registros de depósitos del cliente.
* `networks`: Lista de redes EVM abiertas. Las redes cerradas se omiten. Incluye el slug de la cadena `chain`, el chain ID de EVM `chain_id`, el nombre para mostrar `name`, la latencia típica de acreditación en segundos tras la inclusión en un bloque `typical_credit_seconds` y la plantilla de URL de transacción en el explorador de bloques `explorer_tx_url`.
* `tokens`: Tokens en esta red, incluido el símbolo del token `symbol` (USDC / USDT / USDG), la dirección del contrato `contract`, los decimales del token `decimals` y el monto mínimo de depósito en unidades atómicas sin procesar `min_amount_raw` (consulte el valor real devuelto por el endpoint; no asuma un monto escalado).

> **Decimales del token y conversión de montos**
>
> El mismo token puede tener diferentes decimales en diferentes cadenas (por ejemplo, USDT y USDC en BSC tienen 18 decimales, mientras que USDC en Base tiene 6 decimales). El cálculo del monto debe utilizar los `decimals` devueltos para esa red específica en lugar de codificar de forma fija un único valor decimal del token.


#### Respuestas de error

Los endpoints de recarga autenticados (`/v1/topup/deposit-address` y `/v1/topup/deposits`) devuelven estructuras de error JSON estándar:

* **HTTP 401 (Fallo de autenticación)**: Se devuelve cuando falta el encabezado `x-api-key` (`missing_api_key`) o la clave no es válida, ha sido revocada o está deshabilitada (`invalid_api_key`):

```json
{
  "error": {
    "code": "missing_api_key",
    "message": "missing API key: send it in the x-api-key header",
    "data": {
      "reason": "missing_api_key",
      "docs_url": "https://docs.blockvectra.com/en/errors/#missing_api_key",
      "retryable": false
    }
  }
}
```

* **HTTP 409 (Recarga deshabilitada)**: Se devuelve cuando la recarga está cerrada globalmente o en todas las redes (`topup_disabled`):

```json
{
  "error": {
    "code": "topup_disabled",
    "data": {
      "reason": "topup_disabled",
      "docs_url": "https://docs.blockvectra.com/en/errors/#topup_disabled",
      "retryable": false
    }
  }
}
```

Para consultar la lista completa de códigos de error, consulte la [Referencia de errores](https://docs.blockvectra.com/en/errors/).

### 3. Transmitir la transferencia on-chain

Utilizando la billetera o el script de su agente, envíe una transacción ERC-20 `transfer` a la `address` de depósito obtenida en el Paso 2.

Requisitos de transferencia:

* Envíe únicamente tokens y contratos listados en el array `tokens` para esa red.
* Asegúrese de que el monto de la transferencia sea mayor o igual a `min_amount_raw` (sujeto al valor real devuelto por `GET /v1/topup/deposit-address`, o `min_deposit_usd` devuelto por `GET /v1/topup/status`), formateado según los `decimals` del token en esa red.
* Las transferencias enviadas a cadenas no admitidas o con tokens incorrectos no se pueden acreditar automáticamente; verifique la red y el contrato del token antes de la transmisión.
* Registre el hash de la transacción on-chain (`tx_hash`) una vez enviada.

### 4. Consultar registros de depósitos y verificar la acreditación (GET /v1/topup/deposits)

Después de que la transacción se incluya en un bloque, consulte el historial de transferencias de depósito para rastrear el estado de la acreditación. Este endpoint requiere `x-api-key` y es solo para el lado del servidor.

#### Parámetros de consulta

* `limit`: Número de registros de depósito a devolver por página. El valor predeterminado es `20`, el rango válido es de `1` a `100`.
* `before`: Parámetro de paginación por cursor basado en `deposit_id`. Pase el valor `next_before` de la respuesta de la página anterior para obtener la página siguiente de registros anteriores.
* `tx_hash`: Hash de transacción hexadecimal opcional de 64 caracteres con prefijo 0x para filtrar por una transferencia específica.

Filtre por hash de transacción (`tx_hash`) para inspeccionar su transferencia específica:

```bash
curl -s \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  "https://api.blockvectra.com/v1/topup/deposits?tx_hash=0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
```

Ejemplo de respuesta:

```json
{
  "items": [
    {
      "deposit_id": 42,
      "chain": "base_mainnet",
      "chain_id": 8453,
      "token": "USDC",
      "contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "25.000000",
      "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "tx_log_ordinal": 0,
      "block_number": 123456789,
      "external_ref": "eip155:8453:0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890:0",
      "status": "credited",
      "reason": null,
      "credited_units": 250000,
      "credited_cu": 250000000,
      "detected_at": "2026-10-02T10:00:00Z"
    }
  ],
  "next_before": null
}
```

* `items`: Array de registros de depósitos que coinciden con los parámetros de consulta.
* `next_before`: ID de cursor para la página siguiente cuando existen más registros, o `null` si no hay registros anteriores. Combínelo con el parámetro de consulta `before` para paginación basada en cursor.

Valores de `status` del depósito:

* `processing`: Transferencia detectada on-chain, acreditación en curso.
* `credited`: Acreditado al saldo de la cuenta. `credited_units` y `credited_cu` indican los montos acreditados.
* `not_credited`: La transferencia no se puede acreditar. El campo `reason` indica la causa:
  * `below_minimum`: El monto del depósito es inferior al umbral mínimo.
  * `large_amount`: El monto del depósito excede el umbral y requiere revisión manual.
  * `other`: Otra excepción de acreditación.

Pautas de latencia de crédito y sondeo:

* **Tiempo de llegada y acreditación**: El tiempo de crédito se rige por `typical_credit_seconds` devuelto en el Paso 2.
* **Intervalo de sondeo**: Sondee a un intervalo recomendado de **cada 20–60 segundos**, no con mayor frecuencia, para evitar activar límites de tasa.

## Ejemplos de código

Los siguientes ejemplos demuestran cómo leer `BLOCKVECTRA_API_KEY` del entorno y consultar los endpoints de recarga en Node.js y Python.

### Node.js (fetch)

```javascript
import process from "node:process";

const apiKey = process.env.BLOCKVECTRA_API_KEY;
if (!apiKey) {
  throw new Error("Missing BLOCKVECTRA_API_KEY environment variable");
}

const BASE_URL = "https://api.blockvectra.com";

// 1. Check availability and read minimum deposit threshold
const statusRes = await fetch(`${BASE_URL}/v1/topup/status`);
const status = await statusRes.json();
if (!status.enabled) {
  throw new Error("Top-up is currently disabled");
}
const minDepositUsd = status.min_deposit_usd;
console.log("Minimum deposit (USD):", minDepositUsd);

// 2. Retrieve deposit address and open networks
const addressRes = await fetch(`${BASE_URL}/v1/topup/deposit-address`, {
  headers: { "x-api-key": apiKey },
});

if (addressRes.status === 401) {
  throw new Error("Missing or invalid API key (HTTP 401)");
}
if (addressRes.status === 409) {
  throw new Error("Top-up is disabled (topup_disabled)");
}
if (!addressRes.ok) {
  throw new Error(`Failed to retrieve deposit address: ${addressRes.status}`);
}

const depositData = await addressRes.json();
console.log("Deposit address:", depositData.address);
console.log("Open networks count:", depositData.networks.length);

// 3. Poll deposit status
async function checkDepositStatus(txHash) {
  const url = new URL(`${BASE_URL}/v1/topup/deposits`);
  url.searchParams.set("tx_hash", txHash);

  const res = await fetch(url, {
    headers: { "x-api-key": apiKey },
  });
  if (res.status === 401) {
    throw new Error("Missing or invalid API key (HTTP 401)");
  }
  if (!res.ok) {
    throw new Error(`Failed to query deposits: ${res.status}`);
  }
  return res.json();
}
```

### Python (requests)

```python
# pip install requests
import os
import requests

api_key = os.environ.get("BLOCKVECTRA_API_KEY")
if not api_key:
    raise ValueError("Missing BLOCKVECTRA_API_KEY environment variable")

base_url = "https://api.blockvectra.com"

# 1. Check availability and read minimum deposit threshold
resp = requests.get(f"{base_url}/v1/topup/status", timeout=10)
resp.raise_for_status()
status_data = resp.json()
if not status_data.get("enabled"):
    raise RuntimeError("Top-up is currently disabled")
min_deposit_usd = status_data.get("min_deposit_usd")
print("Minimum deposit (USD):", min_deposit_usd)

# 2. Retrieve deposit address
resp = requests.get(
    f"{base_url}/v1/topup/deposit-address",
    headers={"x-api-key": api_key},
    timeout=10,
)
if resp.status_code == 401:
    raise RuntimeError("Missing or invalid API key (HTTP 401)")
if resp.status_code == 409:
    raise RuntimeError("Top-up is disabled (topup_disabled)")
resp.raise_for_status()
deposit_data = resp.json()
print("Deposit address:", deposit_data["address"])

# 3. Poll deposit status
def check_deposit_status(tx_hash: str):
    resp = requests.get(
        f"{base_url}/v1/topup/deposits",
        headers={"x-api-key": api_key},
        params={"tx_hash": tx_hash},
        timeout=10,
    )
    if resp.status_code == 401:
        raise RuntimeError("Missing or invalid API key (HTTP 401)")
    resp.raise_for_status()
    return resp.json()
```

## Próximos pasos

* [Consultar saldo (`GET /v1/account`)](https://docs.blockvectra.com/en/guides/billing-rules/#query-balance-get-v1account) para verificar el saldo de su cuenta y las Compute Units (CU) restantes.
* [Reglas de facturación](https://docs.blockvectra.com/en/guides/billing-rules/) para revisar la medición de Compute Units (CU), los límites de tasa y los errores no facturados.
* [Guía del plan gratuito](https://docs.blockvectra.com/en/guides/free-plan/) para revisar los límites del nivel gratuito y las reglas de actualización.
* [Guía de registro programático](https://docs.blockvectra.com/en/guides/programmatic-signup/) para crear cuentas y aprovisionar API keys mediante firmas de billetera.