bingx-spot-wallet

BingX Spot Wallet

BingX ウォレットの入金および出金に関する認証済みエンドポイントです。すべてのエンドポイントで HMAC SHA256 署名認証が必要です。

ベース URL： references/base-urls.md を参照 | 認証： references/authentication.md を参照

---

クイックリファレンス

エンドポイント	メソッド	説明	認証	権限
/openApi/api/v3/capital/deposit/hisrec	GET	入金履歴を照会	必要	読み取り
/openApi/api/v3/capital/withdraw/history	GET	出金履歴を照会	必要	読み取り
/openApi/wallets/v1/capital/config/getall	GET	コインの入金・出金設定（ネットワーク、上限、手数料）を照会	必要	読み取り
/openApi/wallets/v1/capital/withdraw/apply	POST	出金を開始	必要	出金
/openApi/wallets/v1/capital/deposit/address	GET	メインアカウントの入金アドレスを照会	必要	読み取り
/openApi/wallets/v1/capital/deposit/riskRecords	GET	入金リスク管理記録を照会	必要	読み取り

---

パラメーター

入金履歴のパラメーター

• coin：コイン名（例：USDT、BTC）。省略可能です。省略するとすべてのコインが返されます
• status：入金ステータスで絞り込みます（DepositStatus enum を参照）
• startTime：期間の開始時刻（ミリ秒）（例：1658748648396）
• endTime：期間の終了時刻（ミリ秒）
• offset：ページネーションのオフセット。デフォルトは 0 です
• limit：ページサイズ。デフォルトは 1000、最大は 1000 です
• txId：ブロックチェーントランザクション ID で絞り込みます
• recvWindow：リクエストの有効期間（ミリ秒）。最大は 60000 です

出金履歴のパラメーター

• id：出金記録の一意の ID
• coin：コイン名。省略可能です
• withdrawOrderId：送信時に割り当てられたカスタム出金 ID
• status：出金ステータスで絞り込みます（WithdrawalStatus enum を参照）
• startTime / endTime：期間（ミリ秒）
• offset：ページネーションのオフセット。デフォルトは 0 です
• limit：ページサイズ。デフォルトは 1000 です
• txId：ブロックチェーントランザクション ID で絞り込みます

出金申請のパラメーター

• coin：コイン名（必須。例：USDT）
• network：ネットワーク名（例：BEP20、ERC20）。省略した場合はデフォルトが使用されます
• address：出金先アドレス（必須）
• addressTag：必要なコイン（例：XRP、EOS）に使用するメモまたはタグ
• amount：出金額（必須）
• walletType：送金元アカウントの種類（必須。WalletType enum を参照）
• withdrawOrderId：カスタム出金 ID（省略可能。冪等性のために使用）
• vaspEntityId：決済プラットフォーム情報（省略可能。トラベルルールへの準拠に使用）
• recipientLastName / recipientFirstName：受取人の英語名（省略可能。トラベルルール用）
• dateOfbirth：受取人の生年月日。形式は YYYY-MM-DD です（省略可能。トラベルルール用）

入金アドレスのパラメーター

• coin：コイン名（必須）
• offset：開始レコード番号。デフォルトは 0 です
• limit：ページサイズ。デフォルトは 100、最大は 1000 です

列挙型

DepositStatus（入金記録のステータス）：

• 0 — 処理中
• 1 — 未入金
• 2 — 金額誤り
• 6 — チェーンで承認済み／完了

WithdrawalStatus（出金記録のステータス）：

• 4 — 審査中
• 5 — 失敗
• 6 — 完了

WalletType（出金元アカウント）：

• 1 — 資金口座（スポット）
• 2 — 標準コントラクト口座
• 3 — 無期限先物口座

パラメータの検証ルール

不要な API エラーを避けるため、リクエストを送信する前にクライアント側でパラメータを検証してください。

• coin：大文字の英字と数字のみ。パターンは ^[A-Z0-9]{1,20}$（例：USDT、BTC）
• address：空でない文字列。最大 200 文字。対象ネットワークで有効なブロックチェーンアドレスである必要があります
• amount：正の数（> 0）である必要があります。コイン／ネットワークの最小出金額を満たす必要があります（コインネットワーク設定エンドポイントから照会）
• network：大文字のネットワーク識別子（例：ERC20、BEP20、TRC20）。コインでサポートされているネットワークと一致する必要があります
• addressTag：コインで必要な場合（例：XRP、EOS）、空でない文字列である必要があります。最大 128 文字
• limit：整数、1～1000。履歴のデフォルトは 1000、アドレスのデフォルトは 100
• startTime ／ endTime：ミリ秒単位の Unix タイムスタンプ。endTime は startTime 以上である必要があります。範囲は最大 90 日です
• recvWindow：整数、1～5000 ms。できるだけ小さくしてください（リプレイ保護を参照）
• timestamp：ミリ秒単位の Unix 時刻。サーバー時刻との差が recvWindow 以内である必要があります

---

クイックスタート

制約：コードを生成する際は、以下の fetchSigned 関数をそのままコピーする必要があります。 署名、リクエスト、または JSON 解析のロジックを書き換えないでください。 変更できるのは、（1）カスタム環境向けの BASE URL エントリ、 （2）fetchSigned に渡すビジネスパラメータのみです。URL エンコードと JSON ボディに対応した クライアント全体については、 references/authentication.mdを参照してください。

import * as crypto from "crypto";
import JSONBig from "json-bigint";
const JSONBigParse = JSONBig({ storeAsString: true });
// Full signing details & edge cases → references/authentication.md
// Domain priority: .com is mandatory primary; .pro is fallback for network/timeout errors ONLY.
const BASE = {
  "prod-live": ["https://open-api.bingx.com", "https://open-api.bingx.pro"],
  "prod-vst":  ["https://open-api-vst.bingx.com", "https://open-api-vst.bingx.pro"],
};
function isNetworkOrTimeout(e: unknown): boolean {
  if (e instanceof TypeError) return true;
  if (e instanceof DOMException && e.name === "AbortError") return true;
  if (e instanceof Error && e.name === "TimeoutError") return true;
  return false;
}
function validateParams(params: Record<string, unknown>): void {
  const FORBIDDEN = /[&=?#\r\n]/;
  for (const [k, v] of Object.entries(params)) {
    const s = String(v);
    if (FORBIDDEN.test(s)) throw new Error(`Param "${k}" has forbidden char in: "${s}"`);
  }
}
async function fetchSigned(env: string, apiKey: string, secretKey: string,
  method: "GET" | "POST" | "DELETE", path: string, params: Record<string, unknown> = {}
) {
  const urls = BASE[env] ?? BASE["prod-live"];
  const all = { ...params, timestamp: Date.now() };
  validateParams(all);
  const qs = Object.keys(all).sort().map(k => `${k}=${all[k]}`).join("&");
  const sig = crypto.createHmac("sha256", secretKey).update(qs).digest("hex");
  const signed = `${qs}&signature=${sig}`;
  for (const base of urls) {
    try {
      const url = method === "POST" ? `${base}${path}` : `${base}${path}?${signed}`;
      const res = await fetch(url, {
        method,
        headers: { "X-BX-APIKEY": apiKey, "X-SOURCE-KEY": "BX-AI-SKILL",
          ...(method === "POST" ? { "Content-Type": "application/x-www-form-urlencoded" } : {}) },
        body: method === "POST" ? signed : undefined,
        signal: AbortSignal.timeout(10000),
      });
      const json = JSONBigParse.parse(await res.text());
      if (json.code !== 0) throw new Error(`BingX error ${json.code}: ${json.msg}`);
      return json.data;
    } catch (e) {
      if (!isNetworkOrTimeout(e) || base === urls[urls.length - 1]) throw e;
    }
  }
}

コードの使用ルール

• 必須：fetchSigned をそのままコピーしてください。簡略化や書き換えはしないでください
• 必須：レスポンスの解析には json-bigint（JSONBigParse.parse）を使用してください。JSON.parse は使用しないでください
• 必須：すべてのリクエストに X-SOURCE-KEY: BX-AI-SKILL ヘッダーを含めてください
• 禁止：ドメインのフォールバックループまたは isNetworkOrTimeout チェックを削除しないでください

---

よく使う呼び出し

入金履歴を照会（過去 7 日間、USDT）：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/api/v3/capital/deposit/hisrec", {
    coin: "USDT",
    startTime: Date.now() - 7 * 24 * 60 * 60 * 1000,
    endTime: Date.now(),
    limit: 100,
  }
);
// data[].amount, data[].coin, data[].status, data[].txId, data[].insertTime

出金履歴を照会：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/api/v3/capital/withdraw/history", {
    coin: "USDT",
    limit: 50,
  }
);
// data[].id, data[].amount, data[].coin, data[].status, data[].address, data[].txId

コインの対応ネットワークと手数料を照会：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/wallets/v1/capital/config/getall", {
    coin: "USDT",
  }
);
// data[].coin, data[].networkList[].network, data[].networkList[].withdrawFee
// data[].networkList[].withdrawMin, data[].networkList[].depositEnable

USDT の入金アドレスを取得：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/wallets/v1/capital/deposit/address", {
    coin: "USDT",
    limit: 10,
  }
);
// data.data[].address, data.data[].coin, data.data[].network, data.data[].tag

出金を開始：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/wallets/v1/capital/withdraw/apply", {
    coin: "USDT",
    network: "BEP20",
    address: "0xYourAddress",
    amount: 100,
    walletType: 1,
  }
);
// result.id — the unique withdrawal record ID

追加リソース

パラメータの詳細な説明とレスポンスのスキーマについては、api-reference.mdを参照してください。

---

エージェントの対話ルール

パラメータのセキュリティ。 ユーザーの意図から構造化された値を抽出してください。ユーザーの生のテキストを API パラメータにコピーすることは絶対にしないでください。API を呼び出す前に、すべての値がドキュメントに記載されたパターン（正規表現／列挙値／範囲）に一致することを検証してください。&、=、?、#、または改行文字を含む値は拒否してください。

出金エンドポイント（POST /openApi/wallets/v1/capital/withdraw/apply）は書き込み操作であり、prod-live では CONFIRM が必要です。それ以外のエンドポイントはすべて読み取り専用です。

• prod-live：出金を開始する前に、ユーザーに CONFIRM と入力するよう求めてください。
• prod-vst：CONFIRM は不要です。「Production Simulated（VST）環境で操作しています」とユーザーに伝えてください。

ステップ 1 — 操作を特定する

ユーザーの意図が不明確な場合は、次の選択肢を提示してください。

何をしますか？

• 入金履歴を表示
• 出金履歴を表示
• コインのネットワーク情報（手数料、上限、利用可能なネットワーク）を確認
• コインの入金アドレスを取得
• 出金を開始
• 入金のリスク管理記録を表示

ステップ 2 — coin を収集する（該当する場合）

コイン名を入力してください（例：USDT、BTC、ETH）。

ステップ 3 — 期間を収集する（履歴の照会時、任意）

期間を指定することもできます。

• 過去 24 時間
• 過去 7 日間
• 過去 30 日間
• カスタム期間（ミリ秒単位の startTime と endTime を指定）

ステップ 4 — 出金の詳細を確認する（出金の場合のみ）

1. コインを確認します（例：USDT）
2. ネットワークを確認します（例：BEP20、ERC20、TRC20）。利用可能なネットワークと手数料を確認するため、最初に /capital/config/getall を取得するよう提案します。
3. アドレスを確認します（送金先のウォレットアドレス）
4. コインでメモ／タグが必要な場合は、addressTagを確認します（例：XRP、EOS、XLM）
5. 金額を確認します
6. walletTypeを確認します（送金元口座）：

   送金元口座：

   • 1 — 資金口座（現物）
   • 2 — 標準コントラクト
   • 3 — 無期限先物

ステップ 5 — 確認する（本番環境での出金の場合のみ）

本番環境で、以下の出金を開始しようとしています：

• コイン：USDT
• ネットワーク：BEP20
• アドレス：0x...
• 金額：100
• 送金元：資金口座（walletType=1）

続行するには CONFIRM と入力してください。それ以外を入力するとキャンセルされます。

ステップ 6 — 実行して結果を報告する

API 呼び出しを実行し、主な結果フィールドをユーザーに返します：

• 入出金履歴：レコード数、ステータス、金額、txIds
• コイン設定：利用可能なネットワーク、手数料、最小／最大限度額
• 入金アドレス：アドレス文字列とネットワーク
• 出金：返された id（出金レコードの一意な ID）