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

> Source: https://docs.blockvectra.com/tr/guides/agent-topup/

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ı](https://blockvectra.com/tr/pricing/) kontrol edin ve [CU ağırlıklarından RPC ve Data API maliyetlerini tahmin edin](https://docs.blockvectra.com/en/guides/reading-cu-pricing/).

* **İ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](https://blockvectra.com/tr/agents/).

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

Oturum açın, [yatırma adresinizi almak için Faturalandırma sayfasını açın](https://console.blockvectra.com/login/?next=%2Fbilling%2F) 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](https://api.blockvectra.com/v1/topup/status) adresinden güncel ağları, tokenları ve minimum depozitoyu kontrol edin.

> **API key güvenliği ve sunucu tarafı gereksinimi**
>
> `x-api-key` başlığı **yalnızca sunucu tarafı ortamlarından çağrılabilir**. Bakiye yükleme uç noktalarını asla istemci tarafı tarayıcı kodundan çağırmayın ve API key'inizi asla ön uç paketlerinde, herkese açık depolarda veya AI sohbet konuşmalarında açığa çıkarmayın.


## Ö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](https://docs.blockvectra.com/en/guides/programmatic-signup/) takip edin veya [Konsol](https://console.blockvectra.com/login/?next=%2Fkeys%2F)'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](https://blockvectra.com/tr/pricing/) ve [ücretsiz plan kurallarına](https://blockvectra.com/tr/free/#rules) bakın; güncel sınırları ve minimum yükleme tutarını [GET /v1/plans](https://console-api.blockvectra.com/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](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.

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

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

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

```bash
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.

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

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

> **Token ondalık basamakları ve miktar dönüşümü**
>
> Aynı token farklı zincirlerde farklı ondalık basamaklara sahip olabilir (örneğin, BSC üzerindeki USDT ve USDC 18 basamaklıyken, Base üzerindeki USDC 6 basamaklıdır). Miktar hesaplaması, tek bir token ondalık değerini sabit kodlamak yerine o belirli ağ için döndürülen `decimals` değerini kullanmalıdır.


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

```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 (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:

```json
{
  "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ı](https://docs.blockvectra.com/en/errors/) 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:

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

Örnek yanıt:

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

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

## Sonraki adımlar

* [Bakiye sorgulayın (`GET /v1/account`)](https://docs.blockvectra.com/en/guides/billing-rules/#query-balance-get-v1account) 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ı](https://docs.blockvectra.com/en/guides/billing-rules/) sayfasına bakın.
* Ücretsiz katman sınırlarını ve yükseltme kurallarını incelemek için [Ücretsiz plan rehberi](https://docs.blockvectra.com/en/guides/free-plan/) sayfasına bakın.
* Cüzdan imzalarını kullanarak hesap oluşturmak ve API key temin etmek için [Programatik kayıt rehberi](https://docs.blockvectra.com/en/guides/programmatic-signup/) sayfasına bakın.