RPC mit USDC / USDT / USDG bezahlen: Programmatisches Aufladen für KI-Agenten

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 und schätzen Sie die RPC- und Data-API-Kosten anhand von CU-Gewichten.

• 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.

Einzahlungsadresse in Billing abrufen

Melden Sie sich an, öffnen Sie Billing, um Ihre Einzahlungsadresse abzurufen, 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, bevor Sie Mittel transferieren.

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, um sich über eine Ethereum-Wallet-Signatur zu registrieren und einen Key zu erstellen, oder generieren Sie einen in der Konsole.
• 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 und Regeln des kostenlosen Tarifs; lesen Sie aktuelle Limits und die Mindestaufladung über GET /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).

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.

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

Beispielantwort (ausgewählte Netzwerke und Token):

{
  "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:

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.

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

Beispielantwort (ausgewählte Netzwerke und Token):

{
  "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: 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).

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):

{
  "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):

{
  "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.

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:

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

Beispielantwort:

{
  "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)

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()

Nächste Schritte

• Guthaben abfragen (GET /v1/account), um Ihr Kontoguthaben und verbleibende Compute Units (CU) zu überprüfen.
• Abrechnungsregeln, um Compute Unit (CU)-Messung, Rate-Limits und nicht abgerechnete Fehler einzusehen.
• Leitfaden zum kostenlosen Tarif, um Limits des Free-Tiers und Upgrade-Regeln einzusehen.
• Leitfaden zur programmatischen Registrierung, um Konten zu erstellen und API keys über Wallet-Signaturen bereitzustellen.