# RPC mit USDC / USDT / USDG bezahlen: Programmatisches Aufladen für KI-Agenten > Source: https://docs.blockvectra.com/de/guides/agent-topup/ Entwickler und KI-Agenten können ein RPC- und Data-API-Konto über HTTP aufladen: Prüfen Sie offene Netzwerke und Token, nutzen Sie einen bestehenden API key, um die EVM-Einzahlungsadresse des Kontos abzurufen, und pollen Sie nach dem Transfer von Mitteln den Gutschriftstatus. Prüfen Sie vor der Einzahlung die [Preisseite](https://blockvectra.com/de/pricing/) und [schätzen Sie die RPC- und Data-API-Kosten anhand von CU-Gewichten](https://docs.blockvectra.com/de/guides/reading-cu-pricing/). * **Erster Schritt:** Führen Sie `curl -s https://api.blockvectra.com/v1/topup/status` aus, um offene Netzwerke, Token und `min_deposit_usd` vor dem Transfer von Mitteln zu prüfen. * **Abgeschlossen, wenn:** Der Einzahlungsdatensatz für Ihren `tx_hash` den Status `status: credited` aufweist; `credited_units` und `credited_cu` zeigen das Ihrem Konto gutgeschriebene Guthaben an. [Agent-Zugriffsoptionen](https://blockvectra.com/de/agents/). ## Einzahlungsadresse in Billing abrufen Melden Sie sich an, [öffnen Sie Billing, um Ihre Einzahlungsadresse abzurufen](https://console.blockvectra.com/login/?next=%2Fbilling%2F), und nutzen Sie die für Ihr Konto angezeigte Einzahlungsadresse und Tokendetails. Prüfen Sie die aktuellen Netzwerke, Token und Mindesteinzahlungen unter [GET /v1/topup/status](https://api.blockvectra.com/v1/topup/status), bevor Sie Mittel transferieren. > **Sicherheit des API keys und serverseitige Anforderung** > > Der `x-api-key`-Header **kann nur aus serverseitigen Umgebungen aufgerufen werden**. Rufen Sie Top-up-Endpunkte niemals aus clientseitigem Browser-Code auf und legen Sie Ihren API key keinesfalls in Frontend-Bundles, öffentlichen Repositories oder KI-Chat-Konversationen offen. ## Voraussetzungen * **Bestehender API key**: Der Aufruf authentifizierter Top-up-Endpunkte erfordert einen aktiven BlockVectra-RPC-API-key. Falls Sie noch keinen API key besitzen, folgen Sie dem [Leitfaden zur programmatischen Registrierung](https://docs.blockvectra.com/de/guides/programmatic-signup/), um sich über eine Ethereum-Wallet-Signatur zu registrieren und einen Key zu erstellen, oder generieren Sie einen in der [Konsole](https://console.blockvectra.com/login/?next=%2Fkeys%2F). * **On-Chain-Assets**: Ihre Agenten-Umgebung oder Einzahlungs-Wallet muss von `GET /v1/topup/status` aufgelistete USDC / USDT / USDG auf einem unterstützten Netzwerk halten, zusammen mit ausreichend nativen Gas-Token zum Übertragen von Transaktionen. * **Umgebungsvariable**: Speichern Sie Ihren Key in der Umgebungsvariablen `BLOCKVECTRA_API_KEY`. Die authentifizierten Top-up-Endpunkte akzeptieren den `x-api-key`-Header direkt mit demselben API key, der auch für RPC-Aufrufe verwendet wird. Es ist keine Browser-Sitzung erforderlich. ## Vierstufiger Auflade-Workflow Sobald die erste bezahlte Aufladung gutgeschrieben ist, enden die kostenlosen Zyklus-Auffüllungen, ungenutztes kostenloses Guthaben bleibt weiterhin verfügbar und die Aufrufratenbegrenzung auf Kontoebene wird aufgehoben; Ratenbegrenzungen pro Key bleiben unverändert. Siehe die [Preisregeln](https://blockvectra.com/de/pricing/) und [Regeln des kostenlosen Tarifs](https://blockvectra.com/de/free/#rules); lesen Sie aktuelle Limits und die Mindestaufladung über [GET /v1/plans](https://console-api.blockvectra.com/v1/plans) (`free`, `key_defaults` und `pricing.min_topup_usd`) ab. Top-up-Endpunkte (Status, Einzahlungsadresse und Einzahlungen) nutzen den Produktions-API-Host: ``` https://api.blockvectra.com ``` Tariflimits und Preisparameter werden von der Console-API unter `https://console-api.blockvectra.com` bereitgestellt (wie [GET https://console-api.blockvectra.com/v1/plans](https://console-api.blockvectra.com/v1/plans)). ### 1. Verfügbarkeit prüfen (GET /v1/topup/status) Prüfen Sie vor dem Initiieren eines Transfers den globalen Top-up-Status, kontrollieren Sie, welche Netzwerke und Token aktuell geöffnet sind, und lesen Sie die aktive Mindesteinzahlungsgrenze aus. Dieser Endpunkt ist öffentlich und erfordert keine Anmeldedaten. ```bash curl -s https://api.blockvectra.com/v1/topup/status ``` Beispielantwort (ausgewählte Netzwerke und Token): ```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`: Globaler Schalter. Wenn `false`, ist das Aufladen über alle Netzwerke hinweg geschlossen. * `networks`: Offener Status pro Netzwerk und Token. Wenn `enabled` für ein Netzwerk oder Token `false` ist, **transferieren Sie keine Mittel auf diesem Netzwerk**. * `min_deposit_usd`: Globaler Mindesteinzahlungsbetrag in USD, formatiert auf 6 Dezimalstellen. Der Mindesteinzahlungsbetrag ist dynamisch: Beziehen Sie sich immer auf den von `GET https://api.blockvectra.com/v1/topup/status` in Echtzeit zurückgegebenen Wert `min_deposit_usd`. Um den aktiven Wert `min_deposit_usd` direkt auszulesen: ```bash curl -s https://api.blockvectra.com/v1/topup/status | jq -r .min_deposit_usd ``` ### 2. Einzahlungsadresse und Parameter abrufen (GET /v1/topup/deposit-address) Rufen Sie die EVM-Einzahlungsadresse des Kunden ab bzw. weisen Sie diese zu und prüfen Sie unterstützte Netzwerke und Token-Contracts. Dieser Endpunkt erfordert eine Authentifizierung per `x-api-key` und darf nur aus serverseitigen Umgebungen aufgerufen werden. ```bash curl -s \ -H "x-api-key: $BLOCKVECTRA_API_KEY" \ https://api.blockvectra.com/v1/topup/deposit-address ``` Beispielantwort (ausgewählte Netzwerke und Token): ```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`: EIP-55-checksummierte, Ihrem Konto fest zugeordnete EVM-Einzahlungsadresse. * `deposits_url`: URL zur Abfrage von Kundeneinzahlungsdatensätzen. * `networks`: Liste der offenen EVM-Netzwerke. Geschlossene Netzwerke werden weggelassen. Enthält den Chain-Slug `chain`, die EVM-Chain-ID `chain_id`, den Anzeigenamen `name`, die typische Gutschriftlatenz in Sekunden nach Blockaufnahme `typical_credit_seconds` sowie die Transaktions-URL-Vorlage des Block-Explorers `explorer_tx_url`. * `tokens`: Token auf diesem Netzwerk, einschließlich Token-Symbol `symbol` (USDC / USDT / USDG), Contract-Adresse `contract`, Token-Dezimalstellen `decimals` und Mindesteinzahlungsbetrag in atomaren Basiseinheiten `min_amount_raw` (beziehen Sie sich auf den tatsächlichen Rückgabewert des Endpunkts; gehen Sie nicht von einem skalierten Betrag aus). > **Token-Dezimalstellen und Betragskonvertierung** > > Derselbe Token kann auf verschiedenen Chains unterschiedliche Dezimalstellen haben (beispielsweise haben USDT und USDC auf BSC 18 Dezimalstellen, während USDC auf Base 6 Dezimalstellen hat). Die Betragsberechnung muss die für das jeweilige Netzwerk zurückgegebenen `decimals` verwenden, anstatt einen festen Dezimalwert vorauszusetzen. #### Fehlerantworten Authentifizierte Top-up-Endpunkte (`/v1/topup/deposit-address` und `/v1/topup/deposits`) geben standardmäßige JSON-Fehlerstrukturen zurück: * **HTTP 401 (Authentifizierungsfehler)**: Wird zurückgegeben, wenn der `x-api-key`-Header fehlt (`missing_api_key`) oder der Key ungültig, widerrufen oder deaktiviert ist (`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 (Aufladung deaktiviert)**: Wird zurückgegeben, wenn das Aufladen global oder über alle Netzwerke hinweg geschlossen ist (`topup_disabled`): ```json { "error": { "code": "topup_disabled", "data": { "reason": "topup_disabled", "docs_url": "https://docs.blockvectra.com/en/errors/#topup_disabled", "retryable": false } } } ``` Die vollständige Liste der Fehlercodes finden Sie in der [Fehlerreferenz](https://docs.blockvectra.com/de/errors/). ### 3. On-Chain-Transfer senden Senden Sie über die Wallet oder ein Skript Ihres Agenten eine ERC-20-`transfer`-Transaktion an die in Schritt 2 abgerufene Einzahlungsadresse `address`. Transferanforderungen: * Senden Sie nur Token und Contracts, die im `tokens`-Array für dieses Netzwerk aufgeführt sind. * Stellen Sie sicher, dass der Transferbetrag größer oder gleich `min_amount_raw` ist (vorbehaltlich des von `GET /v1/topup/deposit-address` zurückgegebenen tatsächlichen Werts bzw. des von `GET /v1/topup/status` zurückgegebenen `min_deposit_usd`), formatiert gemäß den `decimals` des Tokens auf diesem Netzwerk. * An nicht unterstützte Chains oder mit falschen Token gesendete Transfers können nicht automatisch gutgeschrieben werden; überprüfen Sie das Netzwerk und den Token-Contract vor dem Senden. * Halten Sie den On-Chain-Transaktions-Hash (`tx_hash`) nach der Übermittlung fest. ### 4. Einzahlungsdatensätze pollen und Gutschrift prüfen (GET /v1/topup/deposits) Fragen Sie nach der Aufnahme der Transaktion in einen Block die Einzahlungshistorie ab, um den Gutschriftstatus nachzuverfolgen. Dieser Endpunkt erfordert `x-api-key` und ist nur für serverseitige Aufrufe vorgesehen. #### Abfrageparameter * `limit`: Anzahl der pro Seite zurückzugebenden Einzahlungsdatensätze. Standardwert ist `20`, gültiger Bereich ist `1`–`100`. * `before`: Cursor-Paginierungsparameter basierend auf `deposit_id`. Übergeben Sie den Wert `next_before` aus der vorherigen Seitenantwort, um die nächste Seite früherer Datensätze abzurufen. * `tx_hash`: Optionaler, 64-stelliger hexadezimaler Transaktions-Hash mit 0x-Präfix zum Filtern nach einem bestimmten Transfer. Filtern Sie nach Transaktions-Hash (`tx_hash`), um Ihren spezifischen Transfer einzusehen: ```bash curl -s \ -H "x-api-key: $BLOCKVECTRA_API_KEY" \ "https://api.blockvectra.com/v1/topup/deposits?tx_hash=0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" ``` Beispielantwort: ```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`: Array von Einzahlungsdatensätzen, die den Abfrageparametern entsprechen. * `next_before`: Cursor-ID für die nächste Seite, wenn weitere Datensätze vorhanden sind, oder `null`, wenn keine früheren Datensätze vorliegen. Kombinieren Sie diesen Wert mit dem Abfrageparameter `before` für die cursorbasierte Paginierung. Werte für den Einzahlungsstatus `status`: * `processing`: Transfer wurde on-chain erkannt, Gutschrift läuft. * `credited`: Dem Kontoguthaben gutgeschrieben. `credited_units` und `credited_cu` geben die gutgeschriebenen Beträge an. * `not_credited`: Transfer kann nicht gutgeschrieben werden. Das Feld `reason` nennt die Ursache: * `below_minimum`: Einzahlungsbetrag liegt unter dem Mindestbetrag. * `large_amount`: Einzahlungsbetrag überschreitet den Schwellenwert und erfordert eine manuelle Überprüfung. * `other`: Sonstige Gutschriftausnahme. Gutschriftlatenz und Polling-Hinweise: * **Bestätigungs- und Gutschriftlatenz**: Die Gutschriftzeit richtet sich nach dem in Schritt 2 zurückgegebenen Wert `typical_credit_seconds`. * **Polling-Intervall**: Pollen Sie in einem empfohlenen Intervall von **alle 20–60 Sekunden**, keinesfalls häufiger, um das Auslösen von Rate-Limits zu vermeiden. ## Codebeispiele Die folgenden Beispiele zeigen, wie `BLOCKVECTRA_API_KEY` aus der Umgebung ausgelesen und Top-up-Endpunkte in Node.js und Python abgefragt werden. ### 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. 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) ```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. 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() ``` ## Nächste Schritte * [Guthaben abfragen (`GET /v1/account`)](https://docs.blockvectra.com/de/guides/billing-rules/#query-balance-get-v1account), um Ihr Kontoguthaben und verbleibende Compute Units (CU) zu überprüfen. * [Abrechnungsregeln](https://docs.blockvectra.com/de/guides/billing-rules/), um Compute Unit (CU)-Messung, Rate-Limits und nicht abgerechnete Fehler einzusehen. * [Leitfaden zum kostenlosen Tarif](https://docs.blockvectra.com/de/guides/free-plan/), um Limits des Free-Tiers und Upgrade-Regeln einzusehen. * [Leitfaden zur programmatischen Registrierung](https://docs.blockvectra.com/de/guides/programmatic-signup/), um Konten zu erstellen und API keys über Wallet-Signaturen bereitzustellen.