課金されないもの：エラーコードと課金ルール

BlockVectra はリクエストを Compute Units（CU）単位で計測します。JSON-RPC および Data API の呼び出しは、レスポンスが得られた後にのみ課金されます。このガイドでは、HTTP ステータスコード、JSON-RPC 呼び出し、Data API における課金判定ルールと、開発者向けの推奨される対応をまとめます。

HTTP ステータスコードと課金ルール

HTTP レベルのレスポンスに対する課金判定および処理ルールは以下のとおりです：

注記：Cloudflare 経由でアクセスした場合、Cloudflare が 52x や 1015 のエラーページを返すことがありますが、これらは当サービスによって生成されたものではありません。

課金と残高のレスポンスヘッダー：HTTP リクエスト（JSON-RPC と Data API の両方に適用可能）で x-bv-meter: 1 を送信すると、少なくとも 1 回の呼び出しが課金されたレスポンスにおいて、x-bv-cu-charged（このリクエストで課金された Compute Units、またはバッチ内で課金された呼び出しの合計）と x-bv-balance-units（この課金直後のアカウントの残り残高ユニット。過払い時はマイナス。残高が不明な場合は省略）が返されます。x-bv-meter: 1 のないリクエスト、課金が発生しなかったレスポンス、402、403、429、503 のエラーレスポンスでは、両ヘッダーとも省略されます。これらのレスポンスヘッダーは CORS 経由でブラウザスクリプトからアクセス可能ですが、WebSocket では使用されません。残高は未決済の総利用量を整数ユニットに 1 回切り上げて差し引きます。毎時の決済では切り捨てられるため、決済後に報告される残高が最大 1 ユニット増加する場合があります。

JSON-RPC エラーコードと課金ルール

同一のエラーコードでもプラットフォームまたはノードのいずれかから発生する可能性があり、課金が異なります：

• プラットフォーム自体によって生成されたエラー：一切課金されません。
• ノードから返されたエラー：そのまま透過され、メソッドの重み付けで課金されます。ただし、以下に記載するノードエラーコードのみが例外となります。

ルールの詳細

• 課金されないノードエラー：ノードの -32002（バッチタイムアウト）、-32003（バッチレスポンスが大きすぎる）、および -32600（バッチ全体が拒否された）は、ノードが処理を早期に破棄したことを示し、これらおよび同じバッチ内の通知は課金されません。ノードの -32601（公開メソッドが未実装）および -32603（ノード内部障害）は HTTP または WebSocket 経由で課金されず、バッチ内の他のコールや通知には影響しません。さらに、4444（プルーニングされたブロック）および -32000（GET /v1/chains の state_window_blocks で定義されるノードの状態履歴ウィンドウ外の過去の状態）は課金されず、バッチ内の他のコールには影響しません。
• 課金されるノードエラー：チェーンの結果を報告するノードからのその他のエラーは、メソッドの重み付けで課金されます。たとえば execution reverted（-32000 または data 付きの 3）、ノード独自の -32602 invalid argument などです。
• 残高受付と同期：-32020 はアカウントの残高不足を示し、チャージが必要です。残高が判明している場合、error.data.balance_units と error.data.balance_cu に残り残高（マイナスの場合あり）が含まれます。新規作成されたキーは数秒間 -32021（503）を返す場合があります。Retry-After を待って再試行してください。
• アップストリーム障害：アップストリームとの通信障害または不正なレスポンス（upstream unavailable、no response from upstream、malformed upstream response）が原因でプラットフォームが生成した -32603 には、data.reason: upstream_unavailable が付与されます。
• 通知の課金：通知（204）は、そのメソッドの重み付けで課金されます。

JSON-RPC エラーコード表

Data API の課金ルール

Data API は読み取り専用のチェーンデータを REST エンドポイントにラップします。その課金とエラー処理は以下のルールに従います：

ルールの詳細

• 課金されるのは 2xx の成功レスポンスのみです。
• 対応範囲外の利用できない操作（非対応チェーンやトレースカバレッジ外のブロックなど）は HTTP 422 no_coverage を返します。これは課金されませんが、レート制限にはカウントされます。
• HTTP 401、402、404、および 429 のレスポンスは課金されません。レスポンスヘッダー（x-bv-meter: 1）については、HTTP ステータスコードと課金ルールを参照してください。

Data API ステータスコード表

残高の照会（GET /v1/account）

API key の所有者は、課金が発生したり Compute Units（CU）が差し引かれたりすることなく、残高とキーのクォータ詳細を直接確認できます：

curl -H "x-api-key: $BLOCKVECTRA_API_KEY" https://api.blockvectra.com/v1/account

• 無料で課金対象外：GET /v1/account は無料です。課金されることはなく、CU も差し引かれません。残高がゼロやマイナスの場合でも HTTP 200 で現在の残高を返します（402 を返すことはありません）。
• 認証：キー認証には x-api-key ヘッダーのみを使用します（パスキーや Bearer トークンは受け付けられません）。ヘッダーがない場合は 401 missing_api_key が返され、無効または失効したキーの場合は 401 invalid_api_key が返されます。（期限切れのキーは 403 key_expired を返し、一時的なサービス利用不可の場合は Retry-After 付きの 503 auth_unavailable または billing_unavailable を返します。）
• レート制限：キー ID ごとに 1 秒あたり 5 リクエストという個別の制限があり、CU の計測や課金とは独立しています。制限を超えると、Retry-After ヘッダー付きの HTTP 429 rate_limited が返されます。

レスポンスフィールド：

• key_id：API key の識別子文字列。
• plan：アカウントプランのタイプ（アカウントに無料プランのコールレート枠がある場合は free、それ以外は paid）。
• balance_units：アカウントの残り残高ユニット（ゼロまたはマイナスの可能性あり）。
• balance_cu：Compute Units（CU）に換算した残り残高。
• balance_as_of_age_ms：データソースから残高が読み取られてからの経過ミリ秒数。
• key：キー固有の制限とクォータ詳細：
  • cu_per_sec：1 秒あたりの CU トークンバケット補充レート。
  • burst_cu：CU トークンバケットのバースト容量。
  • cu_cap：このキーの有効期間全体の CU 上限（上限がない場合は null）。
  • cu_cap_remaining：cu_cap の下で残っている CU（上限がない場合は null、ゼロまたはマイナスの可能性あり）。
  • expires_at：RFC 3339 形式の有効期限タイムスタンプ（キーが無期限の場合は null）。

レスポンス例：

{
  "key_id": "<key_id>",
  "plan": "<plan>",
  "balance_units": <integer>,
  "balance_cu": <integer>,
  "balance_as_of_age_ms": <integer>,
  "key": {
    "cu_per_sec": <integer>,
    "burst_cu": <integer>,
    "cu_cap": <integer_or_null>,
    "cu_cap_remaining": <integer_or_null>,
    "expires_at": "<expires_at_or_null>"
  }
}

料金とアップグレード

課金されるすべての呼び出しの具体的な費用は、公開されている CU 重み付けによって決定されます：

• すべてのメソッドと操作の重み付けを確認するには、メソッド重み付け表および JSON-RPC CU 計測ルールを参照してください。
• プランの料金と決済の詳細については、料金ページを参照してください。
• 有料プランへのアップグレード：有料チャージを行うと無料プランの 1 秒あたりのコール数上限が解除されます。各キーは引き続き CU レートおよびバースト制限の対象となります。

オンチェーンでのチャージ手順

アカウントの残高が不足している場合や、より高いスループットが必要な場合は、コンソールで以下の手順に従ってオンチェーンでチャージしてください：

1. コンソールにログイン：BlockVectra コンソールにログインします。
2. 請求ページに移動：請求ページに移動します。
3. 専用アドレスを取得：オンチェーンチャージカードで、アカウント専用のチャージアドレスをコピーするか、QR コードをスキャンします。
4. 資金を送金：ページに記載されている対応ネットワークおよび USDC / USDT / USDG のみを使用して送金してください。対応ネットワークと最低チャージ額はコンソールに表示されます。
5. 自動クレジット付与：オンチェーンで検出されるとトランザクションは「処理中」と表示され、入金が確認されるとクレジットが残高に自動的に追加されます。

重要な注意事項：

• コンソールに明示的に記載されているネットワークとトークンのみを使用してください。サポートされていないチェーンや誤ったトークンによる送金は、自動的に反映されません。
• 各送金がコンソールに示されている最低チャージ額を満たしていることを確認してください。
• 初回の有料チャージが反映されると、アカウントは有料アカウントにアップグレードされ、無料プランの 1 秒あたりのコール数上限が解除されます。

エージェントやサーバープログラムは、API key を使用してチャージエンドポイントを直接呼び出すことができます。Agent プログラムによるチャージガイドを参照してください。

Webhook プッシュの課金

Push には、配信済みデータイベント、成功した履歴クエリ、および課金対象のアドレス日に対して個別の重み付けがあります。イベント履歴以外の管理呼び出し、失敗した配信試行、自動再試行、制御イベントは無料です。配信された各イベントは 1 回課金されます。ユーザーによる replay や、reorg（チェーンの再編成）後に再配信された正規チェーンのイベントは、新しい課金対象の配信となります。アドレス課金は、UTC 日内にオンラインだった各購読の最大アドレス数を使用します。アカウントの無料アドレス枠は購読間で共有され、より古い購読が優先して使用します。2 つの購読に含まれるアドレスは 2 回カウントされます。チェーンを追加するとイベント料金が変わりますが、アドレス料金は変わりません。

設定、署名検証、配信復旧については、ブロックチェーン Webhook API ガイドを参照してください。ステーブルコイン決済ガイドでは受領確認とポーリングによるバックフィルを扱っています。WebSocket サブスクリプションは独自の接続と通知の計測を使用します。リクエストエラーはエラーリファレンスに記載されています。以下の重み付けは GET /v1/plans から取得されたものです。

次のステップ

• データセットディレクトリを見ると、BlockVectra がインデックスしているすべてのデータセットを確認できます。
• 無料プランと料金を見ると、アカウントに含まれる内容を確認できます。
• コンソールにログインして、API key を作成してください。