USDC / USDT / USDG ile RPC ödemesi yapın: AI Agent'lar için programatik bakiye yükleme

Geliştiriciler ve AI Agent'lar, HTTP üzerinden bir RPC ve Data API hesabına bakiye yükleyebilir: açık ağları ve tokenları kontrol edin, hesabın EVM yatırma adresini almak için mevcut bir API key kullanın, ardından fonları transfer ettikten sonra bakiye yansıma durumunu sorgulayın. Fon aktarmadan önce fiyatlandırma sayfasını kontrol edin ve CU ağırlıklarından RPC ve Data API maliyetlerini tahmin edin.

• İlk adım: Fonları transfer etmeden önce açık ağları, tokenları ve min_deposit_usd değerini kontrol etmek için curl -s https://api.blockvectra.com/v1/topup/status komutunu çalıştırın.
• Tamamlanma koşulu: tx_hash değeriniz için depozito kaydının status: credited olması; credited_units ve credited_cu değerlerinin hesabınıza eklenen kredileri göstermesi.

Agent erişim seçenekleri.

Faturalandırma sayfasında yatırma adresinizi alın

Oturum açın, yatırma adresinizi almak için Faturalandırma sayfasını açın ve hesabınız için gösterilen yatırma adresini ve token ayrıntılarını kullanın. Fon transfer etmeden önce GET /v1/topup/status adresinden güncel ağları, tokenları ve minimum depozitoyu kontrol edin.

Ön koşullar

• Mevcut API key: Kimlik doğrulamalı bakiye yükleme uç noktalarını çağırmak, aktif bir BlockVectra RPC API key gerektirir. Henüz bir API key'iniz yoksa, bir Ethereum cüzdan imzası kullanarak kaydolmak ve bir anahtar oluşturmak için Programatik kayıt rehberini takip edin veya Konsol'da bir anahtar oluşturun.
• Zincir üstü varlıklar: Agent ortamınız veya fonlama cüzdanınız, desteklenen bir ağda GET /v1/topup/status tarafından listelenen USDC / USDT / USDG varlıklarını ve işlemleri yayınlamak için yeterli yerel gas tokenlarını bulundurmalıdır.
• Ortam değişkeni: Anahtarınızı BLOCKVECTRA_API_KEY ortam değişkeninde saklayın.

Kimlik doğrulamalı bakiye yükleme uç noktaları, RPC çağrıları için kullanılan API key'in aynısını kullanarak doğrudan x-api-key başlığını kabul eder. Tarayıcı oturumu gerekmez.

Dört adımlı bakiye yükleme iş akışı

İlk ücretli bakiye yüklemesi yansıtıldığında, ücretsiz döngü yenilemeleri durur, kullanılmayan ücretsiz krediler kullanılabilir kalır ve hesap düzeyindeki çağrı hızı sınırı kaldırılır; anahtar başına hız sınırları değişmeden kalır. Fiyatlandırma kurallarına ve ücretsiz plan kurallarına bakın; güncel sınırları ve minimum yükleme tutarını GET /v1/plans üzerinden okuyun (free, key_defaults ve pricing.min_topup_usd).

Bakiye yükleme uç noktaları (durum, yatırma adresi ve depozitolar) üretim API sunucusunu kullanır:

https://api.blockvectra.com

Plan sınırları ve fiyatlandırma parametreleri Console API tarafından https://console-api.blockvectra.com adresinden sunulur (GET https://console-api.blockvectra.com/v1/plans gibi).

1. Kullanılabilirliği kontrol edin (GET /v1/topup/status)

Bir transfer başlatmadan önce genel bakiye yükleme durumunu doğrulayın, hangi ağların ve tokenların açık olduğunu kontrol edin ve aktif minimum depozito eşiğini okuyun. Bu uç nokta herkese açıktır ve kimlik bilgisi gerektirmez.

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

Örnek yanıt (seçilen ağlar ve tokenlar):

{
  "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: Genel anahtar. false ise tüm ağlarda bakiye yükleme kapalıdır.
• networks: Ağ ve token başına açık olma durumu. Bir ağ veya token için enabled false olduğunda, bu ağda fon transferi yapmayın.
• min_deposit_usd: USD cinsinden 6 ondalık basamakla biçimlendirilmiş küresel minimum depozito tutarı. Minimum depozito eşiği dinamiktir: her zaman GET https://api.blockvectra.com/v1/topup/status tarafından gerçek zamanlı döndürülen min_deposit_usd değerini esas alın.

Aktif min_deposit_usd değerini doğrudan okumak için:

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

2. Yatırma adresini ve parametreleri alın (GET /v1/topup/deposit-address)

Müşteri EVM yatırma adresini alın veya tahsis edin ve desteklenen ağları ile token sözleşmelerini inceleyin. Bu uç nokta x-api-key kimlik doğrulaması gerektirir ve yalnızca sunucu tarafı ortamlarından çağrılmalıdır.

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

Örnek yanıt (seçilen ağlar ve tokenlar):

{
  "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: Hesabınıza özel, EIP-55 sağlama toplamlı EVM yatırma adresi.
• deposits_url: Müşteri bakiye yükleme kayıtlarını sorgulama URL'si.
• networks: Açık EVM ağlarının listesi. Kapalı ağlar hariç tutulur. Zincir slug'ı chain, EVM zincir kimliği chain_id, görünen ad name, blok onayından sonra saniye cinsinden tipik yansıma gecikmesi typical_credit_seconds ve blok gezgini işlem URL şablonu explorer_tx_url alanlarını içerir.
• tokens: Bu ağdaki tokenlar; token sembolü symbol (USDC / USDT / USDG), sözleşme adresi contract, token ondalık basamak sayısı decimals ve ham atomik birimler cinsinden minimum depozito tutarı min_amount_raw (uç nokta tarafından döndürülen gerçek değere bakın; ölçeklendirilmiş bir miktar varsaymayın) dahildir.

Hata yanıtları

Kimlik doğrulamalı bakiye yükleme uç noktaları (/v1/topup/deposit-address ve /v1/topup/deposits) standart JSON hata yapıları döndürür:

• HTTP 401 (Kimlik doğrulama hatası): x-api-key başlığı eksik olduğunda (missing_api_key) veya anahtar geçersiz, iptal edilmiş ya da devre dışı bırakılmış olduğunda (invalid_api_key) döndürülür:

{
  "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 (Bakiye yükleme devre dışı): Genel olarak veya tüm ağlarda bakiye yükleme kapalı olduğunda (topup_disabled) döndürülür:

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

Hata kodlarının tam listesi için Hata Referansı sayfasına bakın.

3. Zincir üstü transferi yayınlayın

Agent'ınızın cüzdanını veya betiğini kullanarak, 2. Adımda alınan yatırma adresine (address) bir ERC-20 transfer işlemi gönderin.

Transfer gereksinimleri:

• Yalnızca ilgili ağ için tokens dizisinde listelenen tokenları ve sözleşmeleri gönderin.
• Transfer miktarının, o ağdaki token decimals değerine göre biçimlendirilmiş olarak min_amount_raw değerine eşit veya bu değerden büyük olduğundan emin olun (GET /v1/topup/deposit-address tarafından döndürülen gerçek değere veya GET /v1/topup/status tarafından döndürülen min_deposit_usd değerine tabidir).
• Desteklenmeyen zincirlere veya yanlış tokenlarla gönderilen transferler otomatik olarak bakiyeye yansıtılamaz; yayınlamadan önce ağı ve token sözleşmesini doğrulayın.
• Gönderildikten sonra zincir üstü işlem karmasını (tx_hash) kaydedin.

4. Depozito kayıtlarını sorgulayın ve bakiyeyi doğrulayın (GET /v1/topup/deposits)

İşlem bir bloğa dahil edildikten sonra, bakiye yansıma durumunu izlemek için bakiye yükleme transfer geçmişini sorgulayın. Bu uç nokta x-api-key gerektirir ve yalnızca sunucu tarafı içindir.

Sorgu parametreleri

• limit: Sayfa başına döndürülecek depozito kaydı sayısı. Varsayılan 20'dir, geçerli aralık 1–100 arasındadır.
• before: deposit_id değerine dayalı imleç sayfalama parametresi. Daha önceki kayıtların sonraki sayfasını getirmek için önceki sayfa yanıtındaki next_before değerini iletin.
• tx_hash: Belirli bir transferi filtrelemek için isteğe bağlı, 0x ön ekli 64 karakterlik onaltılık işlem karması.

Belirli transferinizi incelemek için işlem karmasına (tx_hash) göre filtreleyin:

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

Örnek yanıt:

{
  "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: Sorgu parametreleriyle eşleşen depozito kayıtları dizisi.
• next_before: Daha fazla kayıt olduğunda sonraki sayfa için imleç kimliği; daha eski kayıt yoksa null. İmleç tabanlı sayfalama için before sorgu parametresiyle birleştirin.

Depozito status değerleri:

• processing: Transfer zincir üzerinde algılandı, bakiyeye yansıtma devam ediyor.
• credited: Hesap bakiyesine yansıtıldı. credited_units ve credited_cu, hesaba eklenen tutarları belirtir.
• not_credited: Transfer bakiyeye yansıtılamıyor. reason alanı nedeni belirtir:
  • below_minimum: Depozito miktarı minimum eşiğin altında.
  • large_amount: Depozito miktarı eşiği aşıyor ve manuel inceleme gerektiriyor.
  • other: Diğer bakiye yansıtma istisnası.

Yansıma gecikmesi ve sorgulama rehberi:

• Varış ve bakiyeye yansıma süresi: Yansıma süresi, 2. Adımda döndürülen typical_credit_seconds değerine tabidir.
• Sorgulama aralığı: Hız sınırlarını tetiklemekten kaçınmak için daha sık değil, her 20–60 saniyede bir önerilen aralıkla sorgulayın.

Kod örnekleri

Aşağıdaki örnekler, ortamdan BLOCKVECTRA_API_KEY değerinin nasıl okunacağını ve Node.js ile Python'da bakiye yükleme uç noktalarının nasıl sorgulanacağını gösterir.

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

Sonraki adımlar

• Bakiye sorgulayın (GET /v1/account) ile hesap bakiyenizi ve kalan Compute Units (CU) miktarınızı doğrulayın.
• Compute Unit (CU) ölçümü, hız sınırları ve faturalandırılmayan hataları incelemek için Faturalandırma kuralları sayfasına bakın.
• Ücretsiz katman sınırlarını ve yükseltme kurallarını incelemek için Ücretsiz plan rehberi sayfasına bakın.
• Cüzdan imzalarını kullanarak hesap oluşturmak ve API key temin etmek için Programatik kayıt rehberi sayfasına bakın.