@dshtrading/connector-okx 0.1.0

package/lib/rest.js

@@ -0,0 +1,716 @@
+import { createHmac } from "node:crypto";
+//#region src/rest.ts
+/**
+* OKX REST 客户端（dsh-trading okx 切片 R1-R3）。
+*
+* 独立于插件 glue：仅依赖 @dshtrading/api 类型词汇 + node:crypto（HMAC-SHA256），
+* 无 cordis/dsh-tools 运行时依赖；fetch 可注入，便于单测与脚本直接消费。
+*
+* 数据面（docs/okx-integration.md §2/§3，2026-08-31 调研）：
+* - REST base = https://openapi.okx.com（生产与模拟盘同 host；demo 完全靠
+*   `x-simulated-trading: 1` 请求头区分，REST 层无独立域名）。
+* - 限频口径为「每 2 秒 N 次」，本客户端不主动限速，只做 10s 超时与结构化错误映射。
+*
+* 签名（调研 §1）：
+* - prehash = timestamp + METHOD + requestPath + body（字符串直连）；
+* - OK-ACCESS-SIGN = Base64(HMAC-SHA256(secret, prehash))；
+* - timestamp = UTC ISO 8601 毫秒精度（如 2020-12-08T09:08:57.715Z）；
+* - GET 的 query string 属于 requestPath（body 参与签名同理，JSON 原样）；
+* - 时差 >30s 即 50102：首个签名请求前先 GET /api/v5/public/time 对时并缓存偏移，
+*   收到 50102 时重对时并重试一次。
+*
+* @module @dshtrading/connector-okx/rest
+*/
+/** api 包 TradingError 契约的运行时 Error 实现（connector-binance 同款）。 */
+var TradingServiceError = class extends Error {
+	code;
+	constructor(code, message, cause) {
+		super(message);
+		this.name = "TradingServiceError";
+		this.code = code;
+		if (cause !== void 0) this.cause = cause;
+	}
+};
+/**
+* 拼接签名 prehash：`timestamp + METHOD + requestPath + body`（调研 §1）。
+* GET 的 query 必须已并入 requestPath；无 body 时省略（传 undefined）。
+*/
+function signaturePrehash(timestamp, method, requestPath, body) {
+	return timestamp + method + requestPath + (body ?? "");
+}
+/** OK-ACCESS-SIGN：Base64(HMAC-SHA256(secret, prehash))。 */
+function signPayload(secret, prehash) {
+	return createHmac("sha256", secret).update(prehash, "utf8").digest("base64");
+}
+/** OK-ACCESS-TIMESTAMP：UTC ISO 8601 毫秒精度（Date.toISOString 即该形态）。 */
+function isoTimestamp(epochMs) {
+	return new Date(epochMs).toISOString();
+}
+/** 四头 + 模拟盘头的构造（导出供单测断言头部集合）。 */
+function buildAuthHeaders(auth, timestamp, method, requestPath, body) {
+	const headers = {
+		"OK-ACCESS-KEY": auth.credentials.key,
+		"OK-ACCESS-SIGN": signPayload(auth.credentials.secret, signaturePrehash(timestamp, method, requestPath, body)),
+		"OK-ACCESS-TIMESTAMP": timestamp,
+		"OK-ACCESS-PASSPHRASE": auth.credentials.passphrase
+	};
+	if (auth.simulated) headers["x-simulated-trading"] = "1";
+	return headers;
+}
+/**
+* api Interval（Binance 词汇）→ OKX bar 词汇。
+*
+* **1d → 1Dutc（口径裁决，回应调研待验证 #3）**：OKX `1D` 按 UTC+8 零点开盘
+* （用户实证记忆：1D 日线边界对齐 UTC+8），而本仓 `Interval` 的 `1d` 语义继承自
+* Binance = UTC 零点。crypto 24/7 交易、UTC 是跨所通用口径，取 `1Dutc` 才能与
+* connector-binance 的日线对齐同一日界；`1D`（UTC+8）会导致同一标的跨连接器日 K
+* 错位 8 小时，故不取。6h/12h/3d/1w/1M 同理取 utc 变体。
+*
+* **8h 无映射**：OKX bar 词汇没有 8 小时档（1m..4H、6Hutc、12Hutc、1Dutc、2Dutc、
+* 3Dutc、1Wutc、1Mutc、3Mutc），8h 请求返回 TRADING_UNSUPPORTED_INTERVAL。
+*/
+const BAR_MAP = {
+	"1m": "1m",
+	"3m": "3m",
+	"5m": "5m",
+	"15m": "15m",
+	"30m": "30m",
+	"1h": "1H",
+	"2h": "2H",
+	"4h": "4H",
+	"6h": "6Hutc",
+	"12h": "12Hutc",
+	"1d": "1Dutc",
+	"3d": "3Dutc",
+	"1w": "1Wutc",
+	"1M": "1Mutc"
+};
+/** 支持的 interval 词汇（工具 enum 用；8h 刻意缺席，见 BAR_MAP 注释）。 */
+const OKX_INTERVAL_VOCABULARY = Object.keys(BAR_MAP);
+/** bar → 毫秒时长（closeTime 补算用；UTC 变体与本地变体时长相同）。 */
+function barDurationMs(bar) {
+	const m = /^(\d+)(m|H|D|W|M)(?:utc)?$/.exec(bar);
+	if (!m) throw new TradingServiceError("TRADING_UNSUPPORTED_INTERVAL", `OKX: unknown bar ${bar}`);
+	const amount = Number(m[1]);
+	switch (m[2]) {
+		case "m": return amount * 6e4;
+		case "H": return amount * 36e5;
+		case "D": return amount * 864e5;
+		case "W": return amount * 7 * 864e5;
+		case "M": return amount * 30 * 864e5;
+	}
+}
+/** Interval → OKX bar；不支持（含 8h）抛 TRADING_UNSUPPORTED_INTERVAL。 */
+function toBar(interval) {
+	const bar = BAR_MAP[interval];
+	if (bar === void 0) throw new TradingServiceError("TRADING_UNSUPPORTED_INTERVAL", `OKX klines: unsupported interval ${String(interval)} — OKX bar vocabulary has no 8h candle; supported: ${OKX_INTERVAL_VOCABULARY.join("/")}`);
+	return bar;
+}
+const DEFAULT_BASE_URL = "https://openapi.okx.com";
+const DEFAULT_TIMEOUT_MS = 1e4;
+/**
+* OKX code → api 词汇已知映射（调研 §5）。51000/51400/51603 及其余 5xxxx 走
+* TRADING_EXCHANGE_ERROR 兜底；HTTP 层 5xx → TRADING_NETWORK、429 → RATE_LIMITED、
+* 401/403 → AUTH_FAILED（envelope code 命中本表时优先于 HTTP 状态，更具体）。
+*/
+const OKX_CODE_MAP = /* @__PURE__ */ new Map([
+	["50011", "TRADING_RATE_LIMITED"],
+	["50013", "TRADING_RATE_LIMITED"],
+	["50103", "TRADING_CREDENTIALS_MISSING"],
+	["50104", "TRADING_CREDENTIALS_MISSING"],
+	["50111", "TRADING_CREDENTIALS_MISSING"],
+	["50105", "TRADING_AUTH_FAILED"],
+	["50102", "TRADING_AUTH_FAILED"],
+	["50112", "TRADING_AUTH_FAILED"],
+	["50113", "TRADING_AUTH_FAILED"],
+	["50114", "TRADING_AUTH_FAILED"],
+	["50110", "TRADING_AUTH_FAILED"],
+	["51008", "TRADING_INSUFFICIENT_BALANCE"]
+]);
+function num(value) {
+	if (value === "") return void 0;
+	const n = typeof value === "string" ? Number(value) : typeof value === "number" ? value : NaN;
+	return Number.isFinite(n) ? n : void 0;
+}
+function str(value) {
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+/** envelope/HTTP → TradingServiceError（msg/sCode 原文进 message，envelope 原样进 cause）。
+*  body 已由调用方解析时直接传入（Response 体只能读一次，重复 json() 会拿到 undefined）。 */
+async function envelopeToError(res, path, parsedBody) {
+	let body = parsedBody;
+	if (body === void 0) try {
+		body = await res.json();
+	} catch {
+		body = void 0;
+	}
+	const env = body ?? {};
+	const code = str(env.code);
+	const msg = str(env.msg) ?? "";
+	const first = Array.isArray(env.data) ? env.data[0] : void 0;
+	const sCode = str(first?.sCode);
+	const sMsg = str(first?.sMsg);
+	let tradingCode;
+	const meaningfulCode = code === "1" || code === "2" ? sCode !== void 0 && sCode !== "0" ? sCode : void 0 : code !== void 0 && code !== "0" ? code : sCode !== void 0 && sCode !== "0" ? sCode : void 0;
+	if (meaningfulCode !== void 0 && OKX_CODE_MAP.has(meaningfulCode)) tradingCode = OKX_CODE_MAP.get(meaningfulCode);
+	else if (meaningfulCode !== void 0) tradingCode = "TRADING_EXCHANGE_ERROR";
+	else if (res.status === 429 || res.status === 418) tradingCode = "TRADING_RATE_LIMITED";
+	else if (res.status === 401 || res.status === 403) tradingCode = "TRADING_AUTH_FAILED";
+	else if (res.status >= 500) tradingCode = "TRADING_NETWORK";
+	else tradingCode = "TRADING_EXCHANGE_ERROR";
+	const detail = [
+		res.status,
+		code !== void 0 && code !== "0" ? `code=${code}` : void 0,
+		sCode !== void 0 && sCode !== "0" ? `sCode=${sCode}` : void 0,
+		msg || sMsg || res.statusText
+	].filter((part) => part !== void 0 && part !== "").join(" ");
+	return new TradingServiceError(tradingCode, `OKX ${path}: ${detail}`, body);
+}
+/** 把 api 语义的 base 币数量换算成 OKX sz（本地精度校验：minSz/lotSz，省一次 51000 往返）。 */
+function normalizeSize(instId, instrument, quantityCoins) {
+	const isSwap = instrument.instType === "SWAP";
+	const amountInExchangeUnit = isSwap ? quantityCoins / (instrument.ctVal ?? NaN) : quantityCoins;
+	if (!Number.isFinite(amountInExchangeUnit) || amountInExchangeUnit <= 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX ${instId}: quantity ${quantityCoins} does not convert to a positive exchange amount` + (isSwap ? ` (ctVal=${String(instrument.ctVal)})` : ""));
+	if (amountInExchangeUnit < instrument.minSz) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX ${instId}: quantity ${quantityCoins} coins = ${amountInExchangeUnit} ${isSwap ? "contracts" : "base units"} is below minSz ${instrument.minSz}`);
+	const step = instrument.lotSz;
+	const units = Math.floor(amountInExchangeUnit / step + 1e-9) * step;
+	if (units <= 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX ${instId}: quantity ${quantityCoins} coins rounds down to 0 at lotSz ${step}`);
+	const sz = trimNumber(units);
+	return isSwap ? { sz } : {
+		sz,
+		tgtCcy: "base_ccy"
+	};
+}
+/** 输出无尾随浮点噪声的数量字符串（最多 12 位有效小数）。 */
+function trimNumber(n) {
+	const fixed = n.toFixed(12).replace(/0+$/, "").replace(/\.$/, "");
+	return fixed === "" ? "0" : fixed;
+}
+var OkxRestClient = class {
+	baseUrl;
+	timeoutMs;
+	fetchImpl;
+	clockSyncEnabled;
+	now;
+	/** 服务器偏移缓存（server - local，ms）；null = 未对时。 */
+	clockOffsetMs;
+	constructor(options = {}) {
+		this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+		this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		this.fetchImpl = options.fetchImpl ?? ((input, init) => globalThis.fetch(input, init));
+		this.clockSyncEnabled = options.clockSync ?? true;
+		this.now = options.now ?? (() => Date.now());
+		this.clockOffsetMs = options.clockOffsetMs ?? null;
+	}
+	/** 当前对时后的墙钟（ms）。clockOffsetMs 预置或已缓存时直接用；否则按需对时。 */
+	async timestampMs() {
+		if (this.clockOffsetMs !== null) return this.now() + this.clockOffsetMs;
+		if (!this.clockSyncEnabled) return this.now();
+		const serverTs = num((await this.request("/api/v5/public/time"))[0]?.ts);
+		this.clockOffsetMs = serverTs !== void 0 ? serverTs - this.now() : 0;
+		return this.now() + this.clockOffsetMs;
+	}
+	/** 使缓存偏移失效（50102 重试路径）。 */
+	invalidateClock() {
+		this.clockOffsetMs = null;
+	}
+	/**
+	* 统一请求：query 拼 URL 与签名 requestPath；签名头经 buildAuthHeaders；
+	* envelope code!=='0'（含 '1' 失败 / '2' 部分成功——本客户端只发单条操作）映射为
+	* 结构化错误；50102（时差）重对时重试一次。
+	*/
+	async request(path, options = {}, allowRetry = true) {
+		const method = options.method ?? "GET";
+		const query = options.query ? new URLSearchParams(options.query).toString() : "";
+		const requestPath = query ? `${path}?${query}` : path;
+		const target = `${this.baseUrl}${requestPath}`;
+		const headers = {};
+		if (options.body !== void 0) headers["Content-Type"] = "application/json";
+		if (options.auth !== void 0) {
+			const timestamp = isoTimestamp(await this.timestampMs());
+			Object.assign(headers, buildAuthHeaders(options.auth, timestamp, method, requestPath, options.body));
+		}
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(new DOMException(`request timed out after ${this.timeoutMs}ms`, "TimeoutError")), this.timeoutMs);
+		let res;
+		try {
+			res = await this.fetchImpl(target, {
+				method,
+				headers,
+				...options.body !== void 0 ? { body: options.body } : {},
+				signal: controller.signal
+			});
+		} catch (cause) {
+			const timedOut = controller.signal.aborted;
+			throw new TradingServiceError("TRADING_NETWORK", timedOut ? `OKX ${path}: request timed out after ${this.timeoutMs}ms` : `OKX ${path}: network error`, cause);
+		} finally {
+			clearTimeout(timer);
+		}
+		try {
+			return await this.processEnvelope(res, path);
+		} catch (error) {
+			if (allowRetry && options.auth !== void 0 && error instanceof TradingServiceError && error.code === "TRADING_AUTH_FAILED" && /\b50102\b/.test(error.message)) {
+				this.invalidateClock();
+				return this.request(path, options, false);
+			}
+			throw error;
+		}
+	}
+	/** envelope/HTTP 状态处理：code==='0' → data；单行 trade 端点的 sCode 非 0 → 失败。 */
+	async processEnvelope(res, path) {
+		if (!res.ok) throw await envelopeToError(res, path);
+		let parsed;
+		try {
+			parsed = await res.json();
+		} catch (cause) {
+			throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX ${path}: invalid JSON response`, cause);
+		}
+		const env = parsed;
+		if (str(env.code) !== "0" || !Array.isArray(env.data)) throw await envelopeToError(res, path, parsed);
+		const data = env.data;
+		const first = data[0];
+		const sCode = str(first?.sCode);
+		if (sCode !== void 0 && sCode !== "0") throw await envelopeToError(res, path, parsed);
+		return data;
+	}
+	/** 最新行情：GET /api/v5/market/ticker。 */
+	async getTicker(instId) {
+		const id = normalizeOkxSymbol(instId);
+		const d = (await this.request("/api/v5/market/ticker", { query: { instId: id } }))[0];
+		const price = num(d?.last);
+		if (price === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX ticker for ${id}: missing/invalid last price`);
+		const volume = id.endsWith("-SWAP") ? num(d?.volCcy24h) ?? num(d?.vol24h) : num(d?.vol24h);
+		const prevClose = num(d?.open24h) ?? num(d?.sodUtc0);
+		const changePercent = price !== void 0 && prevClose !== void 0 && prevClose > 0 ? (price - prevClose) / prevClose * 100 : void 0;
+		return {
+			symbol: toCanonicalOkxSymbol(str(d?.instId) ?? id),
+			price,
+			timestamp: num(d?.ts) ?? Date.now(),
+			...num(d?.bidPx) !== void 0 ? { bid: num(d?.bidPx) } : {},
+			...num(d?.askPx) !== void 0 ? { ask: num(d?.askPx) } : {},
+			...volume !== void 0 ? { volume } : {},
+			...prevClose !== void 0 ? { prevClose } : {},
+			...changePercent !== void 0 ? { changePercent } : {}
+		};
+	}
+	/** K 线：GET /api/v5/market/candles（单请求上限 300，超出走 after 游标翻页；响应新→旧，翻转为旧→新）。 */
+	async getKlines(instId, interval, limit = 100) {
+		const id = normalizeOkxSymbol(instId);
+		const bar = toBar(interval);
+		if (!Number.isInteger(limit) || limit < 1 || limit > 1e3) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX klines: limit must be an integer within 1..1000, got ${limit}`);
+		const collected = [];
+		const seenOpenTimes = /* @__PURE__ */ new Set();
+		let cursor;
+		while (collected.length < limit) {
+			const pageSize = Math.min(limit - collected.length, 300);
+			const query = {
+				instId: id,
+				bar,
+				limit: String(pageSize)
+			};
+			if (cursor !== void 0) query.after = String(cursor);
+			const rows = await this.request("/api/v5/market/candles", { query });
+			if (!Array.isArray(rows)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX klines for ${id}: unexpected response shape`);
+			if (rows.length === 0) break;
+			for (const row of rows) {
+				if (!Array.isArray(row) || row.length < 6) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX klines: malformed row for ${id}`);
+				const openTime = num(row[0]);
+				const open = num(row[1]);
+				const high = num(row[2]);
+				const low = num(row[3]);
+				const close = num(row[4]);
+				const volume = num(row[5]);
+				if (openTime === void 0 || open === void 0 || high === void 0 || low === void 0 || close === void 0 || volume === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX klines: malformed row values for ${id}`);
+				if (seenOpenTimes.has(openTime)) continue;
+				seenOpenTimes.add(openTime);
+				collected.push({
+					openTime,
+					open,
+					high,
+					low,
+					close,
+					volume,
+					closeTime: openTime + barDurationMs(bar) - 1
+				});
+			}
+			if (rows.length < pageSize) break;
+			const oldest = num(rows[rows.length - 1][0]);
+			if (oldest === void 0) break;
+			cursor = oldest;
+		}
+		return collected.reverse();
+	}
+	/** 资金费率：GET /api/v5/public/funding-rate（仅 SWAP；10 次/2s）。 */
+	async getFundingRate(instId) {
+		const id = normalizeOkxSymbol(instId);
+		if (!id.endsWith("-SWAP")) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `OKX funding rate requires a perpetual swap instId (e.g. BTC-USDT-SWAP), got ${id}`);
+		const d = (await this.request("/api/v5/public/funding-rate", { query: { instId: id } }))[0];
+		const fundingRate = num(d?.fundingRate);
+		const fundingTime = num(d?.fundingTime);
+		if (fundingRate === void 0 || fundingTime === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX funding rate for ${id}: missing/invalid fields`);
+		const nextFundingRate = num(d?.nextFundingRate);
+		const nextFundingTime = num(d?.nextFundingTime);
+		return {
+			instId: str(d?.instId) ?? id,
+			fundingRate,
+			fundingTime,
+			...nextFundingRate !== void 0 ? { nextFundingRate } : {},
+			...nextFundingTime !== void 0 ? { nextFundingTime } : {}
+		};
+	}
+	/** 标记价格：GET /api/v5/public/mark-price（仅 SWAP；2026-09-03 真实网络实证）。 */
+	async getMarkPrice(instId) {
+		const id = normalizeOkxSymbol(instId);
+		const d = (await this.request("/api/v5/public/mark-price", { query: {
+			instType: "SWAP",
+			instId: id
+		} }))[0];
+		const markPrice = num(d?.markPx);
+		if (markPrice === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX mark price for ${id}: missing/invalid markPx`);
+		return {
+			instId: str(d?.instId) ?? id,
+			markPrice,
+			ts: num(d?.ts) ?? Date.now()
+		};
+	}
+	/**
+	* 指数价格：GET /api/v5/market/index-tickers（现货指数成分 instId，如 HYPE-USDT；
+	* 与永续 markPx 配对算基差。2026-09-03 真实网络实证）。
+	*/
+	async getIndexPrice(instId) {
+		const id = normalizeOkxSymbol(instId);
+		const d = (await this.request("/api/v5/market/index-tickers", { query: { instId: id } }))[0];
+		const indexPrice = num(d?.idxPx);
+		if (indexPrice === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX index price for ${id}: missing/invalid idxPx`);
+		return {
+			instId: str(d?.instId) ?? id,
+			indexPrice,
+			ts: num(d?.ts) ?? Date.now()
+		};
+	}
+	/** 资金费率历史：GET /api/v5/public/funding-rate-history（响应新→旧 → 反转为升序）。 */
+	async getFundingRateHistory(instId, limit = 30) {
+		const id = normalizeOkxSymbol(instId);
+		const capped = Math.max(1, Math.min(Math.floor(limit) || 30, 100));
+		const rows = await this.request("/api/v5/public/funding-rate-history", { query: {
+			instId: id,
+			limit: String(capped)
+		} });
+		const points = [];
+		for (const row of rows) {
+			const d = row;
+			const time = num(d.fundingTime);
+			const value = num(d.fundingRate);
+			if (time !== void 0 && value !== void 0) points.push({
+				time,
+				value
+			});
+		}
+		return points.reverse();
+	}
+	/**
+	* OI 历史：GET /api/v5/rubik/stat/contracts/open-interest-history（period=1D）。
+	* 响应是时间序列行 `[ts, oi张, oiCcy币, oiUsd]`（字符串数值，新→旧；
+	* 2026-09-03 真实网络实证）；取值列与快照同纪律——优先币数（oiCcy），退张数。
+	*/
+	async getOpenInterestHistory(instId, limit = 30) {
+		const id = normalizeOkxSymbol(instId);
+		const capped = Math.max(1, Math.min(Math.floor(limit) || 30, 100));
+		const rows = await this.request("/api/v5/rubik/stat/contracts/open-interest-history", { query: {
+			instId: id,
+			period: "1D",
+			limit: String(capped)
+		} });
+		const points = [];
+		for (const row of rows) {
+			if (!Array.isArray(row)) continue;
+			const time = num(row[0]);
+			const value = num(row[2]) ?? num(row[1]);
+			if (time !== void 0 && value !== void 0) points.push({
+				time,
+				value
+			});
+		}
+		return points.reverse();
+	}
+	/** books 档位行 [price, size, liqOrders, numOrders] → OrderbookLevel。 */
+	#parseBookRow(row) {
+		if (!Array.isArray(row) || row.length < 2) return void 0;
+		const price = num(row[0]);
+		const amount = num(row[1]);
+		if (price === void 0 || amount === void 0 || price <= 0 || amount <= 0) return void 0;
+		return {
+			price,
+			amount
+		};
+	}
+	/** 盘口快照：GET /api/v5/market/books（sz=20 档；bids 降序 / asks 升序，OKX 原生序）。 */
+	async getOrderbook(instId) {
+		const id = normalizeOkxSymbol(instId);
+		const d = (await this.request("/api/v5/market/books", { query: {
+			instId: id,
+			sz: "20"
+		} }))[0];
+		if (d === void 0 || !Array.isArray(d.bids) || !Array.isArray(d.asks)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX books for ${id}: unexpected response shape`);
+		const bids = d.bids.map((row) => this.#parseBookRow(row)).filter((l) => l !== void 0);
+		const asks = d.asks.map((row) => this.#parseBookRow(row)).filter((l) => l !== void 0);
+		const ts = num(d.ts) ?? Date.now();
+		return {
+			symbol: toCanonicalOkxSymbol(id),
+			bids,
+			asks,
+			timestamp: ts
+		};
+	}
+	/** trades 行 → TradeTick（side 即 taker 方向；OKX 响应新→旧，反转为升序）。 */
+	#parseTradeRow(row, symbol) {
+		const d = row;
+		const price = num(d.px);
+		const amount = num(d.sz);
+		if (price === void 0 || amount === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX trades for ${symbol}: malformed trade row`);
+		const side = d.side === "buy" || d.side === "sell" ? d.side : "unknown";
+		return {
+			id: str(d.tradeId) ?? "",
+			symbol,
+			price,
+			amount,
+			side,
+			timestamp: num(d.ts) ?? Date.now()
+		};
+	}
+	/** 最近逐笔成交：GET /api/v5/market/trades（响应新→旧 → 反转为时间升序）。 */
+	async getRecentTrades(instId, limit = 50) {
+		const id = normalizeOkxSymbol(instId);
+		const capped = Math.max(1, Math.min(Math.floor(limit) || 50, 100));
+		const rows = await this.request("/api/v5/market/trades", { query: {
+			instId: id,
+			limit: String(capped)
+		} });
+		const symbol = toCanonicalOkxSymbol(id);
+		return rows.map((row) => this.#parseTradeRow(row, symbol)).reverse();
+	}
+	/** 未平仓合约量：GET /api/v5/public/open-interest（仅 SWAP；oi=张、oiCcy=币、oiUsd=USD）。 */ async getOpenInterest(instId) {
+		const id = normalizeOkxSymbol(instId);
+		if (!id.endsWith("-SWAP")) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `OKX open interest requires a perpetual swap instId (e.g. BTC-USDT-SWAP), got ${id}`);
+		const d = (await this.request("/api/v5/public/open-interest", { query: {
+			instType: "SWAP",
+			instId: id
+		} }))[0];
+		const oi = num(d?.oi);
+		if (oi === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX open interest for ${id}: missing/invalid oi`);
+		const oiCcy = num(d?.oiCcy);
+		const oiUsd = num(d?.oiUsd);
+		const ts = num(d?.ts) ?? Date.now();
+		return {
+			instId: str(d?.instId) ?? id,
+			oi,
+			...oiCcy !== void 0 ? { oiCcy } : {},
+			...oiUsd !== void 0 ? { oiUsd } : {},
+			ts
+		};
+	}
+	/**
+	* 多空账户人数比：GET /api/v5/rubik/stat/contracts/long-short-account-ratio（ccy=base 资产，period=1H）。
+	* 响应是时间序列行 `[ts, ratio]`（字符串数值，新→旧；2026-09-02 真实网络实证，
+	* spikes/impl-crypto-derivatives），取最新一行。
+	*/
+	async getLongShortAccountRatio(ccy) {
+		const row = (await this.request("/api/v5/rubik/stat/contracts/long-short-account-ratio", { query: {
+			ccy,
+			period: "1H"
+		} }))[0];
+		const ratio = Array.isArray(row) ? num(row[1]) : void 0;
+		if (ratio === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX long/short account ratio for ${ccy}: missing/invalid ratio`);
+		const ts = Array.isArray(row) ? num(row[0]) : void 0;
+		return {
+			ccy,
+			ratio,
+			...ts !== void 0 ? { ts } : {}
+		};
+	}
+	/**
+	* 合约主动买卖量：GET /api/v5/rubik/stat/taker-volume（ccy=base 资产，instType=CONTRACTS）。
+	* 响应是时间序列行 `[ts, buyVol, sellVol]`（字符串数值，新→旧；2026-09-02 真实网络
+	* 实证，spikes/impl-crypto-derivatives），取最新一行。
+	*/
+	async getContractTakerVolume(ccy) {
+		const row = (await this.request("/api/v5/rubik/stat/taker-volume", { query: {
+			ccy,
+			instType: "CONTRACTS"
+		} }))[0];
+		const buyVol = Array.isArray(row) ? num(row[1]) : void 0;
+		const sellVol = Array.isArray(row) ? num(row[2]) : void 0;
+		if (buyVol === void 0 || sellVol === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX taker volume for ${ccy}: missing/invalid buyVol/sellVol`);
+		return {
+			ccy,
+			buyVol,
+			sellVol
+		};
+	}
+	/** 合约/币对规格：GET /api/v5/public/instruments（sz 纪律的 ctVal/lotSz/minSz 来源）。 */
+	async getInstruments(instType, instId) {
+		return (await this.request("/api/v5/public/instruments", { query: instId !== void 0 ? {
+			instType,
+			instId
+		} : { instType } })).map((row) => {
+			const d = row;
+			const id = str(d.instId);
+			const lotSz = num(d.lotSz);
+			const minSz = num(d.minSz);
+			const tickSz = num(d.tickSz);
+			if (id === void 0 || lotSz === void 0 || minSz === void 0 || tickSz === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX instruments: malformed row`);
+			const ctVal = num(d.ctVal);
+			return {
+				instId: id,
+				instType: str(d.instType) ?? instType,
+				lotSz,
+				minSz,
+				tickSz,
+				...ctVal !== void 0 ? { ctVal } : {},
+				...str(d.ctValCcy) !== void 0 ? { ctValCcy: str(d.ctValCcy) } : {},
+				...str(d.settleCcy) !== void 0 ? { settleCcy: str(d.settleCcy) } : {},
+				...str(d.baseCcy) !== void 0 ? { baseCcy: str(d.baseCcy) } : {},
+				...str(d.quoteCcy) !== void 0 ? { quoteCcy: str(d.quoteCcy) } : {}
+			};
+		});
+	}
+	/**
+	* 全部可交易现货标的名册（GET /api/v5/public/instruments?instType=SPOT，Issue #15）。
+	* 输出 symbol 归一化为市场规范形（BTC-USDT → BTCUSDT），name 为 baseCcy/quoteCcy。
+	*/
+	async listInstruments() {
+		return (await this.getInstruments("SPOT")).map((inst) => {
+			const canonical = toCanonicalOkxSymbol(inst.instId);
+			const name = inst.baseCcy && inst.quoteCcy ? `${inst.baseCcy}/${inst.quoteCcy}` : void 0;
+			return {
+				symbol: canonical,
+				...name ? { name } : {}
+			};
+		});
+	}
+	/** 只读余额：GET /api/v5/account/balance（ccy 可选，逗号分隔 ≤20）。 */
+	async getBalance(auth, ccy) {
+		return this.request("/api/v5/account/balance", {
+			query: ccy !== void 0 ? { ccy } : void 0,
+			auth
+		});
+	}
+	/** 只读持仓：GET /api/v5/account/positions（instId 可选过滤）。 */
+	async getPositions(auth, instId) {
+		return this.request("/api/v5/account/positions", {
+			query: instId !== void 0 ? { instId } : void 0,
+			auth
+		});
+	}
+	/** 下单：POST /api/v5/trade/order（60 次/2s）。 */
+	async placeOrder(params, auth) {
+		return this.request("/api/v5/trade/order", {
+			method: "POST",
+			body: JSON.stringify(params),
+			auth
+		});
+	}
+	/** 撤单：POST /api/v5/trade/cancel-order（ordId 优先于 clOrdId，本切片只支持 ordId）。 */
+	async cancelOrder(instId, ordId, auth) {
+		return this.request("/api/v5/trade/cancel-order", {
+			method: "POST",
+			body: JSON.stringify({
+				instId,
+				ordId
+			}),
+			auth
+		});
+	}
+	/** 查单：GET /api/v5/trade/order（query 属于签名 requestPath）。 */
+	async getOrder(instId, ordId, auth) {
+		return this.request("/api/v5/trade/order", {
+			query: {
+				instId,
+				ordId
+			},
+			auth
+		});
+	}
+	/** 当前挂单：GET /api/v5/trade/orders-pending（instId 可选过滤；issue #40 交易台）。 */
+	async listPendingOrders(instId, auth) {
+		return this.request("/api/v5/trade/orders-pending", {
+			query: instId !== void 0 ? { instId } : void 0,
+			auth
+		});
+	}
+	/** 最近成交明细：GET /api/v5/trade/fills-history（instId/limit 可选；issue #40 交易台）。 */
+	async listFillsHistory(instId, limit, auth) {
+		const query = {};
+		if (instId !== void 0) query.instId = instId;
+		if (limit !== void 0) query.limit = String(limit);
+		return this.request("/api/v5/trade/fills-history", {
+			query: Object.keys(query).length > 0 ? query : void 0,
+			auth
+		});
+	}
+};
+/** instId 校验（R3 词汇：SPOT `BASE-QUOTE` 与 SWAP `BASE-QUOTE-SWAP`，OKX 原生连字符）。 */
+const INST_ID_PATTERN = /^[A-Z0-9]{1,20}-[A-Z0-9]{1,20}(-SWAP)?$/;
+/**
+* 规范形（crypto canonical）：BASEQUOTE 大写无分隔（BTCUSDT），衍生品预留
+* BASEQUOTE-SWAP。OKX 原生形：BTC-USDT / BTC-USDT-SWAP。
+*/
+/**
+* 已知 quote 货币后缀表（规范形拆 base/quote 的依据；最长匹配优先）。
+* 表是连接器私有实现——新 quote 货币上线在此增补（规范只管词汇形态）。
+*/
+const KNOWN_QUOTES = [
+	"USDT",
+	"USDC",
+	"USD",
+	"EUR",
+	"BTC",
+	"ETH",
+	"OKB"
+];
+/**
+* 输入归一 → OKX 原生 instId。接受规范形（BTCUSDT / BTCUSDT-SWAP）与原生形
+*（BTC-USDT / BTC-USDT-SWAP）；都解析不出才报 TRADING_UNSUPPORTED_SYMBOL。
+*/
+function normalizeOkxSymbol(input) {
+	const id = typeof input === "string" ? input.trim().toUpperCase() : "";
+	const parts = id.split("-");
+	const splitCanonicalPair = (pair, swapSuffix) => {
+		if (!/^[A-Z0-9]{2,24}$/.test(pair)) return void 0;
+		for (const quote of KNOWN_QUOTES) if (pair.length > quote.length && pair.endsWith(quote)) return pair.slice(0, -quote.length) + "-" + quote + swapSuffix;
+	};
+	if (parts.length === 3) {
+		if (INST_ID_PATTERN.test(id)) return id;
+	} else if (parts.length === 2) {
+		if (parts[1] === "SWAP") {
+			const translated = splitCanonicalPair(parts[0] ?? "", "-SWAP");
+			if (translated !== void 0) return translated;
+		} else if (INST_ID_PATTERN.test(id)) return id;
+	} else if (parts.length === 1) {
+		const translated = splitCanonicalPair(id, "");
+		if (translated !== void 0) return translated;
+	}
+	throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", "OKX: cannot parse symbol " + JSON.stringify(input) + " — use market-canonical vocabulary (BTCUSDT / BTCUSDT-SWAP) or OKX native (BTC-USDT / BTC-USDT-SWAP)");
+}
+/**
+* 输出归一 → 规范形（下游永远看到市场规范词汇）。原生 BTC-USDT → BTCUSDT；
+* BTC-USDT-SWAP → BTCUSDT-SWAP；已是规范形则原样返回。
+*/
+function toCanonicalOkxSymbol(symbol) {
+	const id = typeof symbol === "string" ? symbol.trim().toUpperCase() : "";
+	if (!id.includes("-")) return id;
+	const parts = id.split("-");
+	if (parts[parts.length - 1] === "SWAP") return parts.slice(0, -1).join("") + "-SWAP";
+	return parts.join("");
+}
+/**
+* 衍生品端点输入归一：现货与合约输入一律升到永续 SWAP instId——
+* BTCUSDT / BTC-USDT / BTCUSDT-SWAP / BTC-USDT-SWAP → BTC-USDT-SWAP。
+* （GUI 选中的现货标的也要能看到对应合约的衍生品指标，issue #38。）
+*/
+function toOkxSwapInstId(input) {
+	const id = normalizeOkxSymbol(input);
+	return id.endsWith("-SWAP") ? id : `${id}-SWAP`;
+}
+//#endregion
+export { BAR_MAP, OKX_INTERVAL_VOCABULARY, OkxRestClient, TradingServiceError, barDurationMs, buildAuthHeaders, isoTimestamp, normalizeOkxSymbol, normalizeSize, signPayload, signaturePrehash, toBar, toCanonicalOkxSymbol, toOkxSwapInstId };