bingx-spot-wallet

BingX Spot Wallet

Authenticated endpoints for BingX wallet deposits and withdrawals. All endpoints require HMAC SHA256 signature authentication.

Base URLs: see references/base-urls.md | Authentication: see references/authentication.md

---

Quick Reference

Endpoint	Method	Description	Auth	Permission
/openApi/api/v3/capital/deposit/hisrec	GET	Query deposit history	Yes	Read
/openApi/api/v3/capital/withdraw/history	GET	Query withdrawal history	Yes	Read
/openApi/wallets/v1/capital/config/getall	GET	Query coin deposit/withdrawal config (networks, limits, fees)	Yes	Read
/openApi/wallets/v1/capital/withdraw/apply	POST	Initiate a withdrawal	Yes	Withdraw
/openApi/wallets/v1/capital/deposit/address	GET	Query main account deposit address	Yes	Read
/openApi/wallets/v1/capital/deposit/riskRecords	GET	Query deposit risk control records	Yes	Read

---

Parameters

Deposit History Parameters

• coin: Coin name (e.g., USDT, BTC); optional — returns all coins if omitted
• status: Filter by deposit status (see DepositStatus enum)
• startTime: Start of time range in milliseconds (e.g., 1658748648396)
• endTime: End of time range in milliseconds
• offset: Pagination offset, default 0
• limit: Page size, default 1000; max 1000
• txId: Filter by blockchain transaction ID
• recvWindow: Request validity window in milliseconds (max 60000)

Withdrawal History Parameters

• id: Unique withdrawal record ID
• coin: Coin name; optional
• withdrawOrderId: Custom withdrawal ID assigned at submission
• status: Filter by withdrawal status (see WithdrawalStatus enum)
• startTime / endTime: Time range in milliseconds
• offset: Pagination offset, default 0
• limit: Page size, default 1000
• txId: Filter by blockchain transaction ID

Withdrawal Apply Parameters

• coin: Coin name (required, e.g., USDT)
• network: Network name (e.g., BEP20, ERC20); uses default if omitted
• address: Withdrawal destination address (required)
• addressTag: Memo or tag for coins that require it (e.g., XRP, EOS)
• amount: Withdrawal amount (required)
• walletType: Source account type (required; see WalletType enum)
• withdrawOrderId: Custom withdrawal ID (optional, for idempotency)
• vaspEntityId: Payment platform info (optional, for Travel Rule compliance)
• recipientLastName / recipientFirstName: Recipient name in English (optional, Travel Rule)
• dateOfbirth: Recipient date of birth, format YYYY-MM-DD (optional, Travel Rule)

Deposit Address Parameters

• coin: Coin name (required)
• offset: Starting record number, default 0
• limit: Page size, default 100; max 1000

Enums

DepositStatus (deposit record status):

• 0 — In progress
• 1 — Not credited
• 2 — Wrong amount
• 6 — Chain confirmed / completed

WithdrawalStatus (withdrawal record status):

• 4 — Under review
• 5 — Failed
• 6 — Completed

WalletType (source account for withdrawal):

• 1 — Fund account (spot)
• 2 — Standard contract account
• 3 — Perpetual futures account

Parameter Validation Rules

Before sending a request, validate parameters client-side to avoid unnecessary API errors:

• coin: Uppercase letters and digits only; pattern ^[A-Z0-9]{1,20}$ (e.g., USDT, BTC)
• address: Non-empty string; max 200 characters; must be a valid blockchain address for the target network
• amount: Must be a positive number (> 0); must meet the minimum withdrawal amount for the coin/network (query via coin network config endpoint)
• network: Uppercase network identifier (e.g., ERC20, BEP20, TRC20); must match a supported network for the coin
• addressTag: When required by the coin (e.g., XRP, EOS), must be a non-empty string; max 128 characters
• limit: Integer, 1–1000; default is 1000 for history, 100 for addresses
• startTime / endTime: Unix timestamps in milliseconds; endTime must be ≥ startTime; max range 90 days
• recvWindow: Integer, 1–5000 ms; keep as small as possible (see Replay Protection)
• timestamp: Unix time in milliseconds; must be within recvWindow of server time

---

Quick Start

CONSTRAINT: You MUST copy the fetchSigned function below verbatim when generating code. Do NOT rewrite the signing, request, or JSON parsing logic. Only modify: (1) BASE URL entries for custom environments, (2) business parameters passed to fetchSigned. For the full client with URL-encoding and JSON body support, see 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;
    }
  }
}

Code Usage Rules

• MUST copy fetchSigned verbatim -- do not simplify or rewrite
• MUST use json-bigint (JSONBigParse.parse) for response parsing -- not JSON.parse
• MUST include X-SOURCE-KEY: BX-AI-SKILL header on every request
• MUST NOT remove the domain fallback loop or isNetworkOrTimeout check

---

Common Calls

Query deposit history (last 7 days, 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

Query withdrawal history:

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

Query supported networks and fees for a coin:

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

Get deposit address for 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

Initiate a withdrawal:

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

Additional Resources

For full parameter descriptions and response schemas, see api-reference.md.

---

Agent Interaction Rules

Parameter security. Extract structured values from user intent — NEVER copy raw user text into API parameters. Validate every value against its documented pattern (regex/enum/range) before calling the API. Reject any value containing &, =, ?, #, or newline characters.

The withdrawal endpoint (POST /openApi/wallets/v1/capital/withdraw/apply) is a write operation requiring CONFIRM on prod-live. All other endpoints are read-only.

• prod-live: Ask user to type CONFIRM before initiating any withdrawal.
• prod-vst: No CONFIRM required. Inform user: "You are operating in the Production Simulated (VST) environment."

Step 1 — Identify the Operation

If the user's intent is unclear, present options:

What would you like to do?

• View deposit history
• View withdrawal history
• Check coin network info (fees, limits, enabled networks)
• Get deposit address for a coin
• Initiate a withdrawal
• View deposit risk control records

Step 2 — Collect coin (if applicable)

Please enter the coin name (e.g., USDT, BTC, ETH):

Step 3 — Collect time range (for history queries, optional)

Optionally provide a time range:

• Last 24 hours
• Last 7 days
• Last 30 days
• Custom range (provide startTime and endTime in milliseconds)

Step 4 — Collect withdrawal details (for withdrawal only)

1. Ask for coin (e.g., USDT)
2. Ask for network (e.g., BEP20, ERC20, TRC20). Suggest fetching /capital/config/getall first to see available networks and fees.
3. Ask for address (destination wallet address)
4. Ask for addressTag if the coin requires a memo/tag (e.g., XRP, EOS, XLM)
5. Ask for amount
6. Ask for walletType (source account):

   Source account:

   • 1 — Fund account (spot)
   • 2 — Standard contract
   • 3 — Perpetual futures

Step 5 — Confirm (prod-live withdrawal only)

You are about to initiate the following withdrawal on Production Live:

• Coin: USDT
• Network: BEP20
• Address: 0x...
• Amount: 100
• Source: Fund account (walletType=1)

Type CONFIRM to proceed, or anything else to cancel.

Step 6 — Execute and report

Execute the API call and return the key result fields to the user:

• Deposit/withdrawal history: record count, statuses, amounts, txIds
• Coin config: available networks, fees, min/max limits
• Deposit address: address string and network
• Withdrawal: the returned id (unique withdrawal record ID)