Pagar por RPC com USDC / USDT / USDG: recarga programática para agentes de IA
Recarregue uma conta RPC e Data API on-chain via HTTP. Desenvolvedores e agentes de IA usam uma API key para verificar tokens compatíveis, obter um endereço de depósito exclusivo e consultar o status do crédito.
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 e os tokens atuais em GET /v1/topup/status e leia o mínimo dinâmico em USD de pricing.min_topup_usd em GET /v1/plans antes de transferir fundos.
API key security and server-side requirement
O cabeçalho x-api-key só pode ser usado em chamadas de ambientes de servidor. Nunca chame endpoints de recarga de código no navegador do cliente e nunca exponha sua API key em bundles de frontend, repositórios públicos ou conversas de chat com IA.
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/statusem 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 de CU de cada key não revogada são elevados para pelo menos o mínimo das contas pagas, e limites personalizados mais altos são mantidos. 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, paid_key_minimums 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.comLimites 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 e quais redes e tokens estão disponíveis. O mínimo em USD vem de pricing.min_topup_usd em GET /v1/plans, não deste endpoint. Este endpoint é público e não exige credenciais.
curl -s https://api.blockvectra.com/v1/topup/statusExemplo 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 forfalse, a recarga está fechada em todas as redes.networks: status de disponibilidade por rede e token. Quandoenabledéfalsepara uma rede ou token, não transfira fundos nessa rede.min_deposit_usd: Valor secundário em USD (6 casas decimais) para conferência compricing.min_topup_usddeGET https://console-api.blockvectra.com/v1/plans, o mínimo dinâmico em USD de referência. Não é uma fonte alternativa do mínimo.
Para ler o mínimo dinâmico em USD de referência:
curl -s https://console-api.blockvectra.com/v1/plans | jq -r .pricing.min_topup_usd2. 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-addressExemplo 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 redechain, Chain ID EVMchain_id, nome de exibiçãoname, latência típica de crédito em segundos após inclusão no blocotypical_credit_secondse template de URL de transação no explorador de blocosexplorer_tx_url.tokens: tokens nesta rede, incluindo símbolosymbol(USDC / USDT / USDG), endereço do contratocontract, casas decimaisdecimalse depósito mínimo em unidades atômicas brutasmin_amount_raw(consulte o valor real retornado pelo endpoint; não presuma uma quantidade ajustada).
Token decimals and amount conversion
O mesmo token pode ter casas decimais diferentes em redes diferentes (por exemplo, USDT e USDC na BSC têm 18 casas decimais, enquanto USDC na Base tem 6). O cálculo de quantidades deve usar o decimals retornado para aquela rede específica, em vez de fixar um único valor de casas decimais para o token.
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-keyestá 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
tokensdaquela rede. - Garanta que a quantidade transferida seja maior ou igual a
min_amount_raw(vale o valor real retornado porGET /v1/topup/deposit-addresspara o token escolhido), formatada conforme odecimalsdo token naquela rede. - Antes de transmitir, leia as respostas desta execução de
GET /v1/plans,GET /v1/topup/statuseGET /v1/topup/deposit-addresse confirme que a recarga está habilitada, que a rede e o token estão abertos e quecontract,decimals,min_amount_rawe oaddressde depósito da sua conta estão presentes e consistentes. Se algum valor estiver ausente, fechado ou contraditório, pare e não transmita.pricing.min_topup_usdé a política dinâmica em USD; qualquer mínimo fixo antigo não é referência, e$1é apenas um valor de exemplo, não um mínimo. Converta o valor para unidades atômicas inteiras exatas comdecimalse compare commin_amount_raw; não compare USD diretamente com unidades do token. As chamadas de status e endereço nos exemplos de código abaixo apenas leem e imprimem valores; não são a verificação completa antes da transmissão. - 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 emdeposit_id. Envie o valornext_beforeda 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: odeposit_iddo último item quando a página está cheia (o número de itens é igual alimit); caso contrário,null. Uma última página cheia também retorna um cursor; ao solicitá-lo, você recebe uma página vazia (items: []) comnext_before: null. Pare a paginação quandonext_beforefornull. Combine com o parâmetro de consultabeforepara 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_unitsecredited_cuindicam as quantidades creditadas.not_credited: a transferência não pode ser creditada. O camporeasonindica 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_secondsretornado 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; status min_deposit_usd is a secondary cross-check (USD minimum authority: GET /v1/plans pricing.min_topup_usd)
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("Status min_deposit_usd (secondary, 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; status min_deposit_usd is a secondary cross-check (USD minimum authority: GET /v1/plans pricing.min_topup_usd)
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("Status min_deposit_usd (secondary, 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.
Última atualização:
Receitas de frameworks de agentes
Configure RPC de blockchain para ElizaOS, viem, wagmi e Coinbase AgentKit e descubra recursos com o MCP de documentação.
Conectar agentes de IA
Conecte agentes de IA ao RPC de blockchain e ao MCP de documentação: descubra recursos sem chave, cadastre-se via HTTP e chame RPC e Data API com uma API key.