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

> Source: https://docs.blockvectra.com/th/guides/agent-topup/

นักพัฒนาและ AI Agent สามารถเติมเงินบัญชี RPC และ Data API ผ่าน HTTP ได้: ตรวจสอบเครือข่ายและโทเค็นที่เปิดให้บริการ ใช้ API key ที่มีอยู่เพื่อดึงที่อยู่สำหรับฝากบน EVM ของบัญชี จากนั้นโพลตรวจสอบสถานะเครดิตหลังจากโอนเงิน ก่อนเติมเงิน โปรดตรวจสอบ [หน้าราคา](https://blockvectra.com/en/pricing/) และ [ประเมินค่าใช้จ่าย RPC และ Data API จากน้ำหนัก CU](https://docs.blockvectra.com/en/guides/reading-cu-pricing/)

* **ขั้นตอนแรก:** รัน `curl -s https://api.blockvectra.com/v1/topup/status` เพื่อตรวจสอบเครือข่าย, โทเค็นที่เปิด และ `min_deposit_usd` ก่อนโอนเงิน
* **เสร็จสมบูรณ์เมื่อ:** บันทึกการฝากสำหรับ `tx_hash` ของคุณมี `status: credited`; โดย `credited_units` และ `credited_cu` แสดงเครดิตที่เพิ่มเข้าไปในบัญชีของคุณ

[ตัวเลือกการเข้าถึงของ Agent](https://blockvectra.com/en/agents/)

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

เข้าสู่ระบบ, [เปิด Billing เพื่อรับที่อยู่สำหรับฝากของคุณ](https://console.blockvectra.com/login/?next=%2Fbilling%2F) และใช้ที่อยู่สำหรับฝากรวมถึงรายละเอียดโทเค็นที่แสดงสำหรับบัญชีของคุณ ตรวจสอบเครือข่าย, โทเค็นปัจจุบัน และยอดฝากขั้นต่ำได้ที่ [GET /v1/topup/status](https://api.blockvectra.com/v1/topup/status) ก่อนโอนเงิน

> **ความปลอดภัยของ API key และข้อกำหนดฝั่งเซิร์ฟเวอร์**
>
> ส่วนหัว `x-api-key` **สามารถเรียกจากสภาพแวดล้อมฝั่งเซิร์ฟเวอร์เท่านั้น** ห้ามเรียกใช้ endpoint การเติมเงินจากโค้ดเบราว์เซอร์ฝั่งไคลเอนต์เด็ดขาด และห้ามเปิดเผย API key ของคุณในบันเดิลฝั่งฟรอนต์เอนด์, รีโพซิทอรีสาธารณะ หรือการสนทนาในแชท AI


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

* **API key ที่มีอยู่**: การเรียก endpoint การเติมเงินที่มีการยืนยันตัวตนจำเป็นต้องมี BlockVectra RPC API key ที่ใช้งานได้ หากคุณยังไม่มี API key โปรดทำตาม [คู่มือการลงทะเบียนแบบเป็นโปรแกรม](https://docs.blockvectra.com/en/guides/programmatic-signup/) เพื่อลงทะเบียนและสร้างคีย์โดยใช้ลายเซ็นกระเป๋าเงิน Ethereum หรือสร้างคีย์ใน [คอนโซล](https://console.blockvectra.com/login/?next=%2Fkeys%2F)
* **สินทรัพย์บนเชน**: สภาพแวดล้อม agent หรือกระเป๋าเงินสำหรับเติมเงินของคุณต้องถือครอง USDC / USDT / USDG ที่ระบุไว้ใน `GET /v1/topup/status` บนเครือข่ายที่รองรับ พร้อมด้วยโทเค็น native gas ที่เพียงพอสำหรับการบรอดแคสต์ธุรกรรม
* **ตัวแปรสภาพแวดล้อม**: จัดเก็บคีย์ของคุณในตัวแปรสภาพแวดล้อม `BLOCKVECTRA_API_KEY`

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

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

เมื่อการเติมเงินแบบชำระเงินครั้งแรกได้รับการบันทึกเครดิตแล้ว การเติมเครดิตตามรอบฟรีจะหยุดลง เครดิตฟรีที่ยังไม่ได้ใช้จะยังคงใช้งานได้ และเพดานอัตราการเรียกในระดับบัญชีจะถูกยกเลิก ส่วนขีดจำกัดอัตราต่อคีย์จะยังคงเหมือนเดิม ดู [กฎการกำหนดราคา](https://blockvectra.com/en/pricing/) และ [กฎแพ็กเกจฟรี](https://blockvectra.com/en/free/#rules); ตรวจสอบขีดจำกัดปัจจุบันและการเติมเงินขั้นต่ำได้จาก [GET /v1/plans](https://console-api.blockvectra.com/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](https://console-api.blockvectra.com/v1/plans))

### 1. ตรวจสอบความพร้อมใช้งาน (GET /v1/topup/status)

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

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

ตัวอย่างการตอบกลับ (เครือข่ายและโทเค็นที่เลือก):

```json
{
  "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` ที่ใช้งานอยู่โดยตรง:

```bash
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` และต้องเรียกจากสภาพแวดล้อมฝั่งเซิร์ฟเวอร์เท่านั้น

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

ตัวอย่างการตอบกลับ (เครือข่ายและโทเค็นที่เลือก):

```json
{
  "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 อย่าคาดเดาเอาเอง)

> **ทศนิยมของโทเค็นและการแปลงจำนวนเงิน**
>
> โทเค็นเดียวกันอาจมีจำนวนทศนิยมแตกต่างกันในแต่ละเชน (ตัวอย่างเช่น USDT และ USDC บน BSC มี 18 ทศนิยม ในขณะที่ USDC บน Base มี 6 ทศนิยม) การคำนวณจำนวนเงินต้องใช้ค่า `decimals` ที่ส่งคืนสำหรับเครือข่ายนั้นๆ แทนที่จะฮาร์ดโค้ดค่าทศนิยมของโทเค็นเพียงค่าเดียว


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

endpoint การเติมเงินที่ต้องยืนยันตัวตน (`/v1/topup/deposit-address` และ `/v1/topup/deposits`) จะส่งคืนโครงสร้างข้อผิดพลาด JSON มาตรฐาน:

* **HTTP 401 (การยืนยันตัวตนล้มเหลว)**: ส่งคืนเมื่อไม่มีส่วนหัว `x-api-key` (`missing_api_key`) หรือคีย์ไม่ถูกต้อง ถูกเพิกถอน หรือถูกปิดใช้งาน (`invalid_api_key`):

```json
{
  "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`):

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

สำหรับรายการรหัสข้อผิดพลาดทั้งหมด โปรดดู [ข้อมูลอ้างอิงข้อผิดพลาด](https://docs.blockvectra.com/en/errors/)

### 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`) เพื่อตรวจสอบการโอนเฉพาะของคุณ:

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

ตัวอย่างการตอบกลับ:

```json
{
  "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)

```javascript
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)

```python
# 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`)](https://docs.blockvectra.com/en/guides/billing-rules/#query-balance-get-v1account) เพื่อตรวจสอบยอดคงเหลือในบัญชีของคุณและ Compute Units (CU) ที่เหลืออยู่
* [กฎการเรียกเก็บเงิน](https://docs.blockvectra.com/en/guides/billing-rules/) เพื่อตรวจสอบการวัดปริมาณ Compute Unit (CU), การจำกัดอัตรา และข้อผิดพลาดที่ไม่คิดค่าบริการ
* [คู่มือแพ็กเกจฟรี](https://docs.blockvectra.com/en/guides/free-plan/) เพื่อตรวจสอบขีดจำกัดระดับฟรีและกฎการอัปเกรด
* [คู่มือการลงทะเบียนแบบเป็นโปรแกรม](https://docs.blockvectra.com/en/guides/programmatic-signup/) เพื่อสร้างบัญชีและจัดเตรียม API key โดยใช้ลายเซ็นกระเป๋าเงิน