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

Розробники та AI-агенти можуть поповнювати акаунт 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: виклик автентифікованих ендпоінтів поповнення вимагає активного BlockVectra RPC API key. Якщо у вас ще немає 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).

Ендпоінти поповнення (статус, адреса депозиту та депозити) використовують продакшн-хост 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 секунд, не частіше, щоб уникнути спрацьовування rate limit.

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

Наведені нижче приклади демонструють, як зчитувати 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 за допомогою підписів гаманця.