Pay for RPC with USDC / USDT / USDG: programmatic top-up for AI agents

Top up an RPC and Data API account on-chain over HTTP. Developers and AI Agents use an API key to check supported tokens, retrieve a dedicated deposit address and poll credit status.

Developers and AI Agents can top up an RPC and Data API account over HTTP: check open networks and tokens, use an existing API key to retrieve the account's EVM deposit address, then poll credit status after transferring funds. Before funding, check the pricing page and estimate RPC and Data API costs from CU weights.

  • First step: Run curl -s https://api.blockvectra.com/v1/topup/status to check open networks and tokens before transferring funds, and read the dynamic USD minimum from pricing.min_topup_usd in GET https://console-api.blockvectra.com/v1/plans.
  • Done when: The deposit record for your tx_hash has status: credited; credited_units and credited_cu show the credits added to your account.

Agent access options.

Get your deposit address in Billing

Sign in, open Billing to get your deposit address, and use the deposit address and token details shown for your account. Check the current networks and tokens at GET /v1/topup/status, and read the dynamic USD minimum from pricing.min_topup_usd in GET /v1/plans, before transferring funds.

API key security and server-side requirement

The x-api-key header can only be called from server-side environments. Never call top-up endpoints from client-side browser code, and never expose your API key in frontend bundles, public repositories, or AI chat conversations.

Prerequisites

  • Existing API key: Calling authenticated top-up endpoints requires an active BlockVectra RPC API key. If you do not have an API key yet, follow the Programmatic sign-up guide to sign up and create a key using an Ethereum wallet signature, or create one in the Console.
  • On-chain assets: Your agent environment or funding wallet must hold USDC / USDT / USDG listed by GET /v1/topup/status on a supported network, along with sufficient native gas tokens to broadcast transactions.
  • Environment variable: Store your key in the BLOCKVECTRA_API_KEY environment variable.

The authenticated top-up endpoints accept the x-api-key header directly using the same API key used for RPC calls. No browser session is required.

Four-step top-up workflow

Once the first paid top-up is credited, free cycle refills stop, unused free credits remain available, and the account-level call-rate cap is removed; each non-revoked key's CU limits are raised to at least the paid floor and higher custom limits are kept. See the pricing rules and free plan rules; read current limits and the minimum top-up from GET /v1/plans (free, key_defaults, paid_key_minimums, and pricing.min_topup_usd).

Top-up endpoints (status, deposit address, and deposits) use the production API host:

https://api.blockvectra.com

Plan limits and pricing parameters are served by the Console API at https://console-api.blockvectra.com (such as GET https://console-api.blockvectra.com/v1/plans).

1. Check availability (GET /v1/topup/status)

Before initiating a transfer, verify global top-up status and check which networks and tokens are currently open. The USD minimum comes from pricing.min_topup_usd in GET /v1/plans, not from this endpoint. This endpoint is public and requires no credentials.

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

Example response (selected networks and tokens):

{
  "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: Global switch. If false, top-up is closed across all networks.
  • networks: Open status per network and token. When enabled is false for a network or token, do not transfer funds on that network.
  • min_deposit_usd: Secondary USD value (6 decimal places) for cross-checking against pricing.min_topup_usd from GET https://console-api.blockvectra.com/v1/plans, the authoritative dynamic USD minimum. It is not an alternative source of the minimum.

To read the authoritative dynamic USD minimum:

curl -s https://console-api.blockvectra.com/v1/plans | jq -r .pricing.min_topup_usd

2. Retrieve deposit address and parameters (GET /v1/topup/deposit-address)

Retrieve or allocate the customer EVM deposit address and inspect supported networks and token contracts. This endpoint requires x-api-key authentication and must be called from server-side environments only.

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

Example response (selected networks and tokens):

{
  "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: EIP-55 checksummed EVM deposit address dedicated to your account.
  • deposits_url: URL to query customer deposit records.
  • networks: List of open EVM networks. Closed networks are omitted. Includes chain slug chain, EVM chain ID chain_id, display name name, typical credit latency in seconds after block inclusion typical_credit_seconds, and block explorer transaction URL template explorer_tx_url.
  • tokens: Tokens on this network, including token symbol symbol (USDC / USDT / USDG), contract address contract, token decimals decimals, and minimum deposit amount in raw atomic units min_amount_raw (refer to the actual value returned by the endpoint; do not assume a scaled amount).

Token decimals and amount conversion

The same token can have different decimals on different chains (for example, USDT and USDC on BSC are 18 decimals, whereas USDC on Base is 6 decimals). Amount calculation must use the decimals returned for that specific network rather than hardcoding a single token decimal value.

Error responses

Authenticated top-up endpoints (/v1/topup/deposit-address and /v1/topup/deposits) return standard JSON error structures:

  • HTTP 401 (Authentication failure): Returned when the x-api-key header is missing (missing_api_key) or the key is invalid, revoked, or disabled (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 (Top-up disabled): Returned when top-up is closed globally or across all networks (topup_disabled):
{
  "error": {
    "code": "topup_disabled",
    "data": {
      "reason": "topup_disabled",
      "docs_url": "https://docs.blockvectra.com/en/errors/#topup_disabled",
      "retryable": false
    }
  }
}

For the complete list of error codes, see the Errors Reference.

3. Broadcast on-chain transfer

Using your agent's wallet or script, submit an ERC-20 transfer transaction to the deposit address retrieved in Step 2.

Transfer requirements:

  • Send only tokens and contracts listed in the tokens array for that network.
  • Compare the transfer amount and the selected token's returned min_amount_raw in the same raw atomic units; the transfer must be greater than or equal to that minimum. Use the token's decimals when displaying human-readable amounts. pricing.min_topup_usd from GET /v1/plans is the authoritative global USD policy (min_deposit_usd from GET /v1/topup/status is only a secondary cross-check), not token atomic quantities, and cannot be compared directly with raw integers. Read the current policy and token minimum before broadcasting; example amounts are illustrative.
  • Before broadcasting, read this run's GET /v1/plans, GET /v1/topup/status and GET /v1/topup/deposit-address responses and confirm that top-up is enabled, the network and token are open, and contract, decimals, min_amount_raw and your account's deposit address are all present and consistent. If any value is missing, closed or contradictory, stop and do not broadcast. pricing.min_topup_usd is the dynamic USD policy; any older fixed minimum is not authoritative, and $1 is only an example amount, not a minimum. Convert the amount to exact integer atomic units with decimals and compare it with min_amount_raw; do not compare USD directly with token units. The status and address calls in the code samples below only read and print values; they are not the complete pre-broadcast check.
  • Transfers sent to unsupported chains or with incorrect tokens cannot be credited automatically; verify the network and token contract prior to broadcasting.
  • Record the on-chain transaction hash (tx_hash) once submitted.

4. Poll deposit records and verify credit (GET /v1/topup/deposits)

After the transaction is included in a block, query deposit transfer history to track crediting status. This endpoint requires x-api-key and is server-side only.

Query parameters

  • limit: Number of deposit records to return per page. Default is 20, valid range is 1–100.
  • before: Cursor pagination parameter based on deposit_id. Pass the next_before value from the previous page response to fetch the next page of earlier records.
  • tx_hash: Optional 0x-prefixed 64-character hexadecimal transaction hash to filter for a specific transfer.

Filter by transaction hash (tx_hash) to inspect your specific transfer:

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

Example response:

{
  "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: Array of deposit records matching the query parameters.
  • next_before: The deposit_id of the last item when the page is full (the number of items equals limit), otherwise null. A full last page still returns a cursor; requesting it returns an empty page with next_before: null. Stop paging when next_before is null. Combine with the before query parameter for cursor-based pagination.

Deposit status values:

  • processing: Transfer detected on-chain, crediting in progress.
  • credited: Credited to the account balance. credited_units and credited_cu indicate the credited amounts.
  • not_credited: Transfer cannot be credited. The reason field indicates the cause:
    • below_minimum: Deposit amount is below the minimum threshold.
    • large_amount: Deposit amount exceeds threshold and requires manual review.
    • other: Other crediting exception.

Credit latency and polling guidance:

  • Arrival and crediting time: Credit time is governed by the typical_credit_seconds returned in Step 2.
  • Polling interval: Poll at a recommended interval of every 20–60 seconds, not more frequently, to avoid triggering rate limits.

Code examples

The following examples demonstrate how to read BLOCKVECTRA_API_KEY from the environment and query top-up endpoints in Node.js and 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; status min_deposit_usd is a secondary cross-check (USD minimum authority: GET /v1/plans pricing.min_topup_usd)
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("Status min_deposit_usd (secondary, 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; status min_deposit_usd is a secondary cross-check (USD minimum authority: GET /v1/plans pricing.min_topup_usd)
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("Status min_deposit_usd (secondary, 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()

Next steps

Last updated:

On this page