bingx-coinm-ws-account

BingX Coin-M WebSocket アカウントデータ

WebSocket 経由で BingX の Coin-M（インバース）無期限先物のアカウントデータをリアルタイムで受信します。Listen Key 認証が必要です。

WebSocket エンドポイント： wss://open-api-cswap-ws.bingx.com/market?listenKey=<key>

有効な listenKey で接続すると、チャンネルを購読しなくても、すべてのイベントタイプが自動的にプッシュされます。

シンボル形式： Coin-M では BTC-USDT ではなく、BTC-USD 形式を使用します。

クイックリファレンス

WebSocket イベント（自動プッシュ）

イベントタイプ	説明	プッシュ頻度
listenKeyExpired	Listen Key の有効期限切れ	期限切れ時
ACCOUNT_UPDATE	アカウント残高およびポジションの変更	変更時
ORDER_TRADE_UPDATE	注文の作成、約定、ステータスの変更	変更時
ACCOUNT_CONFIG_UPDATE	レバレッジ／証拠金モードの変更	変更時

Listen Key REST API

エンドポイント	メソッド	説明	認証
/openApi/user/auth/userDataStream	POST	Listen Key を生成（有効期間 1 時間）	必要
/openApi/user/auth/userDataStream	PUT	Listen Key の有効期間を延長（60 分まで）	必要
/openApi/user/auth/userDataStream	DELETE	Listen Key を削除	必要

---

Listen Key の管理

WebSocket アカウントデータストリームの認証には Listen Key が必要です。HMAC SHA256 署名の詳細については、references/authentication.md を参照してください。

Listen Key の生成

POST /openApi/user/auth/userDataStream

ヘッダー： X-BX-APIKEY: <your-api-key>、X-SOURCE-KEY: BX-AI-SKILL

レスポンス：

{"listenKey": "a8ea75681542e66f1a50a1616dd06ed77dab61baa0c296bca03a9b13ee5f2dd7"}

Listen Key の延長

PUT /openApi/user/auth/userDataStream

パラメーター： listenKey（文字列、必須）

有効期間を 60 分に延長します。30 分ごとに呼び出すことを推奨します。

Listen Key の削除

DELETE /openApi/user/auth/userDataStream

パラメーター： listenKey（文字列、必須）

---

クイックスタート

WebSocket 接続： GZIP 解凍と Ping/Pong ハートビートについては、references/websocket.md を参照してください。

TypeScript ヘルパー：

制約：コードを生成する際は、以下の connectCoinmWsAccount 関数をそのままコピーする必要があります。 WebSocket または解凍のロジックを書き換えないでください。

import * as pako from "pako";
import * as crypto from "crypto";

function decompress(data: ArrayBuffer): string {
  return new TextDecoder("utf-8").decode(pako.ungzip(new Uint8Array(data)));
}

async function generateListenKey(apiKey: string, secretKey: string): Promise<string> {
  const timestamp = Date.now();
  const paramStr = `timestamp=${timestamp}`;
  const signature = crypto.createHmac("sha256", secretKey).update(paramStr).digest("hex");
  const url = `https://open-api.bingx.com/openApi/user/auth/userDataStream?${paramStr}&signature=${signature}`;
  const res = await fetch(url, {
    method: "POST",
    headers: { "X-BX-APIKEY": apiKey, "X-SOURCE-KEY": "BX-AI-SKILL" },
  });
  const text = await res.text();
  if (!res.ok) throw new Error(`BingX error ${res.status}: ${text}`);
  const json = JSON.parse(text);
  if (json.listenKey) return json.listenKey;
  if (json.data?.listenKey) return json.data.listenKey;
  if (json.code !== 0) throw new Error(`BingX error ${json.code}: ${json.msg}`);
  return json.listenKey ?? json.data?.listenKey;
}

function connectCoinmWsAccount(
  listenKey: string,
  onEvent: (event: any) => void
): WebSocket {
  const ws = new WebSocket(
    `wss://open-api-cswap-ws.bingx.com/market?listenKey=${listenKey}`
  );
  ws.binaryType = "arraybuffer";

  ws.onmessage = (event) => {
    const text = decompress(event.data as ArrayBuffer);
    if (text.includes("ping") || text === "Ping") {
      ws.send("Pong");
      return;
    }
    try {
      onEvent(JSON.parse(text));
    } catch {
      onEvent(text);
    }
  };

  ws.onerror = (err) => console.error("WS error:", err);
  ws.onclose = (ev) => console.log("WS closed:", ev.code, ev.reason);

  return ws;
}

コードの使用ルール

• connectCoinmWsAccount、generateListenKey、decompress は必ずそのままコピーしてください
• Ping/Pong ハートビートを必ず処理してください
• 有効期限切れを防ぐため、Listen Key を 30 分ごとに必ず延長してください
• GZIP 解凍ロジックを削除してはいけません

よく使う呼び出し

アカウントストリームに接続：

const listenKey = await generateListenKey(API_KEY, SECRET_KEY);
connectCoinmWsAccount(listenKey, (event) => {
  if (event.e === "ACCOUNT_UPDATE") {
    // event.a.B: balance updates, event.a.P: position updates
  } else if (event.e === "ORDER_TRADE_UPDATE") {
    // event.o: order details
  } else if (event.e === "ACCOUNT_CONFIG_UPDATE") {
    // event.ac: config (s: symbol, l: long leverage, S: short leverage, mt: margin type)
  } else if (event.e === "listenKeyExpired") {
    // Reconnect with new listen key
  }
});

追加リソース

イベントフィールドの詳細な説明と完全なレスポンススキーマについては、api-reference.md を参照してください。

---

エージェントとのやり取りのルール

重要なルール（すべての応答に適用）：

1. ユーザーにコードを返してはいけません。 応答にコードブロック、コードスニペット、TypeScript、JavaScript、cURL コマンド、生の API 呼び出しを含めないでください。データまたは操作結果の自然言語による要約のみを返してください。
2. GET のみ実行可能です。 HTTP GET リクエストのみを実行してください。Listen Key の管理には POST／PUT／DELETE が必要です。これらの書き込み操作には独自の実装が必要であることをユーザーに伝えてください。
3. パラメーターのセキュリティ。 ユーザーの意図から構造化された値を抽出してください。生のユーザーテキストを API パラメーターにコピーしてはいけません。API 呼び出しの前に、すべての値をドキュメントに記載されたパターン（正規表現／列挙値／範囲）と照合して検証してください。&、=、?、#、または改行文字を含む値は拒否してください。

coinm-ws-account は、認証済みのアカウントデータをリアルタイムで提供します。Listen Key が必要ですが、読み取り専用の監視に CONFIRM は不要です。

操作の特定

ユーザーのリクエストが曖昧な場合（例：「Coin-M アカウントを監視して」）、希望する内容を確認してください。

次のアカウントデータストリームタイプから選択してください：

• アカウント残高とポジションの更新 — ACCOUNT_UPDATE
• 注文ステータスの更新 — ORDER_TRADE_UPDATE
• レバレッジと証拠金設定の変更 — ACCOUNT_CONFIG_UPDATE
• Listen Key の管理（生成／延長／削除）
• すべてのイベント（listenKey で接続すると、すべて自動的に受信します）

アカウントストリームのシンボルコンテキスト

アカウントデータストリームはすべてのシンボルについて自動的にプッシュされます。接続にシンボルパラメーターは必要ありません。各プッシュイベントのペイロードには、関連するシンボルが含まれます（例：注文更新では o.s、ポジション更新では a.P[].s）。Coin-M のシンボルには BTC-USDT ではなく BTC-USD の形式が使われます。ユーザーが特定のシンボルについて尋ねた場合は、プッシュデータ内のシンボルフィールドでイベントを絞り込んでください。