# USDC / USDT / USDG で RPC 料金を支払う：AI エージェント向けプログラムによるチャージ

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

開発者と AI エージェントは、HTTP 経由で RPC および Data API アカウントにチャージできます。利用可能なネットワークとトークンを確認し、既存の API key を使用してアカウントの EVM 入金アドレスを取得し、資金を送金した後に反映ステータスをポーリングします。チャージを行う前に、[料金ページ](https://blockvectra.com/en/pricing/)を確認し、[CU 重み付けから RPC および Data API のコストを見積もって](https://docs.blockvectra.com/en/guides/reading-cu-pricing/)ください。

## 請求（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` ヘッダーは**サーバー側の環境からのみ呼び出すことができます**。クライアント側のブラウザコードからチャージエンドポイントを呼び出さないでください。また、フロントエンドバンドル、公開リポジトリ、AI チャットの会話に API key を絶対に露出させないでください。


## 事前準備

* **既存の API key**：認証付きのチャージエンドポイントを呼び出すには、有効な BlockVectra RPC API key が必要です。まだ API key をお持ちでない場合は、[プログラムによる登録ガイド](https://docs.blockvectra.com/en/guides/programmatic-signup/)に従って Ethereum ウォレット署名で登録してキーを作成するか、[コンソール](https://console.blockvectra.com/login/?next=%2Fkeys%2F)で作成してください。
* **オンチェーン資産**：エージェント環境または送金元ウォレットに、対応ネットワーク上で `GET /v1/topup/status` にリストされている USDC / USDT / USDG と、トランザクションをブロードキャストするのに十分なネイティブガストークンを保持している必要があります。
* **環境変数**：キーを `BLOCKVECTRA_API_KEY` 環境変数に保存します。

認証付きのチャージエンドポイントは、RPC 呼び出しで使用されるのと同じ API key を使用して、`x-api-key` ヘッダーを直接受け付けます。ブラウザセッションは不要です。

## 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`）から読み取ってください。

チャージエンドポイント（ステータス、入金アドレス、および入金記録）は、本番 API ホストを使用します：

```
https://api.blockvectra.com
```

プランの制限と価格設定パラメータは、`https://console-api.blockvectra.com` の Console API（[GET https://console-api.blockvectra.com/v1/plans](https://console-api.blockvectra.com/v1/plans) など）によって提供されます。

### 1. 利用可能性の確認（GET /v1/topup/status）

送金を開始する前に、グローバルなチャージステータスを確認し、現在どのネットワークとトークンが利用可能かを確認し、有効な最低入金額のしきい値を読み取ります。このエンドポイントは公開されており、認証情報は不要です。

```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 桁）。最低入金額のしきい値は動的です。常に `GET https://api.blockvectra.com/v1/topup/status` によってリアルタイムで返される `min_deposit_usd` を参照してください。

有効な `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 入金アドレスを取得または割り当て、対応しているネットワークとトークンコントラクトを確認します。このエンドポイントには `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`：自身のアカウント専用の EIP-55 チェックサム付き EVM 入金アドレス。
* `deposits_url`：顧客の入金記録を照会するための URL。
* `networks`：利用可能な EVM ネットワークのリスト。閉鎖されたネットワークは省略されます。チェーン識別子 `chain`、EVM チェーン ID `chain_id`、表示名 `name`、ブロック取り込み後の標準的な反映遅延秒数 `typical_credit_seconds`、およびブロックエクスプローラーのトランザクション URL テンプレート `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`）は、標準的な 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. オンチェーントランスファーのブロードキャスト

エージェントのウォレットまたはスクリプトを使用して、ステップ 2 で取得した入金先 `address` に対して ERC-20 `transfer` トランザクションを送信します。

送金要件：

* そのネットワークの `tokens` 配列にリストされているトークンとコントラクトのみを送信してください。
* 送金額が `min_amount_raw`（`GET /v1/topup/deposit-address` から返された実際の値、または `GET /v1/topup/status` から返された `min_deposit_usd` に準拠）以上であることを確認し、そのネットワーク上のトークンの `decimals` に従ってフォーマットしてください。
* 非対応のチェーンに送信された送金や、正しくないトークンでの送金は自動的に反映できません。ブロードキャストする前にネットワークとトークンコントラクトを検証してください。
* 送信後、オンチェーンのトランザクションハッシュ（`tx_hash`）を記録してください。

### 4. 入金記録のポーリングと反映の確認（GET /v1/topup/deposits）

トランザクションがブロックに含まれた後、入金履歴を照会して反映ステータスを追跡します。このエンドポイントには `x-api-key` が必要であり、サーバー側専用です。

#### クエリパラメータ

* `limit`：1 ページあたりに返す入金記録の件数。デフォルトは `20`、有効な範囲は `1`〜`100` です。
* `before`：`deposit_id` に基づくカーソルページネーションパラメータ。前ページのレスポンスの `next_before` 値を渡して、それ以前の記録の次ページを取得します。
* `tx_hash`：特定の送金を絞り込むための、オプションの 0x プレフィックス付き 64 文字の十六進数トランザクションハッシュ。

トランザクションハッシュ（`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`：クエリパラメータに一致する入金記録の配列。
* `next_before`：さらに記録が存在する場合の次ページのカーソル ID。それ以前の記録がない場合は `null`。カーソルベースのページネーションを行うには、`before` クエリパラメータと組み合わせます。

入金の `status` の値：

* `processing`：オンチェーンで送金を検知し、反映処理中です。
* `credited`：アカウント残高に反映されました。`credited_units` と `credited_cu` は反映された数量を示します。
* `not_credited`：送金を反映できません。`reason` フィールドが原因を示します：
  * `below_minimum`：入金額が最低しきい値を下回っています。
  * `large_amount`：入金額がしきい値を超えており、手動確認が必要です。
  * `other`：その他の反映例外。

反映の遅延とポーリングのガイダンス：

* **到着および反映時間**：反映時間は、ステップ 2 で返された `typical_credit_seconds` に準拠します。
* **ポーリング間隔**：レート制限のトリガーを回避するため、**20〜60 秒ごと**の推奨間隔でポーリングしてください。それ以上の高頻度では行わないでください。

## コード例

以下の例では、環境変数から `BLOCKVECTRA_API_KEY` を読み取り、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)で、アカウント残高と残りのコンピュートユニット（CU）を確認します。
* [請求ルール](https://docs.blockvectra.com/en/guides/billing-rules/)で、コンピュートユニット（CU）の計測、レート制限、および課金対象外のエラーを確認します。
* [無料プランガイド](https://docs.blockvectra.com/en/guides/free-plan/)で、無料枠の制限とアップグレードルールを確認します。
* [プログラムによる登録ガイド](https://docs.blockvectra.com/en/guides/programmatic-signup/)で、ウォレット署名を使用したアカウント作成と API key のプロビジョニングを確認します。