Endpoint	Method	Description	Required	Optional
`/openApi/swap/v2/quote/contracts`	GET	All contract specifications	None	symbol
`/openApi/swap/v1/tradingRules`	GET	Trading rules and specifications	timestamp, symbol	recvWindow
`/openApi/swap/v2/quote/depth`	GET	Order book bids & asks	symbol	limit, timestamp, recvWindow
`/openApi/swap/v2/quote/trades`	GET	Recent public trades	symbol	limit, timestamp, recvWindow
`/openApi/swap/v1/market/historicalTrades`	GET	Historical trade lookup	timestamp	symbol, limit, fromId, recvWindow
`/openApi/swap/v2/quote/premiumIndex`	GET	Mark price & premium index	None	symbol, timestamp, recvWindow
`/openApi/swap/v2/quote/fundingRate`	GET	Current & next funding rate	None	symbol, startTime, endTime, limit, timestamp, recvWindow
`/openApi/swap/v3/quote/klines`	GET	OHLCV candlestick data	symbol, interval	startTime, endTime, limit, timestamp, recvWindow
`/openApi/swap/v1/market/markPriceKlines`	GET	Mark price kline data	symbol, interval	startTime, endTime, limit, timestamp, recvWindow
`/openApi/swap/v2/quote/openInterest`	GET	Total open interest	symbol	timestamp, recvWindow
`/openApi/swap/v2/quote/ticker`	GET	24h price change statistics	None	symbol, timestamp, recvWindow
`/openApi/swap/v1/ticker/price`	GET	Latest price ticker	None	symbol, timestamp, recvWindow
`/openApi/swap/v2/quote/bookTicker`	GET	Best bid/ask price & qty	symbol	timestamp, recvWindow
`/openApi/swap/v2/server/time`	GET	Query server time	None	None

Parameters

Common Parameters

timestamp: Current Unix time in milliseconds. Required only for trading rules and historical trades; optional only where listed above. The helper generates it dynamically for the two required endpoints.
symbol: Trading pair in BASE-QUOTE format (e.g., BTC-USDT, ETH-USDT, SOL-USDT)
limit: Number of results to return. Default and max vary per endpoint.
startTime: Start timestamp in milliseconds (e.g., 1735693200000)
endTime: End timestamp in milliseconds (e.g., 1735693200000)
interval: Kline/candlestick interval (see Enums below)
recvWindow: Request validity window in milliseconds (optional, default 5000, max 60000)

Enums

interval: 1m | 3m | 5m | 15m | 30m | 1h | 2h | 4h | 6h | 8h | 12h | 1d | 3d | 1w | 1M

Parameter Validation Rules

symbol: Must match ^[A-Z0-9]+-[A-Z]+$; max 20 characters (e.g., BTC-USDT)
limit: Positive integer; default and max vary per endpoint (typically 500–1000)
startTime / endTime: Unix timestamps in milliseconds; endTime must be ≥ startTime
interval: Must exactly match one of the enum values above
recvWindow: Integer, 1–5000 ms (see Replay Protection)
timestamp: Unix time in milliseconds; must be within recvWindow of server time

Quick Start

Base URLs: see references/base-urls.md

TypeScript helper:

CONSTRAINT: You MUST copy the fetchSwapMarket function below verbatim when generating code. Do NOT rewrite the request or JSON parsing logic. Only modify: (1) BASE URL entries for custom environments, (2) business parameters passed to fetchSwapMarket. This helper is for public GET market endpoints only, not private trading or account APIs.

import JSONBig from "json-bigint";
const JSONBigParse = JSONBig({ storeAsString: true });
// 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 fetchSwapMarket(env: string,
  path: string, params: Record<string, string | number> = {}
) {
  const urls = BASE[env] ?? BASE["prod-live"];
  const requiresTimestamp = path === "/openApi/swap/v1/tradingRules"
    || path === "/openApi/swap/v1/market/historicalTrades";
  const all = requiresTimestamp ? { ...params, timestamp: Date.now() } : { ...params };
  validateParams(all);
  const qs = new URLSearchParams(
    Object.entries(all).map(([k, v]) => [k, String(v)])
  ).toString();
  for (const base of urls) {
    try {
      const url = `${base}${path}${qs ? `?${qs}` : ""}`;
      const res = await fetch(url, {
        method: "GET",
        headers: { "X-SOURCE-KEY": "BX-AI-SKILL" },
        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 fetchSwapMarket 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

24h ticker price for BTC-USDT:

const ticker = await fetchSwapMarket("prod-live",
  "/openApi/swap/v2/quote/ticker", { symbol: "BTC-USDT" }
);
// ticker.lastPrice, ticker.priceChangePercent, ticker.volume

Order book depth (top 20 levels):

const depth = await fetchSwapMarket("prod-live",
  "/openApi/swap/v2/quote/depth", { symbol: "BTC-USDT", limit: 20 }
);
// depth.bids: [price, qty][], depth.asks: [price, qty][]

1-hour klines (last 100 candles):

const klines = await fetchSwapMarket("prod-live",
  "/openApi/swap/v3/quote/klines", { symbol: "BTC-USDT", interval: "1h", limit: 100 }
);
// Each item: [openTime, open, high, low, close, volume, closeTime]

Current funding rate:

const funding = await fetchSwapMarket("prod-live",
  "/openApi/swap/v2/quote/fundingRate", { symbol: "BTC-USDT" }
);
// funding.fundingRate, funding.nextFundingTime

Best bid/ask price:

const bookTicker = await fetchSwapMarket("prod-live",
  "/openApi/swap/v2/quote/bookTicker", { symbol: "BTC-USDT" }
);
// bookTicker.bidPrice, bookTicker.askPrice

Trading rules and historical trades (timestamp generated by the helper):

const rules = await fetchSwapMarket("prod-live",
  "/openApi/swap/v1/tradingRules", { symbol: "BTC-USDT" }
);
const historicalTrades = await fetchSwapMarket("prod-live",
  "/openApi/swap/v1/market/historicalTrades", { symbol: "BTC-USDT", limit: 10 }
);

Additional Resources

For complete parameter descriptions, optional fields, 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.

swap-market provides public read-only market data. Do not request API keys or sign these requests. Trading rules and historical trades still require a dynamic timestamp. No CONFIRM needed. The interaction goal is to collect query parameters.

Operation Identification

When the user's request is vague (e.g. "check the market" or "look at BTC"), first identify what type of data they want to query:

Please select the market data type:

Price / 24h change — ticker

Best bid/ask price (top of book) — bookTicker

Order book depth — depth

K-lines / Candlesticks — klines

Funding rate — fundingRate

Mark price / Premium index — premiumIndex

Open interest — openInterest

Contract specification list — contracts

When symbol is missing

Applicable endpoints: depth, trades, fundingRate, klines, openInterest

Please select a trading pair (or type another):

BTC-USDT

ETH-USDT

SOL-USDT

BNB-USDT

Other (enter manually, format: BASE-USDT)

If the trading pair can be inferred from context (e.g. "BTC market today" or "Ethereum funding rate"), infer it automatically without asking again.

When interval is missing (klines endpoint only)

Please select a K-line interval:

1m (1 minute)

5m (5 minutes)

15m (15 minutes)

1h (1 hour)

4h (4 hours)

1d (daily)

1w (weekly)

limit handling

klines: default 100, no need to ask — inform the user "returning the most recent 100 K-lines by default"
depth: default 20, no need to ask

Endpoints where symbol is optional

symbol is optional for ticker and premiumIndex (returns all contracts if omitted). bookTicker requires symbol. If the user does not specify a trading pair for ticker/premiumIndex, query all contracts and inform the user; if a trading pair is specified, query only that pair.

bingx-swap-market

BingX Swap Market Data

Quick Reference