bingx-swap-account

name	bingx-swap-account
description	Query BingX perpetual swap account data including balance, positions, commission rates, and fund flow history. Use when the user asks about BingX account balance, margin info, current positions, PnL, liquidation price, fee rates, or income/fund flow records.

BingX Swap Account

Authenticated read-only endpoints for BingX perpetual futures account data. All endpoints require HMAC SHA256 signature authentication.

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

---

Quick Reference

Endpoint	Method	Description	Authentication
/openApi/swap/v3/user/balance	GET	Account balance, equity, and margin info	Yes
/openApi/swap/v2/user/positions	GET	Current open positions with PnL and liquidation price	Yes
/openApi/swap/v2/user/commissionRate	GET	User taker/maker fee rates	Yes
/openApi/swap/v2/user/income	GET	Fund flow history (PnL, funding fees, trading fees, etc.)	Yes
/openApi/swap/v2/user/income/export	GET	Export fund flow as Excel file	Yes

---

Parameters

Common Parameters

• symbol: Trading pair in BASE-QUOTE format (e.g., BTC-USDT). Optional for most account endpoints.
• timestamp: Request timestamp in milliseconds (required for all authenticated endpoints).
• recvWindow: Request validity window in milliseconds (optional, max 60000).
• startTime / endTime: Time range filters in milliseconds (used by income endpoints).
• limit: Number of results to return (used by income endpoints; default 100, max 1000).

incomeType Enum (for income endpoints)

Value	Description
TRANSFER	Transfer
REALIZED_PNL	Realized profit and loss
FUNDING_FEE	Funding fee
TRADING_FEE	Trading fee
INSURANCE_CLEAR	Liquidation
TRIAL_FUND	Trial fund
ADL	Auto-deleveraging
SYSTEM_DEDUCTION	System deduction
GTD_PRICE	Guaranteed price

Parameter Validation Rules

• symbol: When provided, must match ^[A-Z0-9]+-[A-Z]+$; max 20 characters (e.g., BTC-USDT)
• incomeType: When provided, must exactly match one of the enum values above
• startTime / endTime: Unix timestamps in milliseconds; endTime must be ≥ startTime
• limit: Positive integer, 1–1000; default 100
• recvWindow: Integer, 1–5000 ms (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 account balance:

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v3/user/balance"
);
// data.balance.balance, data.balance.equity, data.balance.availableMargin

Query all open positions:

const positions = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v2/user/positions"
);
// positions[].symbol, positions[].positionAmt, positions[].unrealizedProfit, positions[].liquidationPrice

Query positions for a specific symbol:

const positions = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v2/user/positions", { symbol: "BTC-USDT" }
);

Query user fee rates:

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v2/user/commissionRate"
);
// data.commission.takerCommissionRate, data.commission.makerCommissionRate

Query recent fund flow (last 7 days, all types):

const income = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v2/user/income", { limit: 100 }
);
// income[].incomeType, income[].income, income[].asset, income[].time

Query funding fees for BTC-USDT in a time range:

const income = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v2/user/income", {
    symbol: "BTC-USDT",
    incomeType: "FUNDING_FEE",
    startTime: 1700000000000,
    endTime: 1702731787011,
    limit: 200,
  }
);

Additional Resources

For complete parameter descriptions and full 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.

All swap-account endpoints are read-only (GET). No CONFIRM required for any environment — they never modify account state.

Credentials are required. If no account is specified, default to the main account.

Step 1 — Identify the query

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

Please select the account information type to query:

• Account balance / Equity / Margin — balance
• Current positions / Unrealized PnL / Liquidation price — positions
• Commission rate — commissionRate
• Fund flow (PnL / funding fee / trading fee / etc.) — income
• Export fund flow (Excel) — income/export

Step 2 — Collect symbol (if relevant)

For positions and income endpoints, symbol is optional. If the user asks about a specific coin, infer the symbol automatically (e.g., "BTC position" → BTC-USDT).

If not specified, query all symbols and inform the user.

Step 3 — Collect time range (for income endpoints)

• If neither startTime nor endTime is provided, the API returns the last 7 days of data. Inform the user.
• Only the last 3 months of data is available.
• If the user asks for a specific date range, convert to milliseconds.

Step 4 — Collect incomeType (for income endpoints)

If the user specifies a type (e.g., "funding fee", "trading fee", "PnL"), map to the correct incomeType enum value:

User says	incomeType
Realized PnL / PnL	REALIZED_PNL
Funding fee / Funding rate	FUNDING_FEE
Trading fee / Commission	TRADING_FEE
Liquidation	INSURANCE_CLEAR
ADL / Auto-deleverage	ADL
Transfer	TRANSFER

If not specified, omit incomeType to return all types.

Step 5 — Execute and report

Execute the API call and present results in a readable format:

• balance: Show equity, available margin, used margin, unrealized PnL as a summary table.
• positions: Show a table per position: symbol, side, amount, avg price, unrealized PnL, liquidation price, leverage.
• commissionRate: Show taker and maker rate as percentages (multiply by 100).
• income: Show a table of recent records: time, type, symbol, amount, asset.