Bingx Swap Trade

BingX Swap Trade

Authenticated trading endpoints for BingX perpetual futures. All endpoints require HMAC SHA256 signature authentication.

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

Quick Reference

Parameters

Order Parameters

• symbol: Trading pair in BASE-QUOTE format (e.g., BTC-USDT, ETH-USDT)
• side: Order direction — BUY or SELL
• positionSide: Position direction — LONG or SHORT (hedge mode) / BOTH (one-way mode)
• type: Order type (see Enums)
• quantity: Order quantity in coins (e.g., 0.01 for BTC-USDT); can be omitted when closePosition: true
• price: Limit price (required for LIMIT, STOP, TAKE_PROFIT types)
• stopPrice: Trigger price (required for STOP_MARKET, STOP, TAKE_PROFIT_MARKET, TAKE_PROFIT)
• timeInForce: GTC | IOC | FOK | PostOnly — default GTC; required for LIMIT type
• clientOrderId: Custom order ID, 1–40 chars (converted to lowercase)
• recvWindow: Request validity window in milliseconds (max 60000)
• orderId: System order ID (for cancel/query operations)
• workingType: Price source used to trigger conditional orders — MARK_PRICE (mark price) or CONTRACT_PRICE (last traded price, default)
• stopGuaranteed: true | false — Whether stop-loss execution is guaranteed; guaranteed stops may incur an additional fee
• closePosition: true | false — When the trigger fires, close the entire position quantity; cannot be used with quantity
• reduceOnly: true | false — Order can only reduce (never increase) position size
• activationPrice: Activation price for TRAILING_STOP_MARKET orders (optional; defaults to current market price when omitted)
• priceRate: Trailing callback rate for TRAILING_STOP_MARKET / TRAILING_TP_SL orders (e.g., 0.05 = 5%)
• stopLoss: Object — Attach a stop-loss to a MARKET/LIMIT order (see Stop-Loss/Take-Profit Object)
• takeProfit: Object — Attach a take-profit to a MARKET/LIMIT order (see Stop-Loss/Take-Profit Object)

Position Parameters

• leverage: Integer leverage multiplier (e.g., 10, 20, 50)
• marginType: ISOLATED or CROSSED
• dualSidePosition: "true" (hedge mode) or "false" (one-way mode)
• positionId: Position ID string (used by closePosition and positionMargin endpoints)
• amount: Margin adjustment amount in USDT (used by positionMargin endpoint)
• direction_type: 1 (add margin) or 2 (reduce margin) (used by positionMargin endpoint)

Enums

type (Order type):

• MARKET — Market order (fills immediately at best price; attach stopLoss/takeProfit objects here)
• LIMIT — Limit order (requires price and timeInForce; attach stopLoss/takeProfit objects here)
• STOP_MARKET — Stop-loss market (triggers at stopPrice, executes as market)
• STOP — Stop-loss limit (triggers at stopPrice, executes as limit at price)
• TAKE_PROFIT_MARKET — Take-profit market (triggers at stopPrice, executes as market)
• TAKE_PROFIT — Take-profit limit (triggers at stopPrice, executes as limit at price)
• TRAILING_STOP_MARKET — Trailing stop market; uses priceRate (required) and optional activationPrice
• TRAILING_TP_SL — Trailing TP/SL for an existing position; links to position via symbol + positionSide; uses priceRate

side: BUY | SELL

positionSide: LONG | SHORT | BOTH

marginType: ISOLATED | CROSSED

timeInForce: GTC | IOC | FOK | PostOnly

workingType (trigger price source for conditional orders):

• MARK_PRICE — Use mark price to evaluate trigger condition
• CONTRACT_PRICE — Use last traded price (default)

Stop-Loss / Take-Profit Object Structure

When attaching stopLoss or takeProfit to a MARKET or LIMIT order:

{
  "stopLoss": {
    "type": "STOP_MARKET",       // "STOP_MARKET" or "STOP"
    "stopPrice": 29000,          // required: trigger price
    "price": 28900,              // required only for type "STOP" (limit execution price)
    "workingType": "MARK_PRICE", // "MARK_PRICE" or "CONTRACT_PRICE"
    "stopGuaranteed": false      // true = guaranteed execution (extra fee may apply)
  },
  "takeProfit": {
    "type": "TAKE_PROFIT_MARKET",  // "TAKE_PROFIT_MARKET" or "TAKE_PROFIT"
    "stopPrice": 35000,            // required: trigger price
    "price": 35100,                // required only for type "TAKE_PROFIT" (limit execution price)
    "workingType": "MARK_PRICE",
    "stopGuaranteed": false
  }
}

Constraint: stopLoss/takeProfit objects are only supported on MARKET or LIMIT order types. They cannot be used with STOP_MARKET, STOP, TAKE_PROFIT_MARKET, TAKE_PROFIT, TRAILING_STOP_MARKET, or TRAILING_TP_SL.

Parameter Validation Rules

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

• symbol: Must match ^[A-Z0-9]+-[A-Z]+$; max 20 characters (e.g., BTC-USDT)
• quantity: Must be a positive number (> 0); max precision depends on the symbol's contract specification
• price: When provided, must be a positive number (> 0)
• stopPrice: When provided, must be a positive number (> 0); must differ from current market price
• leverage: Positive integer; range varies per symbol (typically 1–125 for BTC-USDT)
• clientOrderId: Alphanumeric only, 1–40 characters; pattern ^[a-zA-Z0-9]{1,40}$; no special characters
• priceRate: Trailing callback rate; must satisfy 0 < value ≤ 1 (e.g., 0.05 = 5%)
• 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

Place a market buy order:

const order = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/swap/v2/trade/order", {
    symbol: "BTC-USDT",
    side: "BUY",
    positionSide: "LONG",
    type: "MARKET",
    quantity: 0.01,
  }
);
// order.orderId, order.status

Cancel an order:

await fetchSigned("prod-live", API_KEY, SECRET, "DELETE",
  "/openApi/swap/v2/trade/order", {
    symbol: "BTC-USDT",
    orderId: 123456789,
  }
);

Query open orders:

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

Set leverage:

await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/swap/v2/trade/leverage", {
    symbol: "BTC-USDT",
    side: "LONG",
    leverage: 10,
  }
);

Set margin type:

await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/swap/v2/trade/marginType", {
    symbol: "BTC-USDT",
    marginType: "ISOLATED",
  }
);

Note: To query current positions, use the swap-account skill which provides position query endpoints with full details including PnL and liquidation price.

Additional Resources

For full parameter descriptions, response schemas, and all 42 endpoints, 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-trade operations are write operations (except GET queries). Follow environment confirmation rules:

• prod-live: Ask user to type CONFIRM before any order placement, cancellation, or position/leverage change.
• 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?

• Place a new order
• Cancel an order / Cancel all orders
• Close a position / Close all positions
• Check open orders
• Check current positions
• Set leverage
• Set margin type (ISOLATED / CROSSED)
• Set position mode (Hedge / One-way)

Step 2 — Collect symbol (if not provided)

Please select a trading pair (or type another):

• BTC-USDT
• ETH-USDT
• SOL-USDT
• BNB-USDT
• Other (format: BASE-USDT)

Step 3 — Collect side (for order placement)

Order direction:

• BUY
• SELL

Step 4 — Collect positionSide

Position direction:

• LONG (open/add long)
• SHORT (open/add short)
• BOTH (one-way mode)

Step 5 — Collect order type

Order type:

• MARKET — execute immediately at market price (can attach stopLoss/takeProfit objects)
• LIMIT — execute at a specific price (can attach stopLoss/takeProfit objects)
• STOP_MARKET — stop-loss market order (triggers at stopPrice, executes as market)
• STOP — stop-loss limit order (triggers at stopPrice, executes as limit)
• TAKE_PROFIT_MARKET — take-profit market order (triggers at stopPrice)
• TAKE_PROFIT — take-profit limit order (triggers at stopPrice, executes as limit)
• TRAILING_STOP_MARKET — trailing stop for new position (requires priceRate; optional activationPrice)
• TRAILING_TP_SL — trailing TP/SL for an existing position (links via symbol + positionSide; requires priceRate)

Step 6 — Collect quantity and price

• Ask for quantity in coins (e.g., 0.01 BTC for BTC-USDT). Omit if using closePosition: true.
• If type is LIMIT, STOP, or TAKE_PROFIT: also ask for price.
• If type is STOP_MARKET, STOP, TAKE_PROFIT_MARKET, or TAKE_PROFIT: also ask for stopPrice.
• If type is TRAILING_STOP_MARKET or TRAILING_TP_SL: ask for priceRate (e.g., 0.05 = 5%) and optionally activationPrice.
• If type is MARKET or LIMIT: optionally offer to attach a stopLoss and/or takeProfit object (ask for trigger price and type).

Optional advanced parameters (ask only if relevant or user mentions them):

• workingType: trigger price source — MARK_PRICE or CONTRACT_PRICE (default)
• reduceOnly: true to ensure the order only reduces position size
• closePosition: true to close the entire position when triggered (cannot use with quantity)
• stopGuaranteed: true for guaranteed stop execution (extra fee may apply)

Step 7 — Confirm (prod-live only)

For prod-live environment, present a summary and ask:

You are about to place the following order on Production Live:

• Symbol: BTC-USDT
• Side: BUY / LONG
• Type: MARKET
• Quantity: 0.01

Type CONFIRM to proceed, or anything else to cancel.

Step 8 — Execute and report

Execute the API call and return the order ID and status to the user.

Cancel Order Flow

1. Ask for orderId (or clientOrderId) if not provided.
2. For prod-live: ask for CONFIRM.
3. Execute DELETE /openApi/swap/v2/trade/order.

Close Position Flow

1. Ask for symbol if not provided.
2. Present options: close specific position (LONG/SHORT) or close all.
3. For prod-live: ask for CONFIRM.
4. Use POST /openApi/swap/v2/trade/closeAllPositions or place a reverse MARKET order.

Leverage Settings Flow

1. Ask for symbol if not provided.
2. Ask for position side (LONG / SHORT / both).
3. Ask for leverage value (e.g., 1–125).
4. For prod-live: ask for CONFIRM.
5. Execute POST /openApi/swap/v2/trade/leverage.

Margin Type Flow

1. Ask for symbol if not provided.
2. Present options: ISOLATED or CROSSED.
3. For prod-live: ask for CONFIRM.
4. Execute POST /openApi/swap/v2/trade/marginType.

Position Mode Flow

1. Present options: Hedge mode (dualSidePosition: true) or One-way mode (dualSidePosition: false).
2. For prod-live: ask for CONFIRM.
3. Execute POST /openApi/swap/v1/positionSide/dual.