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/statusto check open networks and tokens before transferring funds, and read the dynamic USD minimum frompricing.min_topup_usdinGET https://console-api.blockvectra.com/v1/plans. - Done when: The deposit record for your
tx_hashhasstatus: credited;credited_unitsandcredited_cushow the credits added to your account.
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/statuson a supported network, along with sufficient native gas tokens to broadcast transactions. - Environment variable: Store your key in the
BLOCKVECTRA_API_KEYenvironment 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.comPlan 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/statusExample 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. Iffalse, top-up is closed across all networks.networks: Open status per network and token. Whenenabledisfalsefor a network or token, do not transfer funds on that network.min_deposit_usd: Secondary USD value (6 decimal places) for cross-checking againstpricing.min_topup_usdfromGET 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_usd2. 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-addressExample 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 slugchain, EVM chain IDchain_id, display namename, typical credit latency in seconds after block inclusiontypical_credit_seconds, and block explorer transaction URL templateexplorer_tx_url.tokens: Tokens on this network, including token symbolsymbol(USDC / USDT / USDG), contract addresscontract, token decimalsdecimals, and minimum deposit amount in raw atomic unitsmin_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-keyheader 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
tokensarray for that network. - Compare the transfer amount and the selected token's returned
min_amount_rawin the same raw atomic units; the transfer must be greater than or equal to that minimum. Use the token'sdecimalswhen displaying human-readable amounts.pricing.min_topup_usdfromGET /v1/plansis the authoritative global USD policy (min_deposit_usdfromGET /v1/topup/statusis 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/statusandGET /v1/topup/deposit-addressresponses and confirm that top-up is enabled, the network and token are open, andcontract,decimals,min_amount_rawand your account's depositaddressare all present and consistent. If any value is missing, closed or contradictory, stop and do not broadcast.pricing.min_topup_usdis the dynamic USD policy; any older fixed minimum is not authoritative, and$1is only an example amount, not a minimum. Convert the amount to exact integer atomic units withdecimalsand compare it withmin_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 is20, valid range is1–100.before: Cursor pagination parameter based ondeposit_id. Pass thenext_beforevalue 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: Thedeposit_idof the last item when the page is full (the number of items equalslimit), otherwisenull. A full last page still returns a cursor; requesting it returns an empty page withnext_before: null. Stop paging whennext_beforeisnull. Combine with thebeforequery parameter for cursor-based pagination.
Deposit status values:
processing: Transfer detected on-chain, crediting in progress.credited: Credited to the account balance.credited_unitsandcredited_cuindicate the credited amounts.not_credited: Transfer cannot be credited. Thereasonfield 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_secondsreturned 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
- Query balance (
GET /v1/account) to verify your account balance and remaining Compute Units (CU). - Billing rules to review Compute Unit (CU) metering, rate limits, and non-billed errors.
- Free plan guide to review free tier limits and upgrade rules.
- Programmatic sign-up guide to create accounts and provision API keys using wallet signatures.
Last updated: