Payer le RPC avec USDC / USDT / USDG : recharge programmatique pour les agents IA

Les développeurs et les agents IA peuvent recharger un compte RPC et Data API via HTTP : vérifier les réseaux et les tokens ouverts, utiliser une clé API existante pour récupérer l'adresse de dépôt EVM du compte, puis interroger l'état des crédits après le transfert de fonds. Avant d'approvisionner, consultez la page des tarifs et estimez les coûts RPC et Data API à partir des pondérations en CU.

• Première étape : Exécutez curl -s https://api.blockvectra.com/v1/topup/status pour vérifier les réseaux ouverts, les tokens et min_deposit_usd avant de transférer des fonds.
• Terminé lorsque : L'enregistrement de dépôt pour votre tx_hash a le status: credited ; credited_units et credited_cu indiquent les crédits ajoutés à votre compte.

Options d'accès pour agents.

Obtenir votre adresse de dépôt dans Facturation

Connectez-vous, ouvrez Facturation pour obtenir votre adresse de dépôt, et utilisez l'adresse de dépôt ainsi que les détails des tokens affichés pour votre compte. Vérifiez les réseaux actuels, les tokens et le dépôt minimum sur GET /v1/topup/status avant de transférer des fonds.

Prérequis

• Clé API existante : L'appel des points de terminaison de recharge authentifiés nécessite une clé API RPC BlockVectra active. Si vous ne possédez pas encore de clé API, suivez le guide d'inscription programmatique pour vous inscrire et créer une clé à l'aide d'une signature de portefeuille Ethereum, ou créez-en une dans la console.
• Actifs on-chain : L'environnement de votre agent ou votre portefeuille de financement doit détenir les USDC / USDT / USDG répertoriés par GET /v1/topup/status sur un réseau pris en charge, ainsi que suffisamment de tokens de gas natifs pour diffuser les transactions.
• Variable d'environnement : Stockez votre clé dans la variable d'environnement BLOCKVECTRA_API_KEY.

Les points de terminaison de recharge authentifiés acceptent directement l'en-tête x-api-key en utilisant la même clé API que celle employée pour les appels RPC. Aucune session de navigateur n'est requise.

Flux de recharge en quatre étapes

Dès que la première recharge payante est créditée, les recharges de cycle gratuites s'arrêtent, les crédits gratuits non utilisés restent disponibles et le plafond de débit d'appels au niveau du compte est levé ; les limites de débit par clé restent inchangées. Consultez les règles de tarification et les règles du forfait gratuit ; lisez les limites actuelles et le montant minimum de recharge depuis GET /v1/plans (free, key_defaults et pricing.min_topup_usd).

Les points de terminaison de recharge (statut, adresse de dépôt et dépôts) utilisent l'hôte API de production :

https://api.blockvectra.com

Les limites des forfaits et les paramètres de tarification sont servis par l'API Console sur https://console-api.blockvectra.com (comme GET https://console-api.blockvectra.com/v1/plans).

1. Vérifier la disponibilité (GET /v1/topup/status)

Avant d'initier un transfert, vérifiez l'état global des recharges, contrôlez quels réseaux et tokens sont actuellement ouverts, et lisez le seuil de dépôt minimum actif. Ce point de terminaison est public et ne nécessite aucun identifiant.

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

Exemple de réponse (réseaux et tokens sélectionnés) :

{
  "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 : Commutateur global. Si false, la recharge est fermée sur tous les réseaux.
• networks : État d'ouverture par réseau et par token. Lorsque enabled est false pour un réseau ou un token, ne transférez pas de fonds sur ce réseau.
• min_deposit_usd : Montant minimum de dépôt global en USD formaté avec 6 décimales. Le seuil de dépôt minimum est dynamique : référez-vous toujours à la valeur min_deposit_usd renvoyée en temps réel par GET https://api.blockvectra.com/v1/topup/status.

Pour lire directement la valeur active de min_deposit_usd :

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

2. Récupérer l'adresse de dépôt et les paramètres (GET /v1/topup/deposit-address)

Récupérez ou allouez l'adresse de dépôt EVM du client et inspectez les réseaux et contrats de tokens pris en charge. Ce point de terminaison nécessite l'authentification x-api-key et doit être appelé uniquement depuis des environnements côté serveur.

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

Exemple de réponse (réseaux et tokens sélectionnés) :

{
  "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 : Adresse de dépôt EVM avec somme de contrôle EIP-55 dédiée à votre compte.
• deposits_url : URL pour interroger les enregistrements de dépôt du client.
• networks : Liste des réseaux EVM ouverts. Les réseaux fermés sont omis. Comprend le slug de la chaîne chain, le chain ID EVM chain_id, le nom d'affichage name, le délai habituel de crédit en secondes après inclusion dans le bloc typical_credit_seconds, et le modèle d'URL de transaction de l'explorateur de blocs explorer_tx_url.
• tokens : Tokens sur ce réseau, comprenant le symbole du token symbol (USDC / USDT / USDG), l'adresse du contrat contract, les décimales du token decimals et le montant minimum de dépôt en unités atomiques brutes min_amount_raw (référez-vous à la valeur réelle renvoyée par le point de terminaison ; ne présumez pas d'un montant mis à l'échelle).

Réponses d'erreur

Les points de terminaison de recharge authentifiés (/v1/topup/deposit-address et /v1/topup/deposits) renvoient des structures d'erreur JSON standard :

• HTTP 401 (Échec d'authentification) : Renvoyé lorsque l'en-tête x-api-key est manquant (missing_api_key) ou que la clé est invalide, révoquée ou désactivée (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 (Recharge désactivée) : Renvoyé lorsque la recharge est fermée globalement ou sur l'ensemble des réseaux (topup_disabled) :

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

Pour la liste complète des codes d'erreur, consultez la référence des erreurs.

3. Diffuser le transfert on-chain

À l'aide du portefeuille ou du script de votre agent, soumettez une transaction ERC-20 transfer vers l'address de dépôt récupérée à l'étape 2.

Exigences du transfert :

• Envoyez uniquement les tokens et contrats listés dans le tableau tokens pour ce réseau.
• Assurez-vous que le montant du transfert est supérieur ou égal à min_amount_raw (selon la valeur réelle renvoyée par GET /v1/topup/deposit-address, ou min_deposit_usd renvoyé par GET /v1/topup/status), formaté selon les decimals du token sur ce réseau.
• Les transferts envoyés vers des chaînes non prises en charge ou avec des tokens incorrects ne peuvent pas être crédités automatiquement ; vérifiez le réseau et le contrat de token avant la diffusion.
• Enregistrez le hash de transaction on-chain (tx_hash) une fois soumis.

4. Interroger les enregistrements de dépôt et vérifier les crédits (GET /v1/topup/deposits)

Une fois la transaction incluse dans un bloc, interrogez l'historique des transferts de dépôt pour suivre l'état de crédit. Ce point de terminaison nécessite x-api-key et s'utilise uniquement côté serveur.

Paramètres de requête

• limit : Nombre d'enregistrements de dépôt à renvoyer par page. La valeur par défaut est 20, la plage valide est comprise entre 1 et 100.
• before : Paramètre de pagination par curseur basé sur deposit_id. Transmettez la valeur next_before de la réponse de la page précédente pour récupérer la page suivante des enregistrements plus anciens.
• tx_hash : Hash de transaction hexadécimal facultatif de 64 caractères préfixé par 0x pour filtrer un transfert spécifique.

Filtrez par hash de transaction (tx_hash) pour inspecter votre transfert spécifique :

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

Exemple de réponse :

{
  "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 : Tableau d'enregistrements de dépôt correspondant aux paramètres de requête.
• next_before : Identifiant de curseur pour la page suivante lorsque d'autres enregistrements existent, ou null s'il n'existe pas d'enregistrements plus anciens. À combiner avec le paramètre de requête before pour la pagination par curseur.

Valeurs du champ status de dépôt :

• processing : Transfert détecté on-chain, crédit en cours.
• credited : Crédité sur le solde du compte. credited_units et credited_cu indiquent les montants crédités.
• not_credited : Le transfert ne peut pas être crédité. Le champ reason indique la cause :
  • below_minimum : Le montant du dépôt est inférieur au seuil minimum.
  • large_amount : Le montant du dépôt dépasse le seuil et nécessite une vérification manuelle.
  • other : Autre exception de crédit.

Conseils sur les délais de crédit et l'intervalle d'interrogation :

• Délai d'arrivée et de crédit : Le temps de crédit est régi par typical_credit_seconds renvoyé à l'étape 2.
• Intervalle d'interrogation : Interrogez à un intervalle recommandé de toutes les 20 à 60 secondes, et pas plus fréquemment, pour éviter de déclencher des limitations de débit.

Exemples de code

Les exemples suivants montrent comment lire BLOCKVECTRA_API_KEY depuis l'environnement et interroger les points de terminaison de recharge en Node.js et 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. Vérifier la disponibilité et lire le seuil de dépôt minimum
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. Récupérer l'adresse de dépôt et les réseaux ouverts
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. Interroger l'état du dépôt
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. Vérifier la disponibilité et lire le seuil de dépôt minimum
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. Récupérer l'adresse de dépôt
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. Interroger l'état du dépôt
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()

Prochaines étapes

• Consulter le solde (GET /v1/account) pour vérifier le solde de votre compte et les Compute Units (CU) restantes.
• Règles de facturation pour examiner le comptage des Compute Units (CU), les limites de débit et les erreurs non facturées.
• Guide du forfait gratuit pour examiner les limites du niveau gratuit et les règles de mise à niveau.
• Guide d'inscription programmatique pour créer des comptes et provisionner des clés API à l'aide de signatures de portefeuille.