# Оплата RPC за допомогою USDC / USDT / USDG: програмне поповнення для AI-агентів

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

Розробники та AI-агенти можуть поповнювати акаунт RPC та Data API через HTTP: перевіряти доступні мережі й токени, використовувати наявний API key для отримання EVM-адреси депозиту акаунта, а потім опитувати статус зарахування після переказу коштів. Перед поповненням перегляньте [сторінку цін](https://blockvectra.com/en/pricing/) та [оцініть витрати на RPC і Data API за вагою CU](https://docs.blockvectra.com/en/guides/reading-cu-pricing/).

* **Перший крок:** виконайте `curl -s https://api.blockvectra.com/v1/topup/status`, щоб перевірити доступні мережі, токени та `min_deposit_usd` перед переказом коштів.
* **Готово, коли:** запис депозиту для вашого `tx_hash` має `status: credited`; поля `credited_units` та `credited_cu` показують кредити, додані до вашого акаунта.

[Варіанти доступу для агентів](https://blockvectra.com/en/agents/).

## Отримання адреси депозиту в розділі Billing

Увійдіть, [відкрийте Billing, щоб отримати адресу депозиту](https://console.blockvectra.com/login/?next=%2Fbilling%2F), і використовуйте адресу депозиту та деталі токенів, наведені для вашого акаунта. Перевірте поточні мережі, токени та мінімальний депозит у [GET /v1/topup/status](https://api.blockvectra.com/v1/topup/status) перед переказом коштів.

> **Безпека API key та вимога використання на стороні сервера**
>
> Заголовок `x-api-key` **можна викликати лише із середовища на стороні сервера**. Ніколи не викликайте ендпоінти поповнення з клієнтського коду браузера й ніколи не розкривайте свій API key у фронтенд-бандлах, публічних репозиторіях або чатах з AI.


## Передумови

* **Наявний API key**: виклик автентифікованих ендпоінтів поповнення вимагає активного BlockVectra RPC API key. Якщо у вас ще немає API key, виконайте інструкції з [Посібника з програмної реєстрації](https://docs.blockvectra.com/en/guides/programmatic-signup/), щоб зареєструватися та створити ключ за допомогою підпису Ethereum-гаманця, або створіть його в [Консолі](https://console.blockvectra.com/login/?next=%2Fkeys%2F).
* **Ончейн-активи**: середовище вашого агента або гаманець для фінансування повинні містити USDC / USDT / USDG, перелічені у відповіді `GET /v1/topup/status` для підтримуваної мережі, разом із достатньою кількістю нативних токенів газу для трансляції транзакцій.
* **Змінна середовища**: збережіть свій ключ у змінній середовища `BLOCKVECTRA_API_KEY`.

Автентифіковані ендпоінти поповнення приймають заголовок `x-api-key` напряму, використовуючи той самий API key, що й для RPC-викликів. Сесія браузера не потрібна.

## Чотирикроковий робочий процес поповнення

Щойно перший платний депозит буде зараховано, поповнення безкоштовного циклу припиняються, невикористані безкоштовні кредити залишаються доступними, а ліміт частоти викликів на рівні акаунта знімається; обмеження швидкості на кожен ключ залишаються без змін. Див. [правила тарифікації](https://blockvectra.com/en/pricing/) та [правила безкоштовного плану](https://blockvectra.com/en/free/#rules); отримайте актуальні ліміти та мінімальну суму поповнення з [GET /v1/plans](https://console-api.blockvectra.com/v1/plans) (`free`, `key_defaults` та `pricing.min_topup_usd`).

Ендпоінти поповнення (статус, адреса депозиту та депозити) використовують продакшн-хост API:

```
https://api.blockvectra.com
```

Ліміти плану та параметри ціноутворення надаються Console API за адресою `https://console-api.blockvectra.com` (наприклад, [GET https://console-api.blockvectra.com/v1/plans](https://console-api.blockvectra.com/v1/plans)).

### 1. Перевірка доступності (GET /v1/topup/status)

Перед ініціюванням переказу перевірте глобальний статус поповнення, які мережі й токени зараз відкриті, а також прочитайте активний поріг мінімального депозиту. Цей ендпоінт є публічним і не потребує облікових даних.

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

Приклад відповіді (вибрані мережі та токени):

```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`: глобальний перемикач. Якщо має значення `false`, поповнення закрите для всіх мереж.
* `networks`: статус доступності для кожної мережі та токена. Якщо `enabled` має значення `false` для мережі чи токена, **не переказуйте кошти в цій мережі**.
* `min_deposit_usd`: глобальна мінімальна сума депозиту в USD, відформатована до 6 десяткових знаків. Поріг мінімального депозиту є динамічним: завжди орієнтуйтеся на значення `min_deposit_usd`, яке повертається в реальному часі ендпоінтом `GET https://api.blockvectra.com/v1/topup/status`.

Щоб отримати активний `min_deposit_usd` напряму:

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

### 2. Отримання адреси депозиту та параметрів (GET /v1/topup/deposit-address)

Отримайте або виділіть EVM-адресу депозиту клієнта та перегляньте підтримувані мережі й контракти токенів. Цей ендпоінт вимагає автентифікації за допомогою `x-api-key` і має викликатися виключно із середовища на стороні сервера.

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

Приклад відповіді (вибрані мережі та токени):

```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`: виділена для вашого акаунта EVM-адреса депозиту з контрольною сумою EIP-55.
* `deposits_url`: URL для запиту записів депозитів клієнта.
* `networks`: список відкритих EVM-мереж. Закриті мережі не відображаються. Містить ідентифікатор мережі `chain`, EVM chain ID `chain_id`, відображувану назву `name`, типовий час зарахування в секундах після включення в блок `typical_credit_seconds` та шаблон URL транзакції в блок-експлорері `explorer_tx_url`.
* `tokens`: токени в цій мережі, включно із символом токена `symbol` (USDC / USDT / USDG), адресою контракту `contract`, кількістю десяткових знаків токена `decimals` та мінімальною сумою депозиту в необроблених атомарних одиницях `min_amount_raw` (орієнтуйтеся на фактичне значення, повернуте ендпоінтом; не припускайте масштабовану суму).

> **Кількість десяткових знаків токена та конвертація суми**
>
> Один і той самий токен може мати різну кількість десяткових знаків у різних мережах (наприклад, USDT та USDC на BSC мають 18 знаків, тоді як USDC на Base має 6 знаків). Розрахунок суми має використовувати значення `decimals`, повернуте для конкретної мережі, замість фіксації одного значення в коді.


#### Відповіді з помилками

Автентифіковані ендпоінти поповнення (`/v1/topup/deposit-address` та `/v1/topup/deposits`) повертають стандартні структури помилок JSON:

* **HTTP 401 (Помилка автентифікації)**: повертається, якщо заголовок `x-api-key` відсутній (`missing_api_key`) або якщо ключ недійсний, відкликаний чи вимкнений (`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 (Поповнення вимкнено)**: повертається, якщо поповнення закрито глобально або у всіх мережах (`topup_disabled`):

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

Повний список кодів помилок див. у [Довіднику помилок](https://docs.blockvectra.com/en/errors/).

### 3. Трансляція ончейн-переказу

Використовуючи гаманець вашого агента або скрипт, надішліть транзакцію `transfer` ERC-20 на адресу депозиту `address`, отриману на Кроці 2.

Вимоги до переказу:

* Надсилайте лише токени та контракти, зазначені в масиві `tokens` для цієї мережі.
* Переконайтеся, що сума переказу більша або дорівнює `min_amount_raw` (згідно з фактичним значенням, повернутим `GET /v1/topup/deposit-address`, або `min_deposit_usd`, повернутим `GET /v1/topup/status`), відформатована відповідно до `decimals` токена в цій мережі.
* Перекази, надіслані на непідтримувані мережі або з неправильними токенами, не можуть бути зараховані автоматично; перевірте мережу та контракт токена перед трансляцією.
* Збережіть хеш ончейн-транзакції (`tx_hash`) після її відправлення.

### 4. Опитування записів депозитів та перевірка зарахування (GET /v1/topup/deposits)

Після включення транзакції в блок надішліть запит до історії переказів депозитів для відстеження статусу зарахування. Цей ендпоінт вимагає `x-api-key` і доступний лише на стороні сервера.

#### Параметри запиту

* `limit`: кількість записів депозитів, що повертаються на сторінку. За замовчуванням `20`, допустимий діапазон від `1` до `100`.
* `before`: параметр курсорної пагінації на основі `deposit_id`. Передайте значення `next_before` з відповіді попередньої сторінки, щоб отримати наступну сторінку раніших записів.
* `tx_hash`: необов'язковий 64-символьний шістнадцятковий хеш транзакції з префіксом 0x для фільтрації конкретного переказу.

Фільтруйте за хешем транзакції (`tx_hash`), щоб перевірити ваш конкретний переказ:

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

Приклад відповіді:

```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`: масив записів депозитів, що відповідають параметрам запиту.
* `next_before`: ID курсора для наступної сторінки, якщо існують інші записи, або `null`, якщо раніших записів немає. Використовуйте разом із параметром запиту `before` для курсорної пагінації.

Значення `status` депозиту:

* `processing`: переказ виявлено в мережі, триває зарахування.
* `credited`: зараховано на баланс акаунта. `credited_units` та `credited_cu` вказують зараховані суми.
* `not_credited`: переказ не може бути зарахований. Поле `reason` вказує причину:
  * `below_minimum`: сума депозиту нижча за мінімальний поріг.
  * `large_amount`: сума депозиту перевищує поріг і вимагає ручної перевірки.
  * `other`: інша виняткова ситуація під час зарахування.

Час зарахування та рекомендації щодо опитування:

* **Час надходження та зарахування**: час зарахування визначається параметром `typical_credit_seconds`, повернутим на Кроці 2.
* **Інтервал опитування**: опитуйте з рекомендованим інтервалом **кожні 20–60 секунд**, не частіше, щоб уникнути спрацьовування rate limit.

## Приклади коду

Наведені нижче приклади демонструють, як зчитувати `BLOCKVECTRA_API_KEY` зі змінного середовища та звертатися до ендпоінтів поповнення в Node.js і Python.

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

## Наступні кроки

* [Запит балансу (`GET /v1/account`)](https://docs.blockvectra.com/en/guides/billing-rules/#query-balance-get-v1account) для перевірки балансу вашого акаунта та залишку Compute Units (CU).
* [Правила тарифікації](https://docs.blockvectra.com/en/guides/billing-rules/) для ознайомлення з обліком Compute Units (CU), обмеженнями швидкості та помилками, що не тарифікуються.
* [Посібник з безкоштовного плану](https://docs.blockvectra.com/en/guides/free-plan/) для ознайомлення з лімітами безкоштовного рівня та правилами оновлення.
* [Посібник з програмної реєстрації](https://docs.blockvectra.com/en/guides/programmatic-signup/) для створення акаунтів та надання API key за допомогою підписів гаманця.