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

Разработчики и ИИ-агенты могут пополнять аккаунт RPC и Data API через HTTP: проверять доступные сети и токены, использовать существующий API key для получения EVM-адреса депозита аккаунта, а затем опрашивать статус зачисления после перевода средств. Перед пополнением ознакомьтесь со страницей цен и оцените затраты на RPC и Data API по весам CU.

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

Варианты доступа для агентов.

Получите адрес депозита в разделе Billing

Войдите в систему, откройте Billing для получения адреса депозита и используйте адрес депозита и реквизиты токенов, указанные для вашего аккаунта. Перед переводом средств проверьте текущие сети, токены и минимальный депозит в GET /v1/topup/status.

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

• Существующий API key: для вызова аутентифицированных эндпоинтов пополнения требуется активный API key BlockVectra RPC. Если у вас еще нет API key, следуйте руководству по программной регистрации, чтобы зарегистрироваться и создать ключ с помощью подписи кошелька Ethereum, либо создайте ключ в консоли.
• Ончейн-активы: среда вашего агента или кошелек финансирования должны содержать USDC / USDT / USDG, перечисленные в GET /v1/topup/status в поддерживаемой сети, а также достаточное количество нативных токенов газа для отправки транзакций.
• Переменная окружения: сохраните ключ в переменной окружения BLOCKVECTRA_API_KEY.

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

Четыре этапа пополнения

После зачисления первого платного пополнения периодические бесплатные пополнения цикла прекращаются, неиспользованные бесплатные кредиты остаются доступными, а ограничение частоты вызовов на уровне аккаунта снимается; лимиты частоты вызовов на уровне каждого ключа остаются без изменений. См. правила тарификации и правила бесплатного тарифа; актуальные лимиты и минимальную сумму пополнения можно запросить через GET /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).

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

Перед инициацией перевода проверьте глобальный статус пополнения, узнайте, какие сети и токены открыты в данный момент, и получите действующий порог минимального депозита. Этот эндпоинт публичный и не требует учетных данных.

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

Пример ответа (выбранные сети и токены):

{
  "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 напрямую:

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

2. Получение адреса депозита и параметров (GET /v1/topup/deposit-address)

Получите или выделите клиентский EVM-адрес депозита и просмотрите поддерживаемые сети и контракты токенов. Этот эндпоинт требует аутентификации с заголовком x-api-key и должен вызываться только из серверных сред.

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

Пример ответа (выбранные сети и токены):

{
  "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 (ориентируйтесь на фактическое значение, возвращенное эндпоинтом; не рассчитывайте фиксированный масштаб).

Ответы с ошибками

Аутентифицированные эндпоинты пополнения (/v1/topup/deposit-address и /v1/topup/deposits) возвращают стандартные структуры ошибок JSON:

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

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

Полный список кодов ошибок см. в Справочнике ошибок.

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) для проверки вашего конкретного перевода:

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

Пример ответа:

{
  "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)

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

Следующие шаги

• Запрос баланса (GET /v1/account), чтобы проверить баланс аккаунта и оставшиеся Compute Units (CU).
• Правила тарификации, чтобы ознакомиться с учетом Compute Units (CU), лимитами запросов и нетарифицируемыми ошибками.
• Руководство по бесплатному тарифу, чтобы ознакомиться с лимитами бесплатного уровня и правилами перехода.
• Руководство по программной регистрации, чтобы создавать аккаунты и выпускать API key с помощью подписей кошелька.