# Оплата RPC с помощью USDC / USDT / USDG: программное пополнение для ИИ-агентов

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

Разработчики и ИИ-агенты могут пополнять аккаунт RPC и Data API через HTTP: проверять доступные сети и токены, использовать существующий API key для получения EVM-адреса депозита аккаунта, а затем опрашивать статус зачисления после перевода средств. Перед пополнением ознакомьтесь со [страницей цен](https://blockvectra.com/ru/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/ru/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 во фронтенд-сборках, публичных репозиториях или в чатах с ИИ.


## Предварительные требования

* **Существующий API key**: для вызова аутентифицированных эндпоинтов пополнения требуется активный API key BlockVectra RPC. Если у вас еще нет 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/ru/pricing/) и [правила бесплатного тарифа](https://blockvectra.com/ru/free/#rules); актуальные лимиты и минимальную сумму пополнения можно запросить через [GET /v1/plans](https://console-api.blockvectra.com/v1/plans) (`free`, `key_defaults` и `pricing.min_topup_usd`).

Эндпоинты пополнения (статус, адрес депозита и депозиты) используют хост production 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 секунд**, но не чаще, чтобы не превышать лимиты частоты запросов.

## Примеры кода

Следующие примеры демонстрируют, как прочитать `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 с помощью подписей кошелька.