Pagar por RPC com USDC / USDT / USDG: recarga programática para agentes de IA

Desenvolvedores e agentes de IA podem recarregar uma conta RPC e Data API via HTTP: verifique redes e tokens disponíveis, use uma API key existente para obter o endereço de depósito EVM da conta e consulte o status do crédito após transferir os fundos. Antes de enviar fundos, consulte a página de preços e estime os custos de RPC e Data API pelos pesos de CU.

Obter seu endereço de depósito em Billing

Entre na conta, abra Billing para obter seu endereço de depósito e use o endereço de depósito e os detalhes de tokens exibidos para sua conta. Verifique as redes, os tokens e o depósito mínimo atuais em GET /v1/topup/status antes de transferir fundos.

Pré-requisitos

• API key existente: chamadas a endpoints de recarga autenticados exigem uma API key RPC BlockVectra ativa. Se ainda não tem uma API key, siga o guia de cadastro programático para se cadastrar e criar uma API key com uma assinatura de carteira Ethereum ou crie uma no Console.
• Ativos on-chain: o ambiente do agente ou a carteira que fornece fundos deve ter USDC / USDT / USDG listadas por GET /v1/topup/status em uma rede compatível, além de tokens nativos suficientes para gas para transmitir transações.
• Variável de ambiente: armazene sua API key na variável de ambiente BLOCKVECTRA_API_KEY.

Os endpoints de recarga autenticados aceitam diretamente o cabeçalho x-api-key com a mesma API key usada nas chamadas RPC. Não é necessária uma sessão de navegador.

Fluxo de recarga em quatro passos

Quando a primeira recarga paga é creditada, as renovações gratuitas por ciclo param, os créditos gratuitos não usados continuam disponíveis e o limite de chamadas por segundo da conta é removido; os limites por API key permanecem iguais. Consulte as regras de preços e as regras do plano gratuito; leia os limites atuais e a recarga mínima em GET /v1/plans (free, key_defaults e pricing.min_topup_usd).

Os endpoints de recarga (status, endereço de depósito e depósitos) usam o host da API de produção:

https://api.blockvectra.com

Limites de planos e parâmetros de preços são fornecidos pela Console API em https://console-api.blockvectra.com (como GET https://console-api.blockvectra.com/v1/plans).

1. Verificar a disponibilidade (GET /v1/topup/status)

Antes de iniciar uma transferência, verifique o status global de recarga, quais redes e tokens estão disponíveis e o limite mínimo de depósito ativo. Este endpoint é público e não exige credenciais.

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

Exemplo de resposta (redes e tokens selecionados):

{
  "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: chave global de ativação. Se for false, a recarga está fechada em todas as redes.
• networks: status de disponibilidade por rede e token. Quando enabled é false para uma rede ou token, não transfira fundos nessa rede.
• min_deposit_usd: valor mínimo global de depósito em USD, formatado com 6 casas decimais. O limite mínimo de depósito é dinâmico: sempre consulte o min_deposit_usd retornado em tempo real por GET https://api.blockvectra.com/v1/topup/status.

Para consultar diretamente o min_deposit_usd ativo:

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

2. Obter endereço de depósito e parâmetros (GET /v1/topup/deposit-address)

Obtenha ou aloque o endereço de depósito EVM do cliente e inspecione redes compatíveis e contratos de tokens. Este endpoint exige autenticação x-api-key e deve ser chamado apenas de ambientes de servidor.

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

Exemplo de resposta (redes e tokens selecionados):

{
  "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: endereço de depósito EVM exclusivo da sua conta com checksum EIP-55.
• deposits_url: URL para consultar registros de depósitos do cliente.
• networks: lista de redes EVM disponíveis. Redes fechadas são omitidas. Inclui slug da rede chain, Chain ID EVM chain_id, nome de exibição name, latência típica de crédito em segundos após inclusão no bloco typical_credit_seconds e template de URL de transação no explorador de blocos explorer_tx_url.
• tokens: tokens nesta rede, incluindo símbolo symbol (USDC / USDT / USDG), endereço do contrato contract, casas decimais decimals e depósito mínimo em unidades atômicas brutas min_amount_raw (consulte o valor real retornado pelo endpoint; não presuma uma quantidade ajustada).

Respostas de erro

Endpoints de recarga autenticados (/v1/topup/deposit-address e /v1/topup/deposits) retornam estruturas de erro JSON padrão:

• HTTP 401 (Falha de autenticação): retornado quando o cabeçalho x-api-key está ausente (missing_api_key) ou a API key é inválida, revogada ou desativada (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 desativada): retornado quando a recarga está fechada globalmente ou em todas as redes (topup_disabled):

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

Para a lista completa de códigos de erro, consulte a Referência de erros.

3. Transmitir a transferência on-chain

Usando a carteira ou o script do agente, envie uma transação ERC-20 transfer para o address de depósito obtido no passo 2.

Requisitos da transferência:

• Envie apenas tokens e contratos listados no array tokens daquela rede.
• Garanta que a quantidade transferida seja maior ou igual a min_amount_raw (conforme o valor real retornado por GET /v1/topup/deposit-address ou min_deposit_usd retornado por GET /v1/topup/status), formatada conforme o decimals do token naquela rede.
• Transferências enviadas a redes não compatíveis ou com tokens incorretos não podem ser creditadas automaticamente; verifique a rede e o contrato do token antes de transmitir.
• Registre o hash da transação on-chain (tx_hash) após o envio.

4. Consultar registros de depósitos e verificar o crédito (GET /v1/topup/deposits)

Depois que a transação for incluída em um bloco, consulte o histórico de transferências de depósito para acompanhar o status do crédito. Este endpoint exige x-api-key e é exclusivo para servidores.

Parâmetros de consulta

• limit: quantidade de registros de depósito por página. O padrão é 20; o intervalo válido é 1–100.
• before: parâmetro de paginação por cursor baseado em deposit_id. Envie o valor next_before da resposta anterior para obter a próxima página de registros mais antigos.
• tx_hash: hash de transação hexadecimal opcional de 64 caracteres com prefixo 0x para filtrar uma transferência específica.

Filtre pelo hash da transação (tx_hash) para inspecionar sua transferência específica:

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

Exemplo de resposta:

{
  "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ósito que correspondem aos parâmetros de consulta.
• next_before: ID de cursor para a próxima página quando há mais registros ou null se não há registros anteriores. Combine com o parâmetro de consulta before para paginação por cursor.

Valores de status do depósito:

• processing: transferência detectada on-chain, crédito em andamento.
• credited: creditado no saldo da conta. credited_units e credited_cu indicam as quantidades creditadas.
• not_credited: a transferência não pode ser creditada. O campo reason indica a causa:
  • below_minimum: a quantidade depositada está abaixo do limite mínimo.
  • large_amount: a quantidade depositada ultrapassa o limite e exige análise manual.
  • other: outra exceção de crédito.

Latência de crédito e orientação de polling:

• Tempo de chegada e crédito: o tempo de crédito é determinado pelo typical_credit_seconds retornado no passo 2.
• Intervalo de polling: consulte no intervalo recomendado de 20–60 segundos, sem aumentar a frequência, para evitar limites de taxa.

Exemplos de código

Os exemplos abaixo demonstram como ler BLOCKVECTRA_API_KEY do ambiente e consultar endpoints de recarga em Node.js e 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 passos

• Consultar saldo (GET /v1/account) para verificar o saldo da conta e as Compute Units (CU) restantes.
• Regras de cobrança para consultar medição de Compute Units (CU), limites de taxa e erros sem cobrança.
• Guia do plano gratuito para consultar limites do plano gratuito e regras de ampliação de capacidade.
• Guia de cadastro programático para criar contas e provisionar API keys com assinaturas de carteira.