Thanh toán cho RPC bằng USDC / USDT / USDG: nạp tiền theo chương trình cho AI Agent

Nhà phát triển và AI Agent có thể nạp tiền vào tài khoản RPC và Data API qua HTTP: kiểm tra các mạng và token đang mở, sử dụng một API key hiện có để lấy địa chỉ nạp tiền EVM của tài khoản, sau đó polling trạng thái ghi có sau khi chuyển tiền. Trước khi nạp tiền, hãy xem trang bảng giá và ước tính chi phí RPC và Data API từ trọng số CU.

Lấy địa chỉ nạp tiền của bạn trong phần Thanh toán

Đăng nhập, mở phần Thanh toán để lấy địa chỉ nạp tiền của bạn, và sử dụng địa chỉ nạp tiền cùng chi tiết token hiển thị cho tài khoản của bạn. Kiểm tra các mạng, token hiện tại và mức nạp tối thiểu tại GET /v1/topup/status trước khi chuyển tiền.

Điều kiện tiên quyết

• API key hiện có: Việc gọi các endpoint nạp tiền đã xác thực yêu cầu một API key BlockVectra RPC đang hoạt động. Nếu bạn chưa có API key, hãy làm theo Hướng dẫn đăng ký theo chương trình để đăng ký và tạo key bằng chữ ký ví Ethereum, hoặc tạo một key trong Console.
• Tài sản on-chain: Môi trường agent hoặc ví nạp tiền của bạn phải nắm giữ USDC / USDT / USDG được liệt kê bởi GET /v1/topup/status trên một mạng được hỗ trợ, cùng với đủ token gas gốc để phát sóng các giao dịch.
• Biến môi trường: Lưu trữ key của bạn trong biến môi trường BLOCKVECTRA_API_KEY.

Các endpoint nạp tiền đã xác thực chấp nhận header x-api-key trực tiếp bằng cách sử dụng cùng một API key dùng cho các lệnh gọi RPC. Không yêu cầu phiên trình duyệt.

Quy trình nạp tiền bốn bước

Sau khi khoản nạp tiền đầu tiên được ghi có, các đợt nạp lại chu kỳ miễn phí sẽ dừng lại, các khoản tín dụng miễn phí chưa sử dụng vẫn khả dụng, và giới hạn tốc độ gọi ở cấp tài khoản sẽ được gỡ bỏ; giới hạn tốc độ cho mỗi key vẫn không đổi. Xem quy tắc định giá và quy tắc gói miễn phí; đọc các giới hạn hiện tại và mức nạp tối thiểu từ GET /v1/plans (free, key_defaults, và pricing.min_topup_usd).

Các endpoint nạp tiền (trạng thái, địa chỉ nạp tiền và các khoản nạp) sử dụng host API production:

https://api.blockvectra.com

Các giới hạn gói và thông số định giá được phục vụ bởi Console API tại https://console-api.blockvectra.com (chẳng hạn như GET https://console-api.blockvectra.com/v1/plans).

1. Kiểm tra tính khả dụng (GET /v1/topup/status)

Trước khi khởi tạo giao dịch chuyển tiền, hãy xác minh trạng thái nạp tiền toàn cầu, kiểm tra mạng và token nào hiện đang mở, đồng thời đọc ngưỡng nạp tiền tối thiểu đang hoạt động. Endpoint này là công khai và không yêu cầu thông tin xác thực.

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

Phản hồi mẫu (các mạng và token được chọn):

{
  "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: Công tắc toàn cầu. Nếu là false, việc nạp tiền sẽ bị đóng trên tất cả các mạng.
• networks: Trạng thái mở của từng mạng và token. Khi enabled là false đối với một mạng hoặc token, không chuyển tiền trên mạng đó.
• min_deposit_usd: Số tiền nạp tối thiểu toàn cầu tính bằng USD được định dạng đến 6 chữ số thập phân. Ngưỡng nạp tiền tối thiểu là động: luôn tham khảo min_deposit_usd được trả về theo thời gian thực bởi GET https://api.blockvectra.com/v1/topup/status.

Để đọc trực tiếp min_deposit_usd đang hoạt động:

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

2. Lấy địa chỉ nạp tiền và các tham số (GET /v1/topup/deposit-address)

Lấy hoặc phân bổ địa chỉ nạp tiền EVM của khách hàng và kiểm tra các mạng cùng hợp đồng token được hỗ trợ. Endpoint này yêu cầu xác thực bằng x-api-key và chỉ được gọi từ các môi trường phía máy chủ.

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

Phản hồi mẫu (các mạng và token được chọn):

{
  "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: Địa chỉ nạp tiền EVM có checksum EIP-55 dành riêng cho tài khoản của bạn.
• deposits_url: URL để truy vấn các bản ghi nạp tiền của khách hàng.
• networks: Danh sách các mạng EVM đang mở. Các mạng đã đóng sẽ bị bỏ qua. Bao gồm slug chuỗi chain, Chain ID EVM chain_id, tên hiển thị name, độ trễ ghi có thông thường tính bằng giây sau khi đưa vào khối typical_credit_seconds, và mẫu URL giao dịch trên trình khám phá khối explorer_tx_url.
• tokens: Các token trên mạng này, bao gồm ký hiệu token symbol (USDC / USDT / USDG), địa chỉ hợp đồng contract, số chữ số thập phân của token decimals, và số tiền nạp tối thiểu theo đơn vị nguyên tử thô min_amount_raw (tham khảo giá trị thực tế do endpoint trả về; không giả định một số tiền đã chia tỷ lệ).

Phản hồi lỗi

Các endpoint nạp tiền đã xác thực (/v1/topup/deposit-address và /v1/topup/deposits) trả về cấu trúc lỗi JSON tiêu chuẩn:

• HTTP 401 (Lỗi xác thực): Được trả về khi thiếu header x-api-key (missing_api_key) hoặc key không hợp lệ, đã bị thu hồi hoặc bị vô hiệu hóa (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 (Nạp tiền bị vô hiệu hóa): Được trả về khi việc nạp tiền bị đóng trên toàn cầu hoặc trên tất cả các mạng (topup_disabled):

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

Để biết danh sách đầy đủ các mã lỗi, hãy xem Tài liệu tham khảo lỗi.

3. Phát sóng giao dịch chuyển khoản on-chain

Sử dụng ví hoặc script của agent, gửi một giao dịch transfer ERC-20 đến address nạp tiền đã lấy ở Bước 2.

Yêu cầu chuyển tiền:

• Chỉ gửi các token và hợp đồng được liệt kê trong mảng tokens cho mạng đó.
• Đảm bảo số tiền chuyển lớn hơn hoặc bằng min_amount_raw (phụ thuộc vào giá trị thực tế do GET /v1/topup/deposit-address trả về, hoặc min_deposit_usd do GET /v1/topup/status trả về), được định dạng theo decimals của token trên mạng đó.
• Các khoản chuyển tiền được gửi đến các chuỗi không được hỗ trợ hoặc gửi sai token sẽ không thể được ghi có tự động; hãy xác minh mạng và hợp đồng token trước khi phát sóng.
• Ghi lại mã băm giao dịch on-chain (tx_hash) sau khi gửi.

4. Polling bản ghi nạp tiền và xác minh ghi có (GET /v1/topup/deposits)

Sau khi giao dịch được đưa vào một khối, hãy truy vấn lịch sử chuyển nạp tiền để theo dõi trạng thái ghi có. Endpoint này yêu cầu x-api-key và chỉ dành cho phía máy chủ.

Tham số truy vấn

• limit: Số lượng bản ghi nạp tiền trả về trên mỗi trang. Mặc định là 20, phạm vi hợp lệ là 1–100.
• before: Tham số phân trang cursor dựa trên deposit_id. Truyền giá trị next_before từ phản hồi của trang trước đó để lấy trang tiếp theo của các bản ghi cũ hơn.
• tx_hash: Mã băm giao dịch dạng thập lục phân 64 ký tự tùy chọn có tiền tố 0x để lọc cho một giao dịch chuyển tiền cụ thể.

Lọc theo hash giao dịch (tx_hash) để kiểm tra giao dịch chuyển tiền cụ thể của bạn:

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

Phản hồi mẫu:

{
  "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: Mảng các bản ghi nạp tiền khớp với các tham số truy vấn.
• next_before: ID cursor cho trang tiếp theo khi còn nhiều bản ghi hơn, hoặc null nếu không còn bản ghi cũ hơn. Kết hợp với tham số truy vấn before để phân trang dựa trên cursor.

Các giá trị status của khoản nạp tiền:

• processing: Giao dịch chuyển tiền được phát hiện on-chain, đang tiến hành ghi có.
• credited: Đã được ghi có vào số dư tài khoản. credited_units và credited_cu biểu thị số lượng đã ghi có.
• not_credited: Giao dịch chuyển tiền không thể được ghi có. Trường reason cho biết nguyên nhân:
  • below_minimum: Số tiền nạp thấp hơn ngưỡng tối thiểu.
  • large_amount: Số tiền nạp vượt quá ngưỡng và yêu cầu xét duyệt thủ công.
  • other: Ngoại lệ ghi có khác.

Hướng dẫn về độ trễ ghi có và polling:

• Thời gian đến và ghi có: Thời gian ghi có được quản lý bởi typical_credit_seconds được trả về ở Bước 2.
• Khoảng thời gian polling: Polling ở khoảng thời gian khuyến nghị là mỗi 20–60 giây, không thường xuyên hơn, để tránh kích hoạt giới hạn tốc độ.

Ví dụ mã nguồn

Các ví dụ sau minh họa cách đọc BLOCKVECTRA_API_KEY từ môi trường và truy vấn các endpoint nạp tiền trong Node.js và 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()

Các bước tiếp theo

• Truy vấn số dư (GET /v1/account) để xác minh số dư tài khoản và Compute Unit (CU) còn lại của bạn.
• Quy tắc thanh toán để xem lại cách đo lường Compute Unit (CU), giới hạn tốc độ và các lỗi không bị tính phí.
• Hướng dẫn gói miễn phí để xem lại các giới hạn của gói miễn phí và quy tắc nâng cấp.
• Hướng dẫn đăng ký theo chương trình để tạo tài khoản và cung cấp API key bằng chữ ký ví.