ชำระค่าบริการ RPC ด้วย USDC / USDT / USDG: การเติมเงินแบบเป็นโปรแกรมสำหรับ AI Agent

นักพัฒนาและ AI Agent สามารถเติมเงินบัญชี 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 แสดงเครดิตที่เพิ่มเข้าไปในบัญชีของคุณ

ตัวเลือกการเข้าถึงของ Agent

รับที่อยู่สำหรับฝากของคุณใน Billing

เข้าสู่ระบบ, เปิด Billing เพื่อรับที่อยู่สำหรับฝากของคุณ และใช้ที่อยู่สำหรับฝากรวมถึงรายละเอียดโทเค็นที่แสดงสำหรับบัญชีของคุณ ตรวจสอบเครือข่าย, โทเค็นปัจจุบัน และยอดฝากขั้นต่ำได้ที่ GET /v1/topup/status ก่อนโอนเงิน

ข้อกำหนดเบื้องต้น

• API key ที่มีอยู่: การเรียก endpoint การเติมเงินที่มีการยืนยันตัวตนจำเป็นต้องมี BlockVectra RPC API key ที่ใช้งานได้ หากคุณยังไม่มี API key โปรดทำตาม คู่มือการลงทะเบียนแบบเป็นโปรแกรม เพื่อลงทะเบียนและสร้างคีย์โดยใช้ลายเซ็นกระเป๋าเงิน Ethereum หรือสร้างคีย์ใน คอนโซล
• สินทรัพย์บนเชน: สภาพแวดล้อม agent หรือกระเป๋าเงินสำหรับเติมเงินของคุณต้องถือครอง USDC / USDT / USDG ที่ระบุไว้ใน GET /v1/topup/status บนเครือข่ายที่รองรับ พร้อมด้วยโทเค็น native gas ที่เพียงพอสำหรับการบรอดแคสต์ธุรกรรม
• ตัวแปรสภาพแวดล้อม: จัดเก็บคีย์ของคุณในตัวแปรสภาพแวดล้อม BLOCKVECTRA_API_KEY

endpoint การเติมเงินที่ต้องยืนยันตัวตนจะรับส่วนหัว x-api-key โดยตรงโดยใช้ API key เดียวกันกับที่ใช้สำหรับการเรียก RPC โดยไม่ต้องมีเซสชันเบราว์เซอร์

เวิร์กโฟลว์การเติมเงิน 4 ขั้นตอน

เมื่อการเติมเงินแบบชำระเงินครั้งแรกได้รับการบันทึกเครดิตแล้ว การเติมเครดิตตามรอบฟรีจะหยุดลง เครดิตฟรีที่ยังไม่ได้ใช้จะยังคงใช้งานได้ และเพดานอัตราการเรียกในระดับบัญชีจะถูกยกเลิก ส่วนขีดจำกัดอัตราต่อคีย์จะยังคงเหมือนเดิม ดู กฎการกำหนดราคา และ กฎแพ็กเกจฟรี; ตรวจสอบขีดจำกัดปัจจุบันและการเติมเงินขั้นต่ำได้จาก GET /v1/plans (free, key_defaults และ pricing.min_topup_usd)

endpoint การเติมเงิน (สถานะ, ที่อยู่สำหรับฝาก และประวัติการฝาก) ใช้โปรดักชัน 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)

ก่อนเริ่มการโอนเงิน ให้ตรวจสอบสถานะการเติมเงินทั่วโลก ตรวจสอบว่าเครือข่ายและโทเค็นใดที่เปิดให้บริการอยู่ในปัจจุบัน และอ่านเกณฑ์การฝากขั้นต่ำที่ใช้งานอยู่ endpoint นี้เป็นแบบสาธารณะและไม่ต้องใช้ข้อมูลประจำตัว

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 ของลูกค้า และตรวจสอบเครือข่ายรวมถึงสัญญาโทเค็นที่รองรับ endpoint นี้ต้องมีการยืนยันตัวตนด้วย 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 ธุรกรรมบน block explorer explorer_tx_url
• tokens: โทเค็นบนเครือข่ายนี้ ประกอบด้วยสัญลักษณ์โทเค็น symbol (USDC / USDT / USDG), ที่อยู่สัญญา contract, ทศนิยมของโทเค็น decimals และจำนวนเงินฝากขั้นต่ำในหน่วยย่อยดิบ (raw atomic units) min_amount_raw (โปรดอ้างอิงจากค่าจริงที่ส่งคืนจาก endpoint อย่าคาดเดาเอาเอง)

การตอบกลับข้อผิดพลาด

endpoint การเติมเงินที่ต้องยืนยันตัวตน (/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. บรอดแคสต์การโอนบนเชน

ใช้กระเป๋าเงินหรือสคริปต์ของ agent ของคุณเพื่อส่งธุรกรรม 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)

หลังจากธุรกรรมถูกรวมไว้ในบล็อกแล้ว ให้สอบถามประวัติการโอนเงินฝากเพื่อติดตามสถานะการบันทึกเครดิต endpoint นี้ต้องใช้ x-api-key และใช้เฉพาะฝั่งเซิร์ฟเวอร์เท่านั้น

พารามิเตอร์ Query

• 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: อาร์เรย์ของบันทึกการฝากที่ตรงกับพารามิเตอร์ query
• next_before: ID เคอร์เซอร์สำหรับหน้าถัดไปเมื่อมีบันทึกเพิ่มเติม หรือ null หากไม่มีบันทึกก่อนหน้านี้ ใช้ร่วมกับพารามิเตอร์ query 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 จากสภาพแวดล้อมและสอบถาม endpoint การเติมเงินใน 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 Unit (CU), การจำกัดอัตรา และข้อผิดพลาดที่ไม่คิดค่าบริการ
• คู่มือแพ็กเกจฟรี เพื่อตรวจสอบขีดจำกัดระดับฟรีและกฎการอัปเกรด
• คู่มือการลงทะเบียนแบบเป็นโปรแกรม เพื่อสร้างบัญชีและจัดเตรียม API key โดยใช้ลายเซ็นกระเป๋าเงิน