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

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 y estime los costos de RPC y Data API a partir de los pesos de CU.

Obtenga su dirección de depósito en Billing

Inicie sesión, abra Billing para obtener su dirección de depósito, 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 antes de transferir fondos.

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 para registrarse y crear una clave mediante una firma de billetera Ethereum, o cree una en la consola.
• 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 y las reglas del plan gratuito; consulte los límites actuales y la recarga mínima en GET /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).

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.

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

Ejemplo de respuesta (redes y tokens seleccionados):

{
  "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:

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.

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

Ejemplo de respuesta (redes y tokens seleccionados):

{
  "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).

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):

{
  "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):

{
  "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.

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:

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

Ejemplo de respuesta:

{
  "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)

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)

# 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) para verificar el saldo de su cuenta y las Compute Units (CU) restantes.
• Reglas de facturación para revisar la medición de Compute Units (CU), los límites de tasa y los errores no facturados.
• Guía del plan gratuito para revisar los límites del nivel gratuito y las reglas de actualización.
• Guía de registro programático para crear cuentas y aprovisionar API keys mediante firmas de billetera.