用 USDC / USDT / USDG 支付 RPC 费用:AI Agent 程序化充值

用USDC / USDT / USDG为账户链上充值:先调用GET /v1/topup/status核对开放网络与币种,再从GET /v1/plans读取最低充值额,再用已有key获取专属充值地址,转账完成后持续轮询到账状态,直到充值记录变为已到账。

开发者与 AI Agent 可通过 HTTP 为 RPC 与 Data API 账户充值:检查开放网络与币种,使用已有 API key 获取账户专属 EVM 充值地址,转账后轮询到账状态。充值前先查看定价页,并按 CU 权重估算 RPC 与 Data API 成本。

  • 第一步:运行 curl -s https://api.blockvectra.com/v1/topup/status,转账前核对开放网络与币种;最低充值额以 GET https://console-api.blockvectra.com/v1/plans 的 pricing.min_topup_usd 为准。
  • 完成标准:对应 tx_hash 的充值记录为 status: credited,credited_units 与 credited_cu 显示账户实际增加的额度。

Agent 接入方式。

在账单页获取充值地址

登录后打开账单页获取充值地址,使用账户中显示的充值地址和币种信息。转账前通过 GET /v1/topup/status 核对当前网络与币种,并从 GET /v1/plans 的 pricing.min_topup_usd 读取动态美元最低充值额。

API key 安全与调用环境限制

x-api-key 请求头只能在服务器端调用。请勿在前端浏览器代码中调用充值接口,切勿将 API key 写入前端代码、公开仓库或 AI 对话中。

前提条件

  • 已有 API key:调用充值接口需要已激活的 BlockVectra RPC API key。若没有 key,可参考程序化开户指南使用钱包签名程序化开户并建 key,也可以在控制台创建。
  • 链上资产:程序运行环境或关联钱包中持有 GET /v1/topup/status 列出的支持网络与 USDC / USDT / USDG,并有足够的网络原生代币支付 Gas 费。
  • 环境变量:建议将 API key 注入为环境变量 BLOCKVECTRA_API_KEY。

带鉴权的充值接口直接接受 x-api-key 请求头,使用调用 RPC 所用的同一个 API key 即可,不需要浏览器。

四步充值流程

首笔付费充值到账后,停止免费周期补足,未用完的免费额度保留,解除账户级调用速率上限;每把未撤销 key 的 CU 限额至少提升到付费账户下限,更高的自定义限额保持不变。详见定价规则与免费套餐规则;当前限额与起充额从 GET /v1/plans 的 free、key_defaults、paid_key_minimums 和 pricing.min_topup_usd 读取。

充值状态、充值地址与记录查询端点统一使用生产 API 主机:

https://api.blockvectra.com

套餐限制与计费参数则由控制台 API 提供(https://console-api.blockvectra.com,即 GET https://console-api.blockvectra.com/v1/plans)。

1. 检查充值可用性(GET /v1/topup/status)

转账前先确认全局充值状态,并核对当前开放的网络与币种。美元最低充值额来自 GET /v1/plans 的 pricing.min_topup_usd,不取自本接口。本接口为公开接口,无需凭证。

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:次要的美元值(保留 6 位小数),仅用于与 GET https://console-api.blockvectra.com/v1/plans 的 pricing.min_topup_usd 交叉核对;后者才是权威的动态美元最低充值额,本字段不是最低额的替代来源。

读取权威的动态美元最低充值额:

curl -s https://console-api.blockvectra.com/v1/plans | jq -r .pricing.min_topup_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:EIP-55 校验和格式的 EVM 专属充值地址。
  • deposits_url:查询充值记录的接口地址。
  • networks:当前开放的网络列表,未开放的网络不会出现在列表中。包含链标识 chain、EVM 链 ID chain_id、网络名称 name、包含交易后的典型到账参考秒数 typical_credit_seconds、浏览器交易链接模板 explorer_tx_url。
  • tokens:该网络的币种列表,包含代币符号 symbol(USDC / USDT / USDG)、合约地址 contract、代币精度 decimals,以及原始最小转账数额 min_amount_raw(以实际返回为准,切勿自行按比例推算)。

代币精度与金额换算

同一代币在不同链上的精度不同(例如 BSC 上的 USDT 与 USDC 均为 18 位精度,而 Base 上的 USDC 为 6 位精度)。金额换算必须以该网络返回的 decimals 字段为准,切勿写死单一代币精度。

错误响应说明

带鉴权的充值接口(/v1/topup/deposit-address 与 /v1/topup/deposits)常见错误响应:

  • HTTP 401(鉴权失败):未提供 x-api-key 请求头时返回 missing_api_key;提供的 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(通道关闭):若充值通道全局关闭或所有网络均未开放,接口返回 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. 发起链上转账

通过 Agent 的钱包程序或脚本,向第 2 步获取到的专属 address 发起 ERC-20 transfer 交易。

转账要求:

  • 仅转账 tokens 列表中列出的代币合约与网络。
  • 将转账金额与所选代币返回的 min_amount_raw 按同一种原子单位比较,转账金额必须大于或等于该最小值;展示可读金额时使用对应代币的 decimals。GET /v1/plans 的 pricing.min_topup_usd 是权威的全局美元政策(GET /v1/topup/status 的 min_deposit_usd 仅作次要交叉核对),不是代币原子数量,不能直接与原始整数比较。广播前读取当前政策和代币最小值;示例金额仅供说明。
  • 广播前读取本次 GET /v1/plans、GET /v1/topup/status 与 GET /v1/topup/deposit-address 的响应,确认充值已开启、网络与代币开放,且 contract、decimals、min_amount_raw 与账户充值 address 齐全并相互一致;任一值缺失、关闭或矛盾时停止,不要广播。pricing.min_topup_usd 是动态的 USD 政策值,旧的固定最低额不作数,$1 只是示例金额,不是最低额。按 decimals 把金额换算为精确的整数原子单位后与 min_amount_raw 比较,不要把 USD 直接与代币单位比较。下方代码示例中的 status 与地址调用只读取并打印数值,不是完整的广播前校验。
  • 转错链或转错代币无法自动入账;发起转账前请务必核对网络与代币合约。
  • 转账提交后,记下链上交易哈希(tx_hash)。

4. 轮询充值记录与确认到账(GET /v1/topup/deposits)

交易在链上打包后,调用该接口查询充值记录与入账状态。该接口需要 x-api-key 鉴权,仅限服务器端调用。

查询参数说明

  • limit:单页返回的充值记录数量,默认 20,取值范围 1–100。
  • before:按 deposit_id 的游标分页参数。传入上一页响应中的 next_before 数值即可获取下一页历史记录。
  • tx_hash:可选的 0x 前缀 64 位十六进制交易哈希,用于精确过滤单笔转账。

支持通过 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:本页条数等于 limit(满页)时为最后一条的 deposit_id,否则为 null。末页恰好满页时仍会返回游标,用它请求下一页会得到空页(items: [])和 next_before: null。next_before 为 null 时停止翻页;配合 before 请求参数完成游标分页。

充值状态(status)字段取值说明:

  • processing:已在链上检测到转账,尚未到账。
  • credited:已入账并增加账户余额。credited_units 与 credited_cu 记录实际增加的额度。
  • not_credited:转账未能入账。此时 reason 字段会注明具体原因:
    • below_minimum:转账金额低于最低充值额度。
    • large_amount:大额充值触发人工核验。
    • other:其他无法入账的原因。

到账时间与轮询建议:

  • 到账时间:以第 2 步返回的 typical_credit_seconds 为准。
  • 轮询建议:建议轮询频率为每 20–60 秒一次,不要更频繁,避免触发接口频率限制。

代码集成示例

以下展示使用 Node.js 与 Python 读取环境变量 BLOCKVECTRA_API_KEY 完成充值查询的完整示例。

Node.js(fetch)

import process from "node:process";

const apiKey = process.env.BLOCKVECTRA_API_KEY;
if (!apiKey) {
  throw new Error("缺少 BLOCKVECTRA_API_KEY 环境变量");
}

const BASE_URL = "https://api.blockvectra.com";

// 1. 检查可用性;status 的 min_deposit_usd 仅作次要交叉核对(美元最低额以 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("充值通道当前已关闭");
}
const minDepositUsd = status.min_deposit_usd;
console.log("status 的 min_deposit_usd(次要,USD):", minDepositUsd);

// 2. 获取专属充值地址与开放网络
const addressRes = await fetch(`${BASE_URL}/v1/topup/deposit-address`, {
  headers: { "x-api-key": apiKey },
});

if (addressRes.status === 401) {
  throw new Error("API key 缺失或无效 (HTTP 401)");
}
if (addressRes.status === 409) {
  throw new Error("充值通道已关闭 (topup_disabled)");
}
if (!addressRes.ok) {
  throw new Error(`获取充值地址失败: ${addressRes.status}`);
}

const depositData = await addressRes.json();
console.log("专属充值地址:", depositData.address);
console.log("支持网络数:", depositData.networks.length);

// 3. 轮询充值状态函数
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("API key 缺失或无效 (HTTP 401)");
  }
  if (!res.ok) {
    throw new Error(`查询充值记录失败: ${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("缺少 BLOCKVECTRA_API_KEY 环境变量")

base_url = "https://api.blockvectra.com"

# 1. 检查可用性;status 的 min_deposit_usd 仅作次要交叉核对(美元最低额以 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("充值通道当前已关闭")
min_deposit_usd = status_data.get("min_deposit_usd")
print("status 的 min_deposit_usd(次要,USD):", min_deposit_usd)

# 2. 获取专属充值地址
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("API key 缺失或无效 (HTTP 401)")
if resp.status_code == 409:
    raise RuntimeError("充值通道已关闭 (topup_disabled)")
resp.raise_for_status()
deposit_data = resp.json()
print("专属充值地址:", deposit_data["address"])

# 3. 轮询充值状态函数
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("API key 缺失或无效 (HTTP 401)")
    resp.raise_for_status()
    return resp.json()

下一步

最后更新:

本页目录