# Payer le RPC avec USDC / USDT / USDG : recharge programmatique pour les agents IA > Source: https://docs.blockvectra.com/fr/guides/agent-topup/ 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](https://blockvectra.com/fr/pricing/) et [estimez les coûts RPC et Data API à partir des pondérations en CU](https://docs.blockvectra.com/fr/guides/reading-cu-pricing/). * **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](https://blockvectra.com/fr/agents/). ## Obtenir votre adresse de dépôt dans Facturation Connectez-vous, [ouvrez Facturation pour obtenir votre adresse de dépôt](https://console.blockvectra.com/login/?next=%2Fbilling%2F), 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](https://api.blockvectra.com/v1/topup/status) avant de transférer des fonds. > **Sécurité de la clé API et obligation côté serveur** > > L'en-tête `x-api-key` **ne peut être appelé que depuis des environnements côté serveur**. N'appelez jamais les points de terminaison de recharge depuis le code navigateur côté client, et n'exposez jamais votre clé API dans des bundles front-end, des dépôts publics ou des conversations de chat avec l'IA. ## 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](https://docs.blockvectra.com/fr/guides/programmatic-signup/) pour vous inscrire et créer une clé à l'aide d'une signature de portefeuille Ethereum, ou créez-en une dans la [console](https://console.blockvectra.com/login/?next=%2Fkeys%2F). * **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](https://blockvectra.com/fr/pricing/) et les [règles du forfait gratuit](https://blockvectra.com/fr/free/#rules) ; lisez les limites actuelles et le montant minimum de recharge depuis [GET /v1/plans](https://console-api.blockvectra.com/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](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. ```bash curl -s https://api.blockvectra.com/v1/topup/status ``` Exemple de réponse (réseaux et tokens sélectionnés) : ```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` : 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` : ```bash 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. ```bash 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) : ```json { "address": "0x", "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). > **Décimales des tokens et conversion des montants** > > Un même token peut avoir des décimales différentes selon les chaînes (par exemple, USDT et USDC sur BSC ont 18 décimales, tandis qu'USDC sur Base a 6 décimales). Le calcul des montants doit utiliser les `decimals` renvoyées pour ce réseau spécifique plutôt que de figer en dur une valeur unique de décimales. #### 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`) : ```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 (Recharge désactivée)** : Renvoyé lorsque la recharge est fermée globalement ou sur l'ensemble des réseaux (`topup_disabled`) : ```json { "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](https://docs.blockvectra.com/fr/errors/). ### 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 : ```bash curl -s \ -H "x-api-key: $BLOCKVECTRA_API_KEY" \ "https://api.blockvectra.com/v1/topup/deposits?tx_hash=0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" ``` Exemple de réponse : ```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` : 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) ```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. 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) ```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. 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`)](https://docs.blockvectra.com/fr/guides/billing-rules/#query-balance-get-v1account) pour vérifier le solde de votre compte et les Compute Units (CU) restantes. * [Règles de facturation](https://docs.blockvectra.com/fr/guides/billing-rules/) pour examiner le comptage des Compute Units (CU), les limites de débit et les erreurs non facturées. * [Guide du forfait gratuit](https://docs.blockvectra.com/fr/guides/free-plan/) pour examiner les limites du niveau gratuit et les règles de mise à niveau. * [Guide d'inscription programmatique](https://docs.blockvectra.com/fr/guides/programmatic-signup/) pour créer des comptes et provisionner des clés API à l'aide de signatures de portefeuille.