@dshtrading/connector-okx 0.1.0

package/lib/index.js

@@ -0,0 +1,869 @@
+import { BAR_MAP, OKX_INTERVAL_VOCABULARY, OkxRestClient, TradingServiceError, barDurationMs, buildAuthHeaders, isoTimestamp, normalizeOkxSymbol, normalizeSize, signPayload, signaturePrehash, toBar, toCanonicalOkxSymbol, toOkxSwapInstId } from "./rest.js";
+import { Service } from "@deepseek-ai/cordis";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import Schema from "@deepseek-ai/schemastery";
+import { createGetIndicatorsTool } from "@dshtrading/indicators/tool";
+//#region src/index.ts
+/**
+* Cordis 插件名 = preset 行 id（TEMPLATES §8）：`dsh-trading-crypto-*` 市场命名空间，
+* 全仓唯一，绝不使用 `base` 等官方保留 id（insert-only 铁律 #1）。
+*/
+const name = "dsh-trading-crypto-connector-okx";
+const Config = Schema.object({
+	enabled: Schema.boolean().default(false),
+	env: Schema.union(["demo", "live"]).default("demo"),
+	dryRun: Schema.boolean().default(true),
+	liveTrading: Schema.boolean().default(false),
+	apiKeyRef: Schema.string().default("OKX_API_KEY"),
+	secretRef: Schema.string().default("OKX_SECRET_KEY"),
+	passphraseRef: Schema.string().default("OKX_PASSPHRASE"),
+	demoApiKeyRef: Schema.string().default("OKX_DEMO_API_KEY"),
+	demoSecretRef: Schema.string().default("OKX_DEMO_SECRET_KEY"),
+	demoPassphraseRef: Schema.string().default("OKX_DEMO_PASSPHRASE")
+});
+/** 需要宿主提供的 Cordis 服务。 */
+const inject = ["tools"];
+/** ctx 服务键（与 @dshtrading/api 的 Context 模块增强一致）。 */
+const TRADING_CRYPTO_MARKET_DATA_KEY = "tradingCryptoMarketData";
+const TRADING_CRYPTO_TRADE_KEY = "tradingCryptoTrade";
+/** credentialRef 语义（DSH credentials 包校验 ^[A-Za-z_][A-Za-z0-9_]*$，镜像镜像）。 */
+const CREDENTIAL_REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** env → ref 组：demo 用 demo*Ref（默认 OKX_DEMO_*），live 用 live 组（默认 OKX_*）。 */
+function credentialRefsFor(config, env = config.env) {
+	return env === "live" ? {
+		apiKeyRef: config.apiKeyRef,
+		secretRef: config.secretRef,
+		passphraseRef: config.passphraseRef
+	} : {
+		apiKeyRef: config.demoApiKeyRef,
+		secretRef: config.demoSecretRef,
+		passphraseRef: config.demoPassphraseRef
+	};
+}
+/**
+* 三 ref 凭证解析：每次操作调用（ctx.credentials 的设计意图——换 key 无需重启插件）。
+* 无 credentials seam 时回落启动环境变量（llm-deepseek 同款降级）。
+* 任何一处未命中/无效 → TRADING_CREDENTIALS_MISSING，消息只带 ref 名（绝不带值）。
+*/
+async function resolveCredentials(ctx, config) {
+	const routerCreds = (ctx.get("tradingMarketRouter") ?? void 0)?.getCredential?.("okx");
+	if (routerCreds?.apiKey && (routerCreds?.secretKey || routerCreds?.secret) && routerCreds?.passphrase) return {
+		key: routerCreds.apiKey,
+		secret: routerCreds.secretKey || routerCreds.secret,
+		passphrase: routerCreds.passphrase
+	};
+	const refs = credentialRefsFor(config);
+	for (const ref of [
+		refs.apiKeyRef,
+		refs.secretRef,
+		refs.passphraseRef
+	]) if (!CREDENTIAL_REF_PATTERN.test(ref)) throw new TradingServiceError("TRADING_CREDENTIALS_MISSING", `connector-okx: credential ref ${JSON.stringify(ref)} is not a valid environment-variable name (env=${config.env})`);
+	const resolver = ctx.get("credentials") ?? void 0;
+	const entries = [
+		["apiKeyRef", refs.apiKeyRef],
+		["secretRef", refs.secretRef],
+		["passphraseRef", refs.passphraseRef]
+	];
+	const resolved = await Promise.all(entries.map(async ([slot, ref]) => {
+		let value;
+		if (resolver !== void 0) value = (await resolver.resolve(ref))?.value;
+		if (value === void 0 || value === "") value = process.env[ref];
+		return {
+			slot,
+			ref,
+			value
+		};
+	}));
+	const missing = resolved.filter((part) => part.value === void 0 || part.value === "");
+	if (missing.length > 0) throw new TradingServiceError("TRADING_CREDENTIALS_MISSING", `connector-okx: missing OKX ${config.env} credentials — provide ` + missing.map((part) => `${part.slot}=${part.ref}`).join(", ") + ` through the credentials service or the launching environment (env=${config.env}; demo and live API keys are separate and not interchangeable)`);
+	const [apiKey, secret, passphrase] = resolved.map((part) => part.value);
+	return {
+		key: apiKey,
+		secret,
+		passphrase
+	};
+}
+const SUBSCRIBE_MIN_MS = 250;
+const SUBSCRIBE_DEFAULT_MS = 5e3;
+var OkxMarketDataService = class extends Service {
+	client;
+	constructor(ctx, options = {}, client, serviceName = TRADING_CRYPTO_MARKET_DATA_KEY) {
+		super(ctx, serviceName);
+		this.client = client ?? new OkxRestClient(options);
+	}
+	getTicker(instId) {
+		return this.client.getTicker(instId);
+	}
+	getKlines(instId, interval, limit) {
+		return this.client.getKlines(instId, interval, limit);
+	}
+	listInstruments() {
+		return this.client.listInstruments();
+	}
+	/** OKX 专属扩展（MarketDataService 契约之外）：SWAP 资金费率。 */
+	getFundingRate(instId) {
+		return this.client.getFundingRate(instId);
+	}
+	/** 盘口快照（api 可选契约 getOrderbook，issue #39）：books 20 档透传。 */
+	getOrderbook(symbol) {
+		return this.client.getOrderbook(symbol);
+	}
+	/** 最近逐笔成交（api 可选契约 getRecentTrades，issue #39），时间升序。 */
+	getRecentTrades(symbol, limit = 50) {
+		return this.client.getRecentTrades(symbol, limit);
+	}
+	/**
+	* 衍生品指标快照（api 可选契约 getDerivatives，issue #38）：聚合 OKX 公共端点
+	* （funding-rate / open-interest / rubik 多空账户比 / rubik taker 买卖量）。
+	* 现货输入经 toOkxSwapInstId 升到对应永续（GUI 选中 BTCUSDT 也能看合约指标）。
+	* 任一子查询失败只降级该字段（undefined，面板按缺格隐藏）；全部失败才抛
+	* 结构化错误（桥层转 ok:false，前端不弹横幅）。
+	*/
+	async getDerivatives(symbol) {
+		const swapId = toOkxSwapInstId(symbol);
+		const spotId = swapId.replace(/-SWAP$/, "");
+		const ccy = swapId.split("-")[0] ?? "";
+		const unavailable = [];
+		const collect = (label, task) => task.catch((error) => {
+			unavailable.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+		});
+		const [funding, interest, ratio, taker, mark, index] = await Promise.all([
+			collect("funding", this.client.getFundingRate(swapId)),
+			collect("open-interest", this.client.getOpenInterest(swapId)),
+			ccy === "" ? Promise.resolve(void 0) : collect("long-short-ratio", this.client.getLongShortAccountRatio(ccy)),
+			ccy === "" ? Promise.resolve(void 0) : collect("taker-volume", this.client.getContractTakerVolume(ccy)),
+			collect("mark-price", this.client.getMarkPrice(swapId)),
+			collect("index-price", this.client.getIndexPrice(spotId))
+		]);
+		const fundingRate = funding?.fundingRate;
+		const nextFundingRate = funding?.nextFundingRate;
+		const nextFundingTime = funding?.nextFundingTime;
+		const openInterest = interest?.oiCcy ?? interest?.oi;
+		const openInterestValue = interest?.oiUsd;
+		const longShortRatio = ratio?.ratio;
+		const takerBuySellRatio = taker !== void 0 && taker.sellVol > 0 ? taker.buyVol / taker.sellVol : void 0;
+		const markPrice = mark?.markPrice;
+		const indexPrice = index?.indexPrice;
+		if (fundingRate === void 0 && openInterest === void 0 && openInterestValue === void 0 && longShortRatio === void 0 && takerBuySellRatio === void 0 && markPrice === void 0 && indexPrice === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX derivatives for ${swapId}: all sub-queries failed` + (unavailable.length > 0 ? ` (${unavailable.join("; ")})` : ""));
+		return {
+			symbol: toCanonicalOkxSymbol(swapId),
+			source: "okx",
+			...openInterest !== void 0 ? { openInterest } : {},
+			...openInterestValue !== void 0 ? { openInterestValue } : {},
+			...longShortRatio !== void 0 ? { longShortRatio } : {},
+			...takerBuySellRatio !== void 0 ? { takerBuySellRatio } : {},
+			...fundingRate !== void 0 ? { fundingRate } : {},
+			...nextFundingRate !== void 0 ? { nextFundingRate } : {},
+			...nextFundingTime !== void 0 ? { nextFundingTime } : {},
+			...markPrice !== void 0 ? { markPrice } : {},
+			...indexPrice !== void 0 ? { indexPrice } : {},
+			timestamp: interest?.ts ?? funding?.fundingTime ?? Date.now()
+		};
+	}
+	/**
+	* 衍生品历史序列（api 可选契约 getDerivativesHistory，issue #54）：
+	* funding-rate-history + rubik open-interest-history 双端点聚合并发拉取，
+	* 任一失败只降级该序列（字段缺省 → 对应趋势卡隐藏），全部失败才抛结构化错误。
+	*/
+	async getDerivativesHistory(symbol) {
+		const swapId = toOkxSwapInstId(symbol);
+		const unavailable = [];
+		const collect = (label, task) => task.catch((error) => {
+			unavailable.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+		});
+		const [fundingRates, openInterest] = await Promise.all([collect("funding-history", this.client.getFundingRateHistory(swapId, 30)), collect("oi-history", this.client.getOpenInterestHistory(swapId, 30))]);
+		if (fundingRates === void 0 && openInterest === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX derivatives history for ${swapId}: all sub-queries failed` + (unavailable.length > 0 ? ` (${unavailable.join("; ")})` : ""));
+		return {
+			symbol: toCanonicalOkxSymbol(swapId),
+			source: "okx",
+			...fundingRates !== void 0 && fundingRates.length > 0 ? { fundingRates } : {},
+			...openInterest !== void 0 && openInterest.length > 0 ? { openInterest } : {}
+		};
+	}
+	subscribeTicker(instId, cb, options) {
+		const ms = Math.max(options?.intervalMs ?? SUBSCRIBE_DEFAULT_MS, SUBSCRIBE_MIN_MS);
+		const tick = () => {
+			this.client.getTicker(instId).then(cb, () => {});
+		};
+		tick();
+		const timer = setInterval(tick, ms);
+		return { dispose: () => clearInterval(timer) };
+	}
+};
+const INSTRUMENT_TTL_MS = 36e5;
+var OkxTradeService = class extends Service {
+	client;
+	config;
+	getCredentials;
+	/** instId → 规格 缓存；key 前缀 demo:/live: —— demo 与实盘 ctVal 是否一致未实证（调研待验证 #5），按环境分桶。 */
+	instruments = /* @__PURE__ */ new Map();
+	constructor(ctx, options, serviceName = TRADING_CRYPTO_TRADE_KEY) {
+		super(ctx, serviceName);
+		this.client = options.client;
+		this.config = options.config;
+		this.getCredentials = options.getCredentials;
+	}
+	get simulated() {
+		return this.config.env === "demo";
+	}
+	auth(credentials) {
+		return {
+			credentials,
+			simulated: this.simulated
+		};
+	}
+	/** 规格（带 TTL 缓存；demo/live 分桶）。查不到 → TRADING_UNSUPPORTED_SYMBOL。 */
+	async getInstrument(instId) {
+		const bucket = `${this.simulated ? "demo" : "live"}:${instId}`;
+		const cached = this.instruments.get(bucket);
+		if (cached !== void 0 && Date.now() - cached.at < INSTRUMENT_TTL_MS) return cached.instrument;
+		const instType = instId.endsWith("-SWAP") ? "SWAP" : "SPOT";
+		const row = (await this.client.getInstruments(instType, instId))[0];
+		if (row === void 0) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `OKX: unknown instId ${instId} (instType=${instType})`);
+		this.instruments.set(bucket, {
+			instrument: row,
+			at: Date.now()
+		});
+		return row;
+	}
+	/**
+	* 下单（api TradeService 契约）。
+	*
+	* **服务缝闸门（P0 · 铁律 #3 修订版 [S4]）**：三态检查以 evaluateOrderGate 同源语义
+	* 下推到服务实现内第一步——绕过工具层直调本服务（dsh-tool-cordis 动态包宿主半、
+	* 未来任何新消费面）同样 fail-closed；工具层 evaluateOrderGate + base 审批闸门保留
+	* （双保险），工具层只做参数预检与富回执。
+	*
+	* - 闸门 ① reject（dryRun=false 请求实盘而 liveTrading=false）→ 结构化错误抛出
+	*   （TRADING_LIVE_TRADING_DISABLED，api TradingError 契约）；
+	* - 闸门 ② simulate（dryRun 缺省/true，或 config.dryRun 强制模拟）→ 本地模拟回执
+	*   （Order.dryRun=true，不触网；工具层另有带市价参照的富回执）；
+	* - 闸门 ③ live（dryRun=false 且 liveTrading=true）→ 真实签名下单（env=demo 加模拟盘头）。
+	*
+	* **sz 单位纪律（调研 §4，实现期最重要的换算）**：
+	* - api `OrderRequest.quantity` 语义恒为 base 币数；
+	* - SPOT：market 单显式 `tgtCcy: 'base_ccy'` —— OKX 现货市价 buy 缺省按计价币
+	*   （USDT）金额，若不显式指定，想买 0.01 BTC 却传 0.01 会被当成 0.01 USDT，
+	*   这是两所词汇最大的坑；limit 单恒为 base 币数；
+	* - SWAP：`sz` 单位是「张」，币数 = sz × ctVal —— 服务层按 instruments 的
+	*   ctVal/lotSz/minSz 换算并本地校验（向下取整，省一次 51000 往返）。
+	*/
+	async placeOrder(req) {
+		const verdict = evaluateOrderGate(this.config, {
+			instId: req.symbol,
+			side: req.side,
+			type: req.type,
+			quantity: req.quantity,
+			...req.price !== void 0 ? { price: req.price } : {},
+			dryRun: req.dryRun
+		});
+		if (verdict.action === "reject") throw new TradingServiceError(verdict.code, verdict.message);
+		if (verdict.action === "simulate") {
+			const instId = normalizeOkxSymbol(req.symbol);
+			return {
+				id: `dry-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+				symbol: toCanonicalOkxSymbol(instId),
+				side: req.side,
+				type: req.type,
+				status: "filled",
+				...req.price !== void 0 ? { price: req.price } : {},
+				quantity: req.quantity,
+				dryRun: true,
+				timestamp: Date.now()
+			};
+		}
+		const instId = normalizeOkxSymbol(req.symbol);
+		const instrument = await this.getInstrument(instId);
+		const normalized = normalizeSize(instId, instrument, req.quantity);
+		const params = {
+			instId,
+			tdMode: instrument.instType === "SWAP" ? "cross" : "cash",
+			side: req.side,
+			ordType: req.type,
+			sz: normalized.sz,
+			...req.type === "limit" ? { px: String(req.price) } : {},
+			...req.type === "market" && normalized.tgtCcy !== void 0 ? { tgtCcy: normalized.tgtCcy } : {}
+		};
+		const credentials = await this.getCredentials();
+		const first = (await this.client.placeOrder(params, this.auth(credentials)))[0];
+		const ordId = typeof first.ordId === "string" && first.ordId !== "" ? first.ordId : void 0;
+		if (ordId === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX place order for ${instId}: missing ordId in response`);
+		return {
+			id: ordId,
+			symbol: toCanonicalOkxSymbol(instId),
+			side: req.side,
+			type: req.type,
+			status: "new",
+			...req.price !== void 0 ? { price: req.price } : {},
+			quantity: req.quantity,
+			dryRun: false,
+			timestamp: Date.now()
+		};
+	}
+	/**
+	* 撤单。OKX 按 instId + ordId 双键定位，symbol（instId）必填——api 契约的
+	* cancelOrder(id) 单参形态对 OKX 不够，扩展第二可选参数（api 包 R3 修订）。
+	*
+	* 撤单幂等化（调研 §5「实现期定」）：51400（订单已成交/已撤/不存在）/51603（订单
+	* 不存在）视作终态成功——撤单语义是「确保不再成交」，订单已终态即达成。
+	*/
+	async cancelOrder(id, symbol) {
+		if (!this.config.liveTrading || this.config.dryRun) throw new TradingServiceError("TRADING_LIVE_TRADING_DISABLED", "OKX cancelOrder rejected at the service seam: cancel is a live action and requires liveTrading=true with dryRun=false (keep liveTrading=false if the order was not placed through this service).");
+		if (symbol === void 0 || symbol === "") throw new TradingServiceError("TRADING_EXCHANGE_ERROR", "OKX cancelOrder requires the instId (symbol) together with the order id — OKX locates orders by (instId, ordId)");
+		const instId = normalizeOkxSymbol(symbol);
+		const credentials = await this.getCredentials();
+		try {
+			await this.client.cancelOrder(instId, id, this.auth(credentials));
+		} catch (error) {
+			if (error instanceof TradingServiceError && error.code === "TRADING_EXCHANGE_ERROR" && /\bsCode=(51400|51603)\b/.test(error.message)) return;
+			throw error;
+		}
+	}
+	/** 查单（api TradeService R3 新增成员）：state → OrderStatus 映射见 ORDER_STATE_MAP。 */
+	async getOrder(symbol, id) {
+		const instId = normalizeOkxSymbol(symbol);
+		const credentials = await this.getCredentials();
+		const d = (await this.client.getOrder(instId, id, this.auth(credentials)))[0];
+		const ordId = typeof d.ordId === "string" ? d.ordId : id;
+		const side = d.side === "sell" ? "sell" : "buy";
+		const ordType = d.ordType === "market" ? "market" : "limit";
+		const state = typeof d.state === "string" ? d.state : "";
+		const instrument = await this.getInstrument(instId);
+		const toCoins = (exchangeAmount) => {
+			const n = typeof exchangeAmount === "string" || typeof exchangeAmount === "number" ? Number(exchangeAmount) : NaN;
+			if (!Number.isFinite(n)) return void 0;
+			return instrument.instType === "SWAP" && instrument.ctVal !== void 0 ? n * instrument.ctVal : n;
+		};
+		const quantity = toCoins(d.sz);
+		if (quantity === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX order ${ordId}: missing/invalid sz`);
+		const filledQuantity = toCoins(d.accFillSz);
+		const price = typeof d.px === "string" && d.px !== "" ? Number(d.px) : typeof d.avgPx === "string" && d.avgPx !== "" ? Number(d.avgPx) : void 0;
+		const timestamp = typeof d.uTime === "string" ? Number(d.uTime) : typeof d.cTime === "string" ? Number(d.cTime) : Date.now();
+		return {
+			id: ordId,
+			symbol: toCanonicalOkxSymbol(instId),
+			side,
+			type: ordType,
+			status: mapOrderState(state),
+			...price !== void 0 && Number.isFinite(price) ? { price } : {},
+			quantity,
+			...filledQuantity !== void 0 ? { filledQuantity } : {},
+			dryRun: false,
+			timestamp: Number.isFinite(timestamp) ? timestamp : Date.now()
+		};
+	}
+	/** 只读持仓（SWAP 的 pos 单位是张 → 经 ctVal 换算成币；net 模式负 pos = short）。 */
+	async getPositions() {
+		const credentials = await this.getCredentials();
+		const rows = await this.client.getPositions(this.auth(credentials));
+		const positions = [];
+		for (const row of rows) {
+			const d = row;
+			const instId = typeof d.instId === "string" ? d.instId : void 0;
+			const pos = typeof d.pos === "string" || typeof d.pos === "number" ? Number(d.pos) : NaN;
+			if (instId === void 0 || !Number.isFinite(pos)) continue;
+			let size = Math.abs(pos);
+			if (instId.endsWith("-SWAP")) try {
+				const instrument = await this.getInstrument(instId);
+				if (instrument.ctVal !== void 0) size = size * instrument.ctVal;
+			} catch {}
+			const posSide = d.posSide === "long" || d.posSide === "short" ? d.posSide : "net";
+			const side = posSide === "net" ? pos >= 0 ? "long" : "short" : posSide;
+			const entryPrice = typeof d.avgPx === "string" ? Number(d.avgPx) : void 0;
+			const markPrice = typeof d.markPx === "string" ? Number(d.markPx) : void 0;
+			const unrealizedPnl = typeof d.upl === "string" ? Number(d.upl) : void 0;
+			const leverage = typeof d.lever === "string" ? Number(d.lever) : void 0;
+			const timestamp = typeof d.uTime === "string" ? Number(d.uTime) : Date.now();
+			positions.push({
+				symbol: toCanonicalOkxSymbol(instId),
+				side,
+				size,
+				...entryPrice !== void 0 && Number.isFinite(entryPrice) ? { entryPrice } : {},
+				...markPrice !== void 0 && Number.isFinite(markPrice) ? { markPrice } : {},
+				...unrealizedPnl !== void 0 && Number.isFinite(unrealizedPnl) ? { unrealizedPnl } : {},
+				...leverage !== void 0 && Number.isFinite(leverage) ? { leverage } : {},
+				timestamp: Number.isFinite(timestamp) ? timestamp : Date.now()
+			});
+		}
+		return positions;
+	}
+	/** 只读余额（TradeService 契约外扩展，crypto_get_balance 工具消费）。 */
+	async getBalances() {
+		const credentials = await this.getCredentials();
+		const rows = await this.client.getBalance(this.auth(credentials));
+		const balances = [];
+		for (const row of rows) {
+			const account = row;
+			const details = Array.isArray(account.details) ? account.details : [];
+			for (const detail of details) {
+				const d = detail;
+				const asset = typeof d.ccy === "string" ? d.ccy : void 0;
+				if (asset === void 0) continue;
+				const free = pickNumber(d.availEq, d.availBal, d.eq);
+				const locked = pickNumber(d.frozenBal);
+				balances.push({
+					asset,
+					free: free ?? 0,
+					locked: locked ?? 0
+				});
+			}
+		}
+		return balances;
+	}
+	/** SWAP 的 sz/accFillSz/fillSz（张）→ base 币数（规格缓存，非 SWAP 原值）。 */
+	async toCoins(instId, exchangeAmount) {
+		const n = typeof exchangeAmount === "string" || typeof exchangeAmount === "number" ? Number(exchangeAmount) : NaN;
+		if (!Number.isFinite(n)) return void 0;
+		if (!instId.endsWith("-SWAP")) return n;
+		try {
+			const instrument = await this.getInstrument(instId);
+			return instrument.ctVal !== void 0 ? n * instrument.ctVal : n;
+		} catch {
+			return n;
+		}
+	}
+	/** 当前挂单（TradeService 可选契约，issue #40；只读、需凭证）。 */
+	async listOpenOrders(symbol) {
+		const instId = symbol !== void 0 && symbol !== "" ? normalizeOkxSymbol(symbol) : void 0;
+		const credentials = await this.getCredentials();
+		const rows = await this.client.listPendingOrders(instId, this.auth(credentials));
+		const orders = [];
+		for (const row of rows) {
+			const d = row;
+			const ordId = typeof d.ordId === "string" ? d.ordId : void 0;
+			const rawInstId = typeof d.instId === "string" ? d.instId : void 0;
+			if (ordId === void 0 || rawInstId === void 0) continue;
+			const quantity = await this.toCoins(rawInstId, d.sz);
+			if (quantity === void 0) continue;
+			const filledQuantity = await this.toCoins(rawInstId, d.accFillSz);
+			const price = typeof d.px === "string" && d.px !== "" ? Number(d.px) : typeof d.avgPx === "string" && d.avgPx !== "" ? Number(d.avgPx) : void 0;
+			const state = typeof d.state === "string" ? d.state : "";
+			const timestamp = typeof d.uTime === "string" ? Number(d.uTime) : typeof d.cTime === "string" ? Number(d.cTime) : Date.now();
+			orders.push({
+				id: ordId,
+				symbol: toCanonicalOkxSymbol(rawInstId),
+				side: d.side === "sell" ? "sell" : "buy",
+				type: d.ordType === "market" ? "market" : "limit",
+				status: state === "partially_filled" ? "partially_filled" : "new",
+				...price !== void 0 && Number.isFinite(price) ? { price } : {},
+				quantity,
+				...filledQuantity !== void 0 ? { filledQuantity } : {},
+				dryRun: false,
+				timestamp: Number.isFinite(timestamp) ? timestamp : Date.now()
+			});
+		}
+		return orders;
+	}
+	/** 最近成交流水（TradeService 可选契约，issue #40；只读、需凭证，时间升序）。 */
+	async listTradeFills(symbol, limit = 50) {
+		const instId = symbol !== void 0 && symbol !== "" ? normalizeOkxSymbol(symbol) : void 0;
+		const capped = Math.max(1, Math.min(Math.floor(limit) || 50, 100));
+		const credentials = await this.getCredentials();
+		const rows = await this.client.listFillsHistory(instId, capped, this.auth(credentials));
+		const fills = [];
+		for (const row of rows) {
+			const d = row;
+			const rawInstId = typeof d.instId === "string" ? d.instId : void 0;
+			const price = pickNumber(d.fillPx);
+			if (rawInstId === void 0 || price === void 0) continue;
+			const amount = await this.toCoins(rawInstId, d.fillSz);
+			if (amount === void 0) continue;
+			const fee = pickNumber(d.fee);
+			const feeAsset = typeof d.feeCcy === "string" && d.feeCcy !== "" ? d.feeCcy : void 0;
+			fills.push({
+				id: typeof d.billId === "string" ? d.billId : String(d.billId ?? ""),
+				symbol: toCanonicalOkxSymbol(rawInstId),
+				side: d.side === "sell" ? "sell" : "buy",
+				price,
+				amount,
+				...fee !== void 0 ? { fee: Math.abs(fee) } : {},
+				...feeAsset !== void 0 ? { feeAsset } : {},
+				timestamp: pickNumber(d.ts) ?? Date.now()
+			});
+		}
+		return fills.reverse();
+	}
+};
+function pickNumber(...values) {
+	for (const value of values) {
+		const n = typeof value === "string" && value !== "" ? Number(value) : typeof value === "number" ? value : NaN;
+		if (Number.isFinite(n)) return n;
+	}
+}
+/** OKX state → api OrderStatus（本切片 vocab：live/partially_filled/filled/canceled）。 */
+function mapOrderState(state) {
+	switch (state) {
+		case "live": return "new";
+		case "partially_filled": return "partially_filled";
+		case "filled": return "filled";
+		case "canceled":
+		case "mmp_canceled": return "canceled";
+		default: return "rejected";
+	}
+}
+function evaluateOrderGate(config, args) {
+	const requestedDryRun = args.dryRun ?? true;
+	if (!requestedDryRun && !config.liveTrading) return {
+		action: "reject",
+		code: "TRADING_LIVE_TRADING_DISABLED",
+		message: `crypto_place_order rejected: the call requests real execution (dryRun=${String(args.dryRun)}) but live trading is disabled (liveTrading=false). Ask the user to enable liveTrading explicitly after confirmation, or keep dryRun=true for a simulated fill.`
+	};
+	if (requestedDryRun || config.dryRun) return { action: "simulate" };
+	return {
+		action: "live",
+		environment: config.env
+	};
+}
+/** 参数校验（模型调用问题抛普通 Error；服务故障才用错误词汇，connector-binance 先例）。 */
+function validatePlaceOrderArgs(args) {
+	try {
+		normalizeOkxSymbol(args.instId);
+	} catch {
+		throw new Error(`crypto_place_order: invalid instId ${JSON.stringify(args.instId)} — expected market-canonical (BTCUSDT / BTCUSDT-SWAP) or OKX native (BTC-USDT / BTC-USDT-SWAP)`);
+	}
+	if (args.side !== "buy" && args.side !== "sell") throw new Error(`crypto_place_order: invalid side ${JSON.stringify(args.side)} — expected buy or sell`);
+	if (args.type !== "market" && args.type !== "limit") throw new Error(`crypto_place_order: invalid type ${JSON.stringify(args.type)} — expected market or limit`);
+	if (typeof args.quantity !== "number" || !Number.isFinite(args.quantity) || args.quantity <= 0) throw new Error(`crypto_place_order: invalid quantity ${JSON.stringify(args.quantity)} — expected a positive base-asset quantity`);
+	if (args.type === "limit" && (typeof args.price !== "number" || !Number.isFinite(args.price) || args.price <= 0)) throw new Error("crypto_place_order: LIMIT orders require a positive price");
+}
+function normalizePlaceOrderArgs(raw) {
+	const args = raw ?? {};
+	const instId = typeof args.instId === "string" ? args.instId.trim().toUpperCase() : void 0;
+	return {
+		...args,
+		instId
+	};
+}
+async function buildDryRunReceipt(args, marketData) {
+	let reference;
+	try {
+		const ticker = await marketData.getTicker(args.instId);
+		reference = {
+			source: "okx-public-ticker",
+			price: ticker.price,
+			bid: ticker.bid,
+			ask: ticker.ask,
+			timestamp: ticker.timestamp
+		};
+	} catch (error) {
+		reference = {
+			source: "okx-public-ticker",
+			unavailable: error instanceof Error ? error.message : String(error)
+		};
+	}
+	return JSON.stringify({
+		status: "filled",
+		dryRun: true,
+		note: "DRY-RUN — simulated fill; no order was sent to OKX. The reference price is market data only, not a fill price.",
+		id: `dry-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+		instId: args.instId,
+		side: args.side,
+		type: args.type,
+		quantity: args.quantity,
+		quantityUnit: "base-asset coins (SWAP orders would be converted to contracts by ctVal)",
+		...args.type === "limit" ? { price: args.price } : {},
+		reference,
+		timestamp: Date.now()
+	});
+}
+/**
+* crypto_place_order 工具工厂（独立导出便于单测三态闸门矩阵）。
+*
+* 审批不在这里做：dryRun!==true 的调用由 @dshtrading/base 的 gate 插件在
+* `tools/pre-execute` waterfall 统一 ask（headless 下 ask=deny，fail-closed）；
+* 工具内不再重复调 ctx.approval。
+*/
+function createPlaceOrderTool(deps) {
+	return defineTool({
+		name: "crypto_place_order",
+		description: "Place an OKX spot or perpetual-swap (SWAP) order, or simulate one. instId accepts market-canonical (BTCUSDT, BTCUSDT-SWAP) or OKX native (BTC-USDT, BTC-USDT-SWAP) vocabulary. quantity is in BASE-ASSET coins: spot MARKET orders are sent with tgtCcy=base_ccy (OKX default for buys is quote-currency amount — a known trap), and SWAP quantities are converted to contracts via ctVal automatically. dryRun defaults to true and returns a DRY-RUN simulated fill receipt with the current market price as reference. Real execution (dryRun=false) requires the plugin liveTrading switch plus user approval; with env=demo (default) the order is signed and routed to the OKX demo exchange (simulated trading), env=live is real money.",
+		parameters: {
+			instId: {
+				type: "string",
+				required: true,
+				description: "Instrument id — market-canonical (BTCUSDT spot / BTCUSDT-SWAP perpetual) or OKX native (BTC-USDT / BTC-USDT-SWAP)"
+			},
+			side: {
+				type: "string",
+				enum: ["buy", "sell"],
+				required: true,
+				description: "Order side (OKX lowercase vocabulary)"
+			},
+			type: {
+				type: "string",
+				enum: ["market", "limit"],
+				required: true,
+				description: "Order type (OKX ordType)"
+			},
+			quantity: {
+				type: "number",
+				required: true,
+				description: "Base asset quantity in coins (e.g. 0.01 BTC); SWAP orders are converted to contracts internally"
+			},
+			price: {
+				type: "number",
+				description: "Limit price; required when type=limit"
+			},
+			dryRun: {
+				type: "boolean",
+				description: "true (default) = simulate only and return a DRY-RUN receipt; false = request real execution (gated by liveTrading, env and user approval)",
+				default: true
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const args = normalizePlaceOrderArgs(raw);
+			validatePlaceOrderArgs(args);
+			const verdict = evaluateOrderGate(deps.config, args);
+			if (verdict.action === "reject") return JSON.stringify({
+				status: "rejected",
+				code: verdict.code,
+				message: verdict.message
+			});
+			if (verdict.action === "simulate") return buildDryRunReceipt(args, deps.marketData);
+			const order = await deps.trade.placeOrder({
+				symbol: args.instId,
+				side: args.side,
+				type: args.type,
+				quantity: args.quantity,
+				...args.type === "limit" ? { price: args.price } : {},
+				dryRun: false
+			});
+			return JSON.stringify(order);
+		}
+	});
+}
+/**
+* 互斥激活的注册面：dsh-tools 对同名重复注册直接抛错（会炸 boot/preset 挂载），
+* 而互斥纪律下「同时至多一个连接器激活」只是配置约定。这里把冲突降级为
+* 「先到先得 + log」：已被占用（binance 或 kit-crypto 先注册）的名字跳过。
+*/
+function registerTool(ctx, tool, log) {
+	const tools = ctx.tools;
+	if (tools.get(tool.name) !== void 0) {
+		log.warn("[dsh-trading-crypto-connector-okx] tool %s already registered by another provider — skipped (mutual exclusion: at most one crypto connector/toolset may be active)", tool.name);
+		return;
+	}
+	tools.register(tool);
+}
+function logger(ctx) {
+	const service = ctx.logger;
+	return typeof service === "function" ? service(name) : console;
+}
+/** 本连接器的路由 provider slug（docs/exchange-routing.md §2.2）。 */
+const ROUTER_PROVIDER = "okx";
+function apply(ctx, config) {
+	const log = logger(ctx);
+	if (!config.enabled) {
+		log.info("[dsh-trading-crypto-connector-okx] not activated (enabled=false) — tradingCryptoMarketData/tradingCryptoTrade and crypto_* tools stay unregistered");
+		return;
+	}
+	const router = ctx.get?.("tradingMarketRouter", false);
+	const active = router?.activeProvider("crypto");
+	if (router !== void 0 && active !== "okx") {
+		log.info("[dsh-trading-crypto-connector-okx] market router selects %s for crypto — not activated; set dshtrading.markets.crypto.provider to okx to use this connector", String(active ?? "(unset)"));
+		return;
+	}
+	const client = new OkxRestClient();
+	const marketData = new OkxMarketDataService(ctx, {}, client);
+	const trade = new OkxTradeService(ctx, {
+		client,
+		config,
+		getCredentials: () => resolveCredentials(ctx, config)
+	});
+	ctx.inject(["tradingCryptoMarketData"], () => {
+		registerTool(ctx, createGetIndicatorsTool({
+			marketData,
+			providerLabel: "okx"
+		}), log);
+		registerTool(ctx, defineTool({
+			name: "crypto_get_ticker",
+			description: "Get the latest public ticker (last price, bid/ask, 24h volume) for an OKX instrument via the OKX public REST API. instId accepts market-canonical (BTCUSDT spot, BTCUSDT-SWAP perpetual) or OKX native vocabulary. No credentials required.",
+			parameters: { instId: {
+				type: "string",
+				required: true,
+				description: "Instrument id — market-canonical (BTCUSDT / BTCUSDT-SWAP) or OKX native (BTC-USDT / BTC-USDT-SWAP)"
+			} },
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{
+					type: "text",
+					text: value
+				}]
+			},
+			async execute(args) {
+				const ticker = await marketData.getTicker(args.instId);
+				return JSON.stringify(ticker);
+			}
+		}), log);
+		registerTool(ctx, defineTool({
+			name: "crypto_get_klines",
+			description: "Get recent public klines (candles: open/high/low/close/volume) for an OKX instrument via the OKX public REST API. Intervals use the dsh-trading vocabulary (1m..1M); 1d maps to OKX 1Dutc (UTC day boundary, consistent with Binance daily bars). No credentials required.",
+			parameters: {
+				instId: {
+					type: "string",
+					required: true,
+					description: "Instrument id — market-canonical (BTCUSDT / BTCUSDT-SWAP) or OKX native (BTC-USDT / BTC-USDT-SWAP)"
+				},
+				interval: {
+					type: "string",
+					enum: [...OKX_INTERVAL_VOCABULARY],
+					description: "Kline interval (dsh-trading vocabulary; no 8h — OKX has no 8-hour bar)",
+					default: "1h"
+				},
+				limit: {
+					type: "integer",
+					description: "Number of candles to return (1-300, OKX max 300)",
+					default: 100
+				}
+			},
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{
+					type: "text",
+					text: value
+				}]
+			},
+			async execute(args) {
+				const interval = args.interval ?? "1h";
+				const limit = args.limit ?? 100;
+				const klines = await marketData.getKlines(args.instId, interval, limit);
+				return JSON.stringify(klines);
+			}
+		}), log);
+		registerTool(ctx, defineTool({
+			name: "crypto_funding_rate",
+			description: "Get the current and next funding rate for an OKX perpetual swap (instId like BTCUSDT-SWAP or BTC-USDT-SWAP) via the OKX public REST API. No credentials required.",
+			parameters: { instId: {
+				type: "string",
+				required: true,
+				description: "OKX perpetual swap instrument id, e.g. BTCUSDT-SWAP (canonical) or BTC-USDT-SWAP (native)"
+			} },
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{
+					type: "text",
+					text: value
+				}]
+			},
+			async execute(args) {
+				const funding = await marketData.getFundingRate(args.instId);
+				return JSON.stringify(funding);
+			}
+		}), log);
+	});
+	ctx.inject(["tradingCryptoTrade"], () => {
+		registerTool(ctx, createPlaceOrderTool({
+			marketData,
+			trade,
+			config
+		}), log);
+		registerTool(ctx, defineTool({
+			name: "crypto_cancel_order",
+			description: "Cancel an OKX order by (instId, ordId). Cancelling an already-terminal order (filled/canceled) is reported as already-terminal, not an error.",
+			parameters: {
+				instId: {
+					type: "string",
+					required: true,
+					description: "Instrument id the order belongs to — canonical (BTCUSDT) or native (BTC-USDT)"
+				},
+				ordId: {
+					type: "string",
+					required: true,
+					description: "OKX order id (ordId from place/get order)"
+				}
+			},
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{
+					type: "text",
+					text: value
+				}]
+			},
+			async execute(args) {
+				await trade.cancelOrder(args.ordId, args.instId);
+				return JSON.stringify({
+					status: "canceled",
+					instId: args.instId,
+					ordId: args.ordId,
+					timestamp: Date.now()
+				});
+			}
+		}), log);
+		registerTool(ctx, defineTool({
+			name: "crypto_get_order",
+			description: "Query one OKX order by (instId, ordId): state, filled quantity, average price. Read-only.",
+			parameters: {
+				instId: {
+					type: "string",
+					required: true,
+					description: "Instrument id — canonical (BTCUSDT / BTCUSDT-SWAP) or native (BTC-USDT)"
+				},
+				ordId: {
+					type: "string",
+					required: true,
+					description: "OKX order id"
+				}
+			},
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{
+					type: "text",
+					text: value
+				}]
+			},
+			async execute(args) {
+				const order = await trade.getOrder(args.instId, args.ordId);
+				return JSON.stringify(order);
+			}
+		}), log);
+		registerTool(ctx, defineTool({
+			name: "crypto_get_balance",
+			description: "Read the OKX account balances (available/frozen per currency) via the signed REST API. Requires the configured credential refs to resolve.",
+			parameters: {},
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{
+					type: "text",
+					text: value
+				}]
+			},
+			async execute() {
+				const balances = await trade.getBalances();
+				return JSON.stringify({
+					env: config.env,
+					simulated: config.env === "demo",
+					balances
+				});
+			}
+		}), log);
+		registerTool(ctx, defineTool({
+			name: "crypto_get_positions",
+			description: "Read the OKX account positions (size converted from contracts to coins for swaps, entry/mark price, unrealized PnL, leverage). Read-only.",
+			parameters: {},
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{
+					type: "text",
+					text: value
+				}]
+			},
+			async execute() {
+				const positions = await trade.getPositions();
+				return JSON.stringify({
+					env: config.env,
+					simulated: config.env === "demo",
+					positions
+				});
+			}
+		}), log);
+	});
+}
+//#endregion
+export { BAR_MAP, Config, OKX_INTERVAL_VOCABULARY, OkxMarketDataService, OkxRestClient, OkxTradeService, ROUTER_PROVIDER, TRADING_CRYPTO_MARKET_DATA_KEY, TRADING_CRYPTO_TRADE_KEY, TradingServiceError, apply, barDurationMs, buildAuthHeaders, buildDryRunReceipt, createPlaceOrderTool, credentialRefsFor, evaluateOrderGate, inject, isoTimestamp, mapOrderState, name, normalizeOkxSymbol, normalizeSize, resolveCredentials, signPayload, signaturePrehash, toBar, toCanonicalOkxSymbol, toOkxSwapInstId };