Bayar RPC dengan USDC / USDT / USDG: top up terprogram untuk agen AI

Pengembang dan Agen AI dapat melakukan top up akun RPC dan Data API melalui HTTP: periksa jaringan dan token yang terbuka, gunakan API key yang ada untuk mendapatkan alamat deposit EVM akun, lalu lakukan polling status kredit setelah mentransfer dana. Sebelum mendanai, periksa halaman harga dan perkirakan biaya RPC dan Data API dari bobot CU.

Dapatkan alamat deposit Anda di Penagihan

Masuk, buka Penagihan untuk mendapatkan alamat deposit Anda, dan gunakan alamat deposit serta detail token yang ditampilkan untuk akun Anda. Periksa jaringan, token, dan deposit minimum saat ini di GET /v1/topup/status sebelum mentransfer dana.

Prasyarat

• API key yang sudah ada: Memanggil endpoint top-up terautentikasi memerlukan API key RPC BlockVectra yang aktif. Jika Anda belum memiliki API key, ikuti Panduan pendaftaran terprogram untuk mendaftar dan membuat kunci menggunakan tanda tangan dompet Ethereum, atau buat satu di Konsol.
• Aset on-chain: Lingkungan agen atau dompet pendanaan Anda harus memiliki USDC / USDT / USDG yang tercantum di GET /v1/topup/status pada jaringan yang didukung, bersama dengan token gas native yang cukup untuk menyiarkan transaksi.
• Variabel lingkungan: Simpan kunci Anda dalam variabel lingkungan BLOCKVECTRA_API_KEY.

Endpoint top-up terautentikasi menerima header x-api-key secara langsung menggunakan API key yang sama dengan yang digunakan untuk panggilan RPC. Tidak diperlukan sesi browser.

Alur kerja top up empat langkah

Setelah top up berbayar pertama dikreditkan, pengisian ulang siklus gratis berhenti, kredit gratis yang belum digunakan tetap tersedia, dan batas laju panggilan tingkat akun dihapus; batas laju per-kunci tetap tidak berubah. Lihat aturan harga dan aturan paket gratis; baca batas saat ini dan deposit minimum dari GET /v1/plans (free, key_defaults, dan pricing.min_topup_usd).

Endpoint top-up (status, alamat deposit, dan deposit) menggunakan host API produksi:

https://api.blockvectra.com

Batas paket dan parameter harga disajikan oleh Console API di https://console-api.blockvectra.com (seperti GET https://console-api.blockvectra.com/v1/plans).

1. Periksa ketersediaan (GET /v1/topup/status)

Sebelum memulai transfer, verifikasi status top-up global, periksa jaringan dan token mana yang saat ini terbuka, dan baca ambang batas deposit minimum yang aktif. Endpoint ini bersifat publik dan tidak memerlukan kredensial.

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

Contoh respons (jaringan dan token yang dipilih):

{
  "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: Sakelar global. Jika false, top-up ditutup di semua jaringan.
• networks: Status terbuka per jaringan dan token. Ketika enabled bernilai false untuk suatu jaringan atau token, jangan transfer dana pada jaringan tersebut.
• min_deposit_usd: Jumlah deposit minimum global dalam USD yang diformat hingga 6 tempat desimal. Ambang batas deposit minimum bersifat dinamis: selalu rujuk min_deposit_usd yang dikembalikan secara real-time oleh GET https://api.blockvectra.com/v1/topup/status.

Untuk membaca min_deposit_usd yang aktif secara langsung:

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

2. Dapatkan alamat deposit dan parameter (GET /v1/topup/deposit-address)

Dapatkan atau alokasikan alamat deposit EVM pelanggan dan periksa jaringan serta kontrak token yang didukung. Endpoint ini memerlukan autentikasi x-api-key dan hanya boleh dipanggil dari lingkungan sisi server.

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

Contoh respons (jaringan dan token yang dipilih):

{
  "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: Alamat deposit EVM ber-checksum EIP-55 yang didedikasikan untuk akun Anda.
• deposits_url: URL untuk mengueri rekaman deposit pelanggan.
• networks: Daftar jaringan EVM yang terbuka. Jaringan yang ditutup dihilangkan. Mencakup slug rantai chain, EVM chain ID chain_id, nama tampilan name, latensi kredit tipikal dalam detik setelah penyertaan blok typical_credit_seconds, dan templat URL transaksi penjelajah blok explorer_tx_url.
• tokens: Token pada jaringan ini, termasuk simbol token symbol (USDC / USDT / USDG), alamat kontrak contract, desimal token decimals, dan jumlah deposit minimum dalam unit atomik mentah min_amount_raw (rujuk nilai aktual yang dikembalikan oleh endpoint; jangan berasumsi jumlah yang diskalakan).

Respons error

Endpoint top-up terautentikasi (/v1/topup/deposit-address dan /v1/topup/deposits) mengembalikan struktur error JSON standar:

• HTTP 401 (Kegagalan autentikasi): Dikembalikan ketika header x-api-key tidak ada (missing_api_key) atau kunci tidak valid, dicabut, atau dinonaktifkan (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 (Top-up dinonaktifkan): Dikembalikan ketika top-up ditutup secara global atau di semua jaringan (topup_disabled):

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

Untuk daftar lengkap kode error, lihat Referensi Error.

3. Siarkan transfer on-chain

Menggunakan dompet atau skrip agen Anda, kirim transaksi transfer ERC-20 ke address deposit yang diperoleh pada Langkah 2.

Persyaratan transfer:

• Kirim hanya token dan kontrak yang tercantum dalam array tokens untuk jaringan tersebut.
• Pastikan jumlah transfer lebih besar dari atau sama dengan min_amount_raw (tunduk pada nilai aktual yang dikembalikan oleh GET /v1/topup/deposit-address, atau min_deposit_usd yang dikembalikan oleh GET /v1/topup/status), diformat sesuai dengan decimals token pada jaringan tersebut.
• Transfer yang dikirim ke rantai yang tidak didukung atau dengan token yang salah tidak dapat dikreditkan secara otomatis; verifikasi jaringan dan kontrak token sebelum menyiarkan.
• Catat hash transaksi on-chain (tx_hash) setelah dikirimkan.

4. Lakukan polling rekaman deposit dan verifikasi kredit (GET /v1/topup/deposits)

Setelah transaksi dimasukkan ke dalam blok, kueri riwayat transfer deposit untuk melacak status pengkreditan. Endpoint ini memerlukan x-api-key dan hanya untuk sisi server.

Parameter kueri

• limit: Jumlah rekaman deposit yang dikembalikan per halaman. Default adalah 20, rentang valid adalah 1–100.
• before: Parameter paginasi kursor berdasarkan deposit_id. Teruskan nilai next_before dari respons halaman sebelumnya untuk mengambil halaman berikutnya dari rekaman yang lebih lama.
• tx_hash: Hash transaksi heksadesimal 64 karakter berawalan 0x opsional untuk memfilter transfer tertentu.

Filter berdasarkan hash transaksi (tx_hash) untuk memeriksa transfer spesifik Anda:

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

Contoh respons:

{
  "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 rekaman deposit yang cocok dengan parameter kueri.
• next_before: ID kursor untuk halaman berikutnya jika ada lebih banyak rekaman, atau null jika tidak ada rekaman yang lebih lama. Gabungkan dengan parameter kueri before untuk paginasi berbasis kursor.

Nilai status deposit:

• processing: Transfer terdeteksi on-chain, pengkreditan sedang berlangsung.
• credited: Dikreditkan ke saldo akun. credited_units dan credited_cu menunjukkan jumlah yang dikreditkan.
• not_credited: Transfer tidak dapat dikreditkan. Bidang reason menunjukkan penyebabnya:
  • below_minimum: Jumlah deposit di bawah ambang batas minimum.
  • large_amount: Jumlah deposit melebihi ambang batas dan memerlukan peninjauan manual.
  • other: Pengecualian pengkreditan lainnya.

Latensi kredit dan panduan polling:

• Waktu kedatangan dan pengkreditan: Waktu pengkreditan diatur oleh typical_credit_seconds yang dikembalikan pada Langkah 2.
• Interval polling: Lakukan polling dengan interval yang disarankan setiap 20–60 detik, tidak lebih sering, untuk menghindari pemicuan batas laju.

Contoh kode

Contoh berikut menunjukkan cara membaca BLOCKVECTRA_API_KEY dari lingkungan dan mengueri endpoint top-up di Node.js dan 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 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()

Langkah selanjutnya

• Kueri saldo (GET /v1/account) untuk memverifikasi saldo akun Anda dan sisa Compute Unit (CU).
• Aturan penagihan untuk meninjau pengukuran Compute Unit (CU), batas laju, dan error yang tidak ditagih.
• Panduan paket gratis untuk meninjau batas tingkat gratis dan aturan peningkatan.
• Panduan pendaftaran terprogram untuk membuat akun dan menyediakan API key menggunakan tanda tangan dompet.