@dshtrading/connector-okx 0.5.0 → 0.6.1

package/lib/index.d.ts

@@ -1,7 +1,7 @@
-import { BAR_MAP, NormalizedSize, OKX_INTERVAL_VOCABULARY, OkxCredentials, OkxFundingRate, OkxInstrument, OkxOpenInterest, OkxPlaceOrderParams, OkxRestClient, OkxRestOptions, SignedAuth, TradingServiceError, barDurationMs, buildAuthHeaders, isoTimestamp, normalizeOkxSymbol, normalizeSize, signPayload, signaturePrehash, toBar, toCanonicalOkxSymbol, toOkxSwapInstId } from "./rest.js";
+import { BAR_MAP, NormalizedSize, OKX_INTERVAL_VOCABULARY, OkxCredentials, OkxFundingRate, OkxInstrument, OkxOpenInterest, OkxPlaceOrderParams, OkxRestClient, OkxRestOptions, OkxSetLeverageParams, SignedAuth, TradingServiceError, barDurationMs, buildAuthHeaders, coinsToContracts, contractsToCoins, isoTimestamp, normalizeOkxSymbol, normalizeSize, okxAssetClassOf, okxContractOf, signPayload, signaturePrehash, toBar, toCanonicalOkxSymbol, toOkxSwapInstId } from "./rest.js";
 import { Context, Service } from "@deepseek-ai/cordis";
 import Schema from "@deepseek-ai/schemastery";
-import { AccountBalance, DerivativesData, DerivativesHistory, Disposable, Interval, Kline, MarketDataService, Order, OrderRequest, OrderStatus, Orderbook, Position, Ticker, TradeFill, TradeService, TradeTick } from "@dshtrading/api";
+import { AccountBalance, DerivativesData, DerivativesHistory, Disposable, InstrumentRef, Interval, Kline, LeverageSetting, MarginMode, MarketDataService, Order, OrderRequest, OrderStatus, Orderbook, Position, SetLeverageRequest, Ticker, TradeFill, TradeService, TradeTick } from "@dshtrading/api";
 //#region src/index.d.ts
 /**
  * Cordis 插件名 = preset 行 id（TEMPLATES §8）：`dsh-trading-crypto-*` 市场命名空间，
@@ -55,7 +55,9 @@ interface ResolvedCredentialRefs {
 declare function credentialRefsFor(config: Config, env?: 'demo' | 'live'): ResolvedCredentialRefs;
 /**
  * 三 ref 凭证解析：每次操作调用（ctx.credentials 的设计意图——换 key 无需重启插件）。
- * 无 credentials seam 时回落启动环境变量（llm-deepseek 同款降级）。
+ * **有 credentials seam 即 fail-closed**：seam 存在时只认 seam，某 slot 未命中不再回退
+ * 启动环境变量——显式配置与 ambient 凭据混用会让 demo 路径拿到 live key（反之亦然）；
+ * 仅当 seam 完全缺席时才回落启动环境变量（llm-deepseek 同款降级）。
  * 任何一处未命中/无效 → TRADING_CREDENTIALS_MISSING，消息只带 ref 名（绝不带值）。
  */
 declare function resolveCredentials(ctx: CredentialsContext, config: Config): Promise<OkxCredentials>;
@@ -68,10 +70,7 @@ declare class OkxMarketDataService extends Service implements MarketDataService
   constructor(ctx: Context, options?: OkxRestOptions, client?: OkxRestClient, serviceName?: string);
   getTicker(instId: string): Promise<Ticker>;
   getKlines(instId: string, interval: Interval, limit?: number): Promise<Kline[]>;
-  listInstruments(): Promise<Array<{
-    symbol: string;
-    name?: string;
-  }>>;
+  listInstruments(): Promise<InstrumentRef[]>;
   /** OKX 专属扩展（MarketDataService 契约之外）：SWAP 资金费率。 */
   getFundingRate(instId: string): Promise<OkxFundingRate>;
   /** 盘口快照（api 可选契约 getOrderbook，issue #39）：books 20 档透传。 */
@@ -137,11 +136,11 @@ declare class OkxTradeService extends Service implements TradeService {
    * 未来任何新消费面）同样 fail-closed；工具层 evaluateOrderGate + base 审批闸门保留
    * （双保险），工具层只做参数预检与富回执。
    *
-   * - 闸门 ① reject（dryRun=false 请求实盘而 liveTrading=false）→ 结构化错误抛出
+   * - 闸门 ① reject（dryRun=false 请求实盘而未获实盘授权）→ 结构化错误抛出
    *   （TRADING_LIVE_TRADING_DISABLED，api TradingError 契约）；
    * - 闸门 ② simulate（dryRun 缺省/true，或 config.dryRun 强制模拟）→ 本地模拟回执
    *   （Order.dryRun=true，不触网；工具层另有带市价参照的富回执）；
-   * - 闸门 ③ live（dryRun=false 且 liveTrading=true）→ 真实签名下单（env=demo 加模拟盘头）。
+   * - 闸门 ③ live（dryRun=false 且实盘已获授权）→ 真实签名下单（env=demo 加模拟盘头）。
    *
    * **sz 单位纪律（调研 §4，实现期最重要的换算）**：
    * - api `OrderRequest.quantity` 语义恒为 base 币数；
@@ -152,6 +151,23 @@ declare class OkxTradeService extends Service implements TradeService {
    *   ctVal/lotSz/minSz 换算并本地校验（向下取整，省一次 51000 往返）。
    */
   placeOrder(req: OrderRequest): Promise<Order>;
+  /**
+   * 设置合约杠杆与保证金模式（P7；api TradeService.setLeverage）。
+   *
+   * 与 placeOrder 共用同一套三态闸门（服务缝第一步——绕过工具层的直调同样 fail-closed）：
+   * - ① dryRun=false 而未获实盘授权 → TRADING_LIVE_TRADING_DISABLED；
+   * - ② dryRun 缺省/true（或被 config.dryRun 强制）→ 本地模拟回执，不触网；
+   * - ③ dryRun=false 且已获授权 → 真实签名 POST /api/v5/account/set-leverage
+   *   （env=demo 带 x-simulated-trading:1）。
+   *
+   * 本地判据（先于上游往返，给出可读原因、不静默改写调用方意图）：
+   * - 仅永续（form=perp）：现货传 setLeverage 报 TRADING_UNSUPPORTED_SYMBOL；
+   * - leverage > 交易所规格 lever（InstrumentContract.maxLeverage）→ 结构化拒绝，
+   *   **不做上限截断**（静默改小杠杆会让调用方以为自己设定的数字已生效）；
+   * - mgnMode 只认 cross/isolated；isolated + 双向持仓模式的 posSide 由调用方传，
+   *   本仓不猜账户持仓模式（缺席即原样透传，交交易所裁定）。
+   */
+  setLeverage(req: SetLeverageRequest): Promise<LeverageSetting>;
   /**
    * 撤单。OKX 按 instId + ordId 双键定位，symbol（instId）必填——api 契约的
    * cancelOrder(id) 单参形态对 OKX 不够，扩展第二可选参数（api 包 R3 修订）。
@@ -162,7 +178,12 @@ declare class OkxTradeService extends Service implements TradeService {
   cancelOrder(id: string, symbol?: string): Promise<void>;
   /** 查单（api TradeService R3 新增成员）：state → OrderStatus 映射见 ORDER_STATE_MAP。 */
   getOrder(symbol: string, id: string): Promise<Order>;
-  /** 只读持仓（SWAP 的 pos 单位是张 → 经 ctVal 换算成币；net 模式负 pos = short）。 */
+  /**
+   * 只读持仓（SWAP 的 pos 单位是张 → 经 ctVal 换算成币；net 模式负 pos = short）。
+   * 合约仓位附带交易所回传的强平价（liqPx）、维持保证金率（mgnRatio）、保证金模式
+   * （mgnMode）与名义价值（notionalUsd）——风控清单的「强平距离」判据读这些字段，
+   * 每条都是交易所口径，缺席即不展示（不本地补算）。
+   */
   getPositions(): Promise<Position[]>;
   /** 只读余额（TradeService 契约外扩展，crypto_get_balance 工具消费）。 */
   getBalances(): Promise<AccountBalance[]>;
@@ -190,14 +211,19 @@ interface PlaceOrderArgs {
   readonly quantity: number;
   /** LIMIT 单必填（schema 无法条件必填，execute 内校验），必须 > 0。 */
   readonly price?: number;
+  /**
+   * 合约订单的保证金模式（缺省 cross 全仓）；仅永续有效，现货传该字段报
+   * TRADING_UNSUPPORTED_SYMBOL。isolated 需先用 crypto_set_leverage 设好该标的的逐仓杠杆。
+   */
+  readonly marginMode?: MarginMode;
   /** 缺省视为 true：仅模拟。显式 false 即实盘意图，进入三态闸门 ②/③。 */
   readonly dryRun?: boolean;
 }
 /**
  * 三态闸门判定（顺序即铁律 #3 修订版的裁决顺序；主 agent 裁决的三态环境映射）：
- *  - `reject`   —— ① 请求实盘（dryRun!==true）而 liveTrading=false：结构化拒绝；
+ *  - `reject`   —— ① 请求实盘（dryRun!==true）而未获实盘授权：结构化拒绝；
  *  - `simulate` —— ② dryRun=true（显式/缺省/被 config.dryRun 强制）：本地模拟回执；
- *  - `live`     —— ③ dryRun=false 且 liveTrading=true：真实签名下单，environment
+ *  - `live`     —— ③ dryRun=false 且实盘已获授权：真实签名下单，environment
  *                 决定是否带模拟盘头（demo=第一默认目标；live=实盘，base 闸门照旧 ask）。
  */
 type OrderGateVerdict = {
@@ -226,7 +252,7 @@ interface PlaceOrderToolDeps {
   readonly marketData: Pick<OkxMarketDataService, 'getTicker'>;
   /** 交易服务（闸门 ③ 的真实签名下单路径）。 */
   readonly trade: TradeService;
-  /** 插件配置（dryRun 强制模拟 / liveTrading 总闸门 / env 三态）。 */
+  /** 插件配置（dryRun 强制模拟 / liveTrading 非权威镜像——实盘授权由 @dshtrading/authority 的人工签署平面裁定 / env 三态）。 */
   readonly config: Config;
 }
 /**
@@ -237,6 +263,33 @@ interface PlaceOrderToolDeps {
  * 工具内不再重复调 ctx.approval。
  */
 declare function createPlaceOrderTool(deps: PlaceOrderToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** crypto_set_leverage 参数契约（仅永续；dryRun 缺省 true）。 */
+interface SetLeverageArgs {
+  /** 永续 instId：规范形（BTCUSDT-SWAP）或 OKX 原生形（BTC-USDT-SWAP）皆收。 */
+  readonly instId: string;
+  /** 目标杠杆倍数（> 0；上限以交易所规格为准，超出即拒绝，不静默截断）。 */
+  readonly leverage: number;
+  /** 保证金模式：'cross'（缺省，全仓）| 'isolated'（逐仓）。 */
+  readonly marginMode?: MarginMode;
+  /** 双向持仓模式（long/short）下的方向；净持仓模式（net）缺席。 */
+  readonly posSide?: 'long' | 'short';
+  /** 全仓多币种保证金模式下按币种设置时的保证金币。 */
+  readonly ccy?: string;
+  /** 缺省视为 true：仅模拟。显式 false 即实盘意图，进入与下单同门槛的闸门。 */
+  readonly dryRun?: boolean;
+}
+interface SetLeverageToolDeps {
+  /** 交易服务（服务缝三态闸门在实现内第一步）。 */
+  readonly trade: TradeService;
+}
+/**
+ * crypto_set_leverage 工具工厂（独立导出便于单测闸门与参数矩阵）。
+ *
+ * 审批不在这里做：dryRun!==true 的调用由 @dshtrading/base 的统一审批闸门在
+ * `tools/pre-execute` waterfall ask（headless 下 ask=deny，fail-closed）；
+ * 工具内不再重复调 ctx.approval。
+ */
+declare function createSetLeverageTool(deps: SetLeverageToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
 /** 本连接器的路由 provider slug（docs/exchange-routing.md §2.2）。 */
 declare const ROUTER_PROVIDER = "okx";
 /** 市场路由服务的最小消费面（api 包 MarketRouterService 同构；不定死接口）。 */
@@ -245,4 +298,4 @@ interface MarketRouterLike {
 }
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { BAR_MAP, Config, CredentialResolverLike, CredentialsContext, DryRunReference, MarketRouterLike, NormalizedSize, OKX_INTERVAL_VOCABULARY, OkxCredentials, OkxFundingRate, OkxInstrument, OkxMarketDataService, OkxOpenInterest, OkxPlaceOrderParams, OkxRestClient, OkxRestOptions, OkxTradeService, OkxTradeServiceOptions, OrderGateVerdict, PlaceOrderArgs, PlaceOrderToolDeps, ROUTER_PROVIDER, ResolvedCredentialRefs, SignedAuth, SubscribeTickerOptions, 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 };
+export { BAR_MAP, Config, CredentialResolverLike, CredentialsContext, DryRunReference, MarketRouterLike, NormalizedSize, OKX_INTERVAL_VOCABULARY, OkxCredentials, OkxFundingRate, OkxInstrument, OkxMarketDataService, OkxOpenInterest, OkxPlaceOrderParams, OkxRestClient, OkxRestOptions, OkxSetLeverageParams, OkxTradeService, OkxTradeServiceOptions, OrderGateVerdict, PlaceOrderArgs, PlaceOrderToolDeps, ROUTER_PROVIDER, ResolvedCredentialRefs, SetLeverageArgs, SetLeverageToolDeps, SignedAuth, SubscribeTickerOptions, TRADING_CRYPTO_MARKET_DATA_KEY, TRADING_CRYPTO_TRADE_KEY, TradingServiceError, apply, barDurationMs, buildAuthHeaders, buildDryRunReceipt, coinsToContracts, contractsToCoins, createPlaceOrderTool, createSetLeverageTool, credentialRefsFor, evaluateOrderGate, inject, isoTimestamp, mapOrderState, name, normalizeOkxSymbol, normalizeSize, okxAssetClassOf, okxContractOf, resolveCredentials, signPayload, signaturePrehash, toBar, toCanonicalOkxSymbol, toOkxSwapInstId };

package/lib/index.js

@@ -1,10 +1,46 @@
-import { BAR_MAP, OKX_INTERVAL_VOCABULARY, OkxRestClient, TradingServiceError, barDurationMs, buildAuthHeaders, isoTimestamp, normalizeOkxSymbol, normalizeSize, signPayload, signaturePrehash, toBar, toCanonicalOkxSymbol, toOkxSwapInstId } from "./rest.js";
+import { BAR_MAP, OKX_INTERVAL_VOCABULARY, OkxRestClient, TradingServiceError, barDurationMs, buildAuthHeaders, coinsToContracts, contractsToCoins, isoTimestamp, normalizeOkxSymbol, normalizeSize, okxAssetClassOf, okxContractOf, signPayload, signaturePrehash, toBar, toCanonicalOkxSymbol, toOkxSwapInstId } from "./rest.js";
+import { liveTradingEnabled } from "@dshtrading/authority";
 import { Service } from "@deepseek-ai/cordis";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import Schema from "@deepseek-ai/schemastery";
+import { instrumentFormOf } from "@dshtrading/api";
 import { createGetIndicatorsTool } from "@dshtrading/indicators/tool";
 //#region src/index.ts
 /**
+* OKX 连接器插件（dsh-trading okx 切片 R1-R3）：真实 MarketDataService + crypto 市场
+* 第一个真实 TradeService。
+*
+* 与 connector-binance 的关系（主 agent 裁决 2026-08-29，方案 B+C）：
+* - **互斥激活**：Config.enabled（默认 false）。false 时整个 apply() 静默退出——不
+*   provide 服务、不注册任何工具，`tradingCryptoMarketData` 与同名 `crypto_*` 工具
+*   归 connector-binance（binance 不动）；true 时由本插件独占。两连接器并存于同一
+*   组合时必须恰好激活一个。为防御误配置，工具注册走 duplicate-safe 路径：名字已被
+*   占用时跳过并 log（dsh-tools 对重复名直接抛错会炸 boot）。
+* - **交易服务分离**：okx 额外 provide `tradingCryptoTrade`（api 包 TradeService 的
+*   第一个真实实现；类型增强声明在 @dshtrading/api）。
+*
+* 三态环境语义（主 agent 裁决，映射铁律 #3 三段闸门）：
+* - dryRun=true（缺省）→ 本地模拟回执，不发任何请求；
+* - dryRun=false + 未获实盘授权 → 结构化拒绝（headless 唯一防线）；
+* - dryRun=false + 实盘已获授权 + env='demo'（缺省）→ 真实签名下单 +
+*   `x-simulated-trading: 1`，成交在 OKX 模拟盘（获得实盘授权后的第一默认目标
+*   是 demo 而非真钱）；
+* - env='live' → 真实实盘（无模拟盘头；base 统一审批闸门照旧 ask，headless fail-closed）。
+*
+* 合约交易语义（P7，2026-10-08）：永续可下单（tdMode 缺省 cross，isolated 需先
+* crypto_set_leverage 设好该标的的逐仓杠杆）、杠杆/保证金模式设置工具
+* crypto_set_leverage（与下单同一套三态闸门 + base 审批闸门），持仓回带
+* 强平价/维持保证金率/名义价值；张↔币换算的唯一实现在 rest.ts 的
+* coinsToContracts（向下取整，绝不上取放大敞口）。
+*
+* 凭证（调研 §6 建议 4）：三 ref（apiKeyRef/secretRef/passphraseRef）= 环境变量名；
+* demo/live 用不同 ref 组（demo 默认 OKX_DEMO_*，live 默认 OKX_*），每次操作经
+* ctx.credentials.resolve() 解析（换 key 无需重启）；有 seam 时未命中即
+* TRADING_CREDENTIALS_MISSING 带 ref 名（不回退启动环境变量），无 seam 才回落。
+*
+* @module @dshtrading/connector-okx
+*/
+/**
 * Cordis 插件名 = preset 行 id（TEMPLATES §8）：`dsh-trading-crypto-*` 市场命名空间，
 * 全仓唯一，绝不使用 `base` 等官方保留 id（insert-only 铁律 #1）。
 */
@@ -42,7 +78,9 @@ function credentialRefsFor(config, env = config.env) {
 }
 /**
 * 三 ref 凭证解析：每次操作调用（ctx.credentials 的设计意图——换 key 无需重启插件）。
-* 无 credentials seam 时回落启动环境变量（llm-deepseek 同款降级）。
+* **有 credentials seam 即 fail-closed**：seam 存在时只认 seam，某 slot 未命中不再回退
+* 启动环境变量——显式配置与 ambient 凭据混用会让 demo 路径拿到 live key（反之亦然）；
+* 仅当 seam 完全缺席时才回落启动环境变量（llm-deepseek 同款降级）。
 * 任何一处未命中/无效 → TRADING_CREDENTIALS_MISSING，消息只带 ref 名（绝不带值）。
 */
 async function resolveCredentials(ctx, config) {
@@ -65,17 +103,17 @@ async function resolveCredentials(ctx, config) {
 		["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
+			value: resolver === void 0 ? process.env[ref] : (await resolver.resolve(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)`);
+	if (missing.length > 0) {
+		const sourceHint = resolver === void 0 ? "through the launching environment (no credentials seam is configured)" : "through the credentials service (a credentials seam is configured; the launching environment is not consulted)";
+		throw new TradingServiceError("TRADING_CREDENTIALS_MISSING", `connector-okx: missing OKX ${config.env} credentials — provide ` + missing.map((part) => `${part.slot}=${part.ref}`).join(", ") + ` ${sourceHint} (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,
@@ -230,7 +268,7 @@ var OkxTradeService = class extends Service {
 		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 instType = instrumentFormOf(instId) === "perp" ? "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, {
@@ -255,7 +293,7 @@ var OkxTradeService = class extends Service {
 	* 返回 Map 只含成功项：查不到的 instId 缺席，调用点按原语义保留张数原值（不再逐行重试）。
 	*/
 	async prefetchInstruments(instIds) {
-		const distinct = [...new Set([...instIds].filter((id) => id.endsWith("-SWAP")))];
+		const distinct = [...new Set([...instIds].filter((id) => instrumentFormOf(id) === "perp"))];
 		const resolved = /* @__PURE__ */ new Map();
 		for (let i = 0; i < distinct.length; i += INSTRUMENT_PREFETCH_CONCURRENCY) await Promise.all(distinct.slice(i, i + INSTRUMENT_PREFETCH_CONCURRENCY).map(async (id) => {
 			try {
@@ -272,11 +310,11 @@ var OkxTradeService = class extends Service {
 	* 未来任何新消费面）同样 fail-closed；工具层 evaluateOrderGate + base 审批闸门保留
 	* （双保险），工具层只做参数预检与富回执。
 	*
-	* - 闸门 ① reject（dryRun=false 请求实盘而 liveTrading=false）→ 结构化错误抛出
+	* - 闸门 ① reject（dryRun=false 请求实盘而未获实盘授权）→ 结构化错误抛出
 	*   （TRADING_LIVE_TRADING_DISABLED，api TradingError 契约）；
 	* - 闸门 ② simulate（dryRun 缺省/true，或 config.dryRun 强制模拟）→ 本地模拟回执
 	*   （Order.dryRun=true，不触网；工具层另有带市价参照的富回执）；
-	* - 闸门 ③ live（dryRun=false 且 liveTrading=true）→ 真实签名下单（env=demo 加模拟盘头）。
+	* - 闸门 ③ live（dryRun=false 且实盘已获授权）→ 真实签名下单（env=demo 加模拟盘头）。
 	*
 	* **sz 单位纪律（调研 §4，实现期最重要的换算）**：
 	* - api `OrderRequest.quantity` 语义恒为 base 币数；
@@ -287,6 +325,10 @@ var OkxTradeService = class extends Service {
 	*   ctVal/lotSz/minSz 换算并本地校验（向下取整，省一次 51000 往返）。
 	*/
 	async placeOrder(req) {
+		if (req.marginMode !== void 0) {
+			if (req.marginMode !== "cross" && req.marginMode !== "isolated") throw new TradingServiceError("TRADING_NOT_IMPLEMENTED", `OKX place order: unknown marginMode ${JSON.stringify(req.marginMode)} — only 'cross' and 'isolated' are implemented`);
+			if (instrumentFormOf(req.symbol) !== "perp") throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `OKX place order: marginMode=${req.marginMode} is only valid for perpetual (${req.symbol}-SWAP shaped) symbols; spot orders must stay cash (spot margin trading is not implemented)`);
+		}
 		const verdict = evaluateOrderGate(this.config, {
 			instId: req.symbol,
 			side: req.side,
@@ -313,9 +355,10 @@ var OkxTradeService = class extends Service {
 		const instId = normalizeOkxSymbol(req.symbol);
 		const instrument = await this.getInstrument(instId);
 		const normalized = normalizeSize(instId, instrument, req.quantity);
+		const marginMode = req.marginMode ?? "cross";
 		const params = {
 			instId,
-			tdMode: instrument.instType === "SWAP" ? "cross" : "cash",
+			tdMode: instrument.instType === "SWAP" ? marginMode : "cash",
 			side: req.side,
 			ordType: req.type,
 			sz: normalized.sz,
@@ -339,6 +382,62 @@ var OkxTradeService = class extends Service {
 		};
 	}
 	/**
+	* 设置合约杠杆与保证金模式（P7；api TradeService.setLeverage）。
+	*
+	* 与 placeOrder 共用同一套三态闸门（服务缝第一步——绕过工具层的直调同样 fail-closed）：
+	* - ① dryRun=false 而未获实盘授权 → TRADING_LIVE_TRADING_DISABLED；
+	* - ② dryRun 缺省/true（或被 config.dryRun 强制）→ 本地模拟回执，不触网；
+	* - ③ dryRun=false 且已获授权 → 真实签名 POST /api/v5/account/set-leverage
+	*   （env=demo 带 x-simulated-trading:1）。
+	*
+	* 本地判据（先于上游往返，给出可读原因、不静默改写调用方意图）：
+	* - 仅永续（form=perp）：现货传 setLeverage 报 TRADING_UNSUPPORTED_SYMBOL；
+	* - leverage > 交易所规格 lever（InstrumentContract.maxLeverage）→ 结构化拒绝，
+	*   **不做上限截断**（静默改小杠杆会让调用方以为自己设定的数字已生效）；
+	* - mgnMode 只认 cross/isolated；isolated + 双向持仓模式的 posSide 由调用方传，
+	*   本仓不猜账户持仓模式（缺席即原样透传，交交易所裁定）。
+	*/
+	async setLeverage(req) {
+		const marginMode = req.marginMode;
+		if (marginMode !== "cross" && marginMode !== "isolated") throw new TradingServiceError("TRADING_NOT_IMPLEMENTED", `OKX set leverage: unknown marginMode ${JSON.stringify(marginMode)} — only 'cross' and 'isolated' are implemented`);
+		if (!Number.isFinite(req.leverage) || req.leverage <= 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX set leverage: leverage ${String(req.leverage)} must be a positive number`);
+		if (instrumentFormOf(req.symbol) !== "perp") throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `OKX set leverage: ${req.symbol} is not a perpetual — leverage/margin mode only applies to -SWAP symbols`);
+		const requestedDryRun = req.dryRun ?? true;
+		if (!requestedDryRun && !liveTradingEnabled(this.config.liveTrading)) throw new TradingServiceError("TRADING_LIVE_TRADING_DISABLED", `crypto_set_leverage rejected: the call requests real execution (dryRun=${String(req.dryRun)}) but live trading is disabled (no signed live-trading grant from the authority plane). Ask the operator to sign a live-trading grant after confirmation, or keep dryRun=true for a simulated receipt.`);
+		const canonical = toCanonicalOkxSymbol(normalizeOkxSymbol(req.symbol));
+		const optional = {
+			...req.posSide !== void 0 ? { posSide: req.posSide } : {},
+			...req.ccy !== void 0 ? { ccy: req.ccy } : {}
+		};
+		if (requestedDryRun || this.config.dryRun) return {
+			symbol: canonical,
+			leverage: req.leverage,
+			marginMode,
+			...optional,
+			dryRun: true,
+			timestamp: Date.now()
+		};
+		const instId = normalizeOkxSymbol(req.symbol);
+		const max = (await this.getInstrument(instId)).maxLeverage;
+		if (max !== void 0 && Number.isFinite(max) && req.leverage > max) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX set leverage for ${instId}: requested ${req.leverage}x exceeds the exchange maximum lever ${max}x — refusing (no silent clamp)`);
+		const params = {
+			instId,
+			lever: String(req.leverage),
+			mgnMode: marginMode,
+			...optional
+		};
+		const credentials = await this.getCredentials();
+		await this.client.setLeverage(params, this.auth(credentials));
+		return {
+			symbol: canonical,
+			leverage: req.leverage,
+			marginMode,
+			...optional,
+			dryRun: false,
+			timestamp: Date.now()
+		};
+	}
+	/**
 	* 撤单。OKX 按 instId + ordId 双键定位，symbol（instId）必填——api 契约的
 	* cancelOrder(id) 单参形态对 OKX 不够，扩展第二可选参数（api 包 R3 修订）。
 	*
@@ -346,7 +445,7 @@ var OkxTradeService = class extends Service {
 	* 不存在）视作终态成功——撤单语义是「确保不再成交」，订单已终态即达成。
 	*/
 	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 (!liveTradingEnabled(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 a signed live-trading grant (see @dshtrading/authority) with dryRun=false (leave the live-trading authority ungranted 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();
@@ -390,7 +489,12 @@ var OkxTradeService = class extends Service {
 			timestamp: Number.isFinite(timestamp) ? timestamp : Date.now()
 		};
 	}
-	/** 只读持仓（SWAP 的 pos 单位是张 → 经 ctVal 换算成币；net 模式负 pos = short）。 */
+	/**
+	* 只读持仓（SWAP 的 pos 单位是张 → 经 ctVal 换算成币；net 模式负 pos = short）。
+	* 合约仓位附带交易所回传的强平价（liqPx）、维持保证金率（mgnRatio）、保证金模式
+	* （mgnMode）与名义价值（notionalUsd）——风控清单的「强平距离」判据读这些字段，
+	* 每条都是交易所口径，缺席即不展示（不本地补算）。
+	*/
 	async getPositions() {
 		const credentials = await this.getCredentials();
 		const rows = await this.client.getPositions(this.auth(credentials));
@@ -402,7 +506,7 @@ var OkxTradeService = class extends Service {
 			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")) {
+			if (instrumentFormOf(instId) === "perp") {
 				const instrument = instruments.get(instId);
 				if (instrument?.ctVal !== void 0) size = size * instrument.ctVal;
 			}
@@ -412,6 +516,10 @@ var OkxTradeService = class extends Service {
 			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 liquidationPrice = pickNumber(d.liqPx);
+			const marginRatio = pickNumber(d.mgnRatio);
+			const marginMode = d.mgnMode === "isolated" ? "isolated" : d.mgnMode === "cross" ? "cross" : void 0;
+			const notionalUsd = pickNumber(d.notionalUsd);
 			const timestamp = typeof d.uTime === "string" ? Number(d.uTime) : Date.now();
 			positions.push({
 				symbol: toCanonicalOkxSymbol(instId),
@@ -421,6 +529,10 @@ var OkxTradeService = class extends Service {
 				...markPrice !== void 0 && Number.isFinite(markPrice) ? { markPrice } : {},
 				...unrealizedPnl !== void 0 && Number.isFinite(unrealizedPnl) ? { unrealizedPnl } : {},
 				...leverage !== void 0 && Number.isFinite(leverage) ? { leverage } : {},
+				...liquidationPrice !== void 0 ? { liquidationPrice } : {},
+				...marginRatio !== void 0 ? { marginRatio } : {},
+				...marginMode !== void 0 ? { marginMode } : {},
+				...notionalUsd !== void 0 ? { notionalUsd } : {},
 				timestamp: Number.isFinite(timestamp) ? timestamp : Date.now()
 			});
 		}
@@ -456,7 +568,7 @@ var OkxTradeService = class extends Service {
 	async toCoins(instId, exchangeAmount, instruments) {
 		const n = typeof exchangeAmount === "string" || typeof exchangeAmount === "number" ? Number(exchangeAmount) : NaN;
 		if (!Number.isFinite(n)) return void 0;
-		if (!instId.endsWith("-SWAP")) return n;
+		if (instrumentFormOf(instId) !== "perp") return n;
 		if (instruments !== void 0) {
 			const instrument = instruments.get(instId);
 			return instrument?.ctVal !== void 0 ? n * instrument.ctVal : n;
@@ -551,10 +663,10 @@ function mapOrderState(state) {
 }
 function evaluateOrderGate(config, args) {
 	const requestedDryRun = args.dryRun ?? true;
-	if (!requestedDryRun && !config.liveTrading) return {
+	if (!requestedDryRun && !liveTradingEnabled(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.`
+		message: `crypto_place_order rejected: the call requests real execution (dryRun=${String(args.dryRun)}) but live trading is disabled (no signed live-trading grant from the authority plane). Ask the operator to sign a live-trading grant (packages/authority/bin/sign-live-trading.mjs) after confirmation, or keep dryRun=true for a simulated fill.`
 	};
 	if (requestedDryRun || config.dryRun) return { action: "simulate" };
 	return {
@@ -610,6 +722,7 @@ async function buildDryRunReceipt(args, marketData) {
 		quantity: args.quantity,
 		quantityUnit: "base-asset coins (SWAP orders would be converted to contracts by ctVal)",
 		...args.type === "limit" ? { price: args.price } : {},
+		...args.marginMode !== void 0 ? { marginMode: args.marginMode } : {},
 		reference,
 		timestamp: Date.now()
 	});
@@ -624,7 +737,7 @@ async function buildDryRunReceipt(args, marketData) {
 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.",
+		description: "Place an OKX spot or perpetual-swap order, or simulate one. instId accepts market-canonical (BTCUSDT, BTCUSDT-SWAP) or OKX native (BTC-USDT). quantity is in BASE-ASSET coins: spot MARKET orders are sent with tgtCcy=base_ccy (the OKX buy default is a quote-currency amount — a known trap) and SWAP quantities convert via ctVal. Perpetual orders default to cross margin; pass marginMode=isolated only after crypto_set_leverage has set the per-instrument isolated leverage. dryRun defaults to true and returns a DRY-RUN receipt; dryRun=false needs a signed live-trading grant plus approval. env=live is real money.",
 		parameters: {
 			instId: {
 				type: "string",
@@ -652,9 +765,14 @@ function createPlaceOrderTool(deps) {
 				type: "number",
 				description: "Limit price; required when type=limit"
 			},
+			marginMode: {
+				type: "string",
+				enum: ["cross", "isolated"],
+				description: "Perpetual margin mode (default cross). Isolated requires crypto_set_leverage for the instrument first; spot orders reject this field."
+			},
 			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)",
+				description: "true (default) = simulate only and return a DRY-RUN receipt; false = request real execution (gated by the signed live-trading authority, env and user approval)",
 				default: true
 			}
 		},
@@ -681,12 +799,103 @@ function createPlaceOrderTool(deps) {
 				type: args.type,
 				quantity: args.quantity,
 				...args.type === "limit" ? { price: args.price } : {},
+				...args.marginMode !== void 0 ? { marginMode: args.marginMode } : {},
 				dryRun: false
 			});
 			return JSON.stringify(order);
 		}
 	});
 }
+/** 参数校验（模型调用问题抛普通 Error，与 createPlaceOrderTool 先例一致）。 */
+function validateSetLeverageArgs(args) {
+	try {
+		normalizeOkxSymbol(args.instId);
+	} catch {
+		throw new Error(`crypto_set_leverage: invalid instId ${JSON.stringify(args.instId)} — expected a perpetual id (BTCUSDT-SWAP canonical or BTC-USDT-SWAP native)`);
+	}
+	if (instrumentFormOf(args.instId) !== "perp") throw new Error(`crypto_set_leverage: ${args.instId} is not a perpetual — leverage/margin mode only applies to -SWAP symbols`);
+	if (typeof args.leverage !== "number" || !Number.isFinite(args.leverage) || args.leverage <= 0) throw new Error(`crypto_set_leverage: invalid leverage ${JSON.stringify(args.leverage)} — expected a positive multiplier`);
+	if (args.marginMode !== void 0 && args.marginMode !== "cross" && args.marginMode !== "isolated") throw new Error(`crypto_set_leverage: invalid marginMode ${JSON.stringify(args.marginMode)} — expected cross or isolated`);
+	if (args.posSide !== void 0 && args.posSide !== "long" && args.posSide !== "short") throw new Error(`crypto_set_leverage: invalid posSide ${JSON.stringify(args.posSide)} — expected long or short`);
+}
+/**
+* crypto_set_leverage 工具工厂（独立导出便于单测闸门与参数矩阵）。
+*
+* 审批不在这里做：dryRun!==true 的调用由 @dshtrading/base 的统一审批闸门在
+* `tools/pre-execute` waterfall ask（headless 下 ask=deny，fail-closed）；
+* 工具内不再重复调 ctx.approval。
+*/
+function createSetLeverageTool(deps) {
+	return defineTool({
+		name: "crypto_set_leverage",
+		description: "Set the OKX perpetual leverage and margin mode for one instrument. This changes real account risk parameters, so it is gated exactly like an order: dryRun defaults to true and returns a DRY-RUN receipt without sending any request; dryRun=false needs a signed live-trading grant plus user approval (env=live is real money). The exchange maximum leverage is enforced on the real path; an out-of-range value is rejected, never silently clamped. Isolated margin also requires this call for the instrument before placing isolated orders.",
+		parameters: {
+			instId: {
+				type: "string",
+				required: true,
+				description: "Perpetual instrument id — market-canonical (BTCUSDT-SWAP) or OKX native (BTC-USDT-SWAP); spot symbols are rejected"
+			},
+			leverage: {
+				type: "number",
+				required: true,
+				description: "Target leverage multiplier (> 0). Must not exceed the exchange maximum (contract.maxLeverage); it is rejected, never clamped."
+			},
+			marginMode: {
+				type: "string",
+				enum: ["cross", "isolated"],
+				description: "Margin mode: cross (default, whole-account) or isolated (per-position; OKX also needs posSide in long/short position mode)",
+				default: "cross"
+			},
+			posSide: {
+				type: "string",
+				enum: ["long", "short"],
+				description: "Position direction — required by OKX in long/short position mode, omit in net mode"
+			},
+			ccy: {
+				type: "string",
+				description: "Margin currency for cross mode under multi-currency margin; omit otherwise"
+			},
+			dryRun: {
+				type: "boolean",
+				description: "true (default) = simulate only and return a DRY-RUN receipt; false = request real execution (gated by the signed live-trading authority, env and user approval)",
+				default: true
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const args = normalizeSetLeverageArgs(raw);
+			validateSetLeverageArgs(args);
+			const setLeverage = deps.trade.setLeverage;
+			if (typeof setLeverage !== "function") throw new TradingServiceError("TRADING_NOT_IMPLEMENTED", "crypto_set_leverage: the routed trade connector does not implement setLeverage");
+			const setting = await setLeverage.call(deps.trade, {
+				symbol: args.instId,
+				leverage: args.leverage,
+				marginMode: args.marginMode ?? "cross",
+				...args.posSide !== void 0 ? { posSide: args.posSide } : {},
+				...args.ccy !== void 0 ? { ccy: args.ccy } : {},
+				...args.dryRun !== void 0 ? { dryRun: args.dryRun } : {}
+			});
+			return JSON.stringify(setting.dryRun ? {
+				...setting,
+				note: "DRY-RUN — simulated leverage change; no request was sent to OKX. The exchange maximum leverage is validated only on a real (dryRun=false) request."
+			} : setting);
+		}
+	});
+}
+function normalizeSetLeverageArgs(raw) {
+	const args = raw ?? {};
+	const instId = typeof args.instId === "string" ? args.instId.trim().toUpperCase() : void 0;
+	return {
+		...args,
+		instId
+	};
+}
 /**
 * 互斥激活的注册面：dsh-tools 对同名重复注册直接抛错（会炸 boot/preset 挂载），
 * 而互斥纪律下「同时至多一个连接器激活」只是配置约定。这里把冲突降级为
@@ -817,6 +1026,7 @@ function apply(ctx, config) {
 			trade,
 			config
 		}), log);
+		registerTool(ctx, createSetLeverageTool({ trade }), 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.",
@@ -898,7 +1108,7 @@ function apply(ctx, config) {
 		}), 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.",
+			description: "Read the OKX account positions: size is converted from contracts to coins for swaps, with entry/mark price, unrealized PnL and leverage. Perpetual positions also carry the exchange-reported liquidation price, maintenance margin ratio, margin mode (cross/isolated) and USD notional when OKX returns them — these drive the pre-trade risk checklist; absent means the exchange did not report it, never a locally computed value. Read-only.",
 			parameters: {},
 			output: {
 				schema: { type: "string" },
@@ -919,4 +1129,4 @@ function apply(ctx, config) {
 	});
 }
 //#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 };
+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, coinsToContracts, contractsToCoins, createPlaceOrderTool, createSetLeverageTool, credentialRefsFor, evaluateOrderGate, inject, isoTimestamp, mapOrderState, name, normalizeOkxSymbol, normalizeSize, okxAssetClassOf, okxContractOf, resolveCredentials, signPayload, signaturePrehash, toBar, toCanonicalOkxSymbol, toOkxSwapInstId };

package/lib/rest.d.ts

@@ -1,4 +1,4 @@
-import { DerivativesPoint, Interval, Kline, Orderbook, Ticker, TradeTick, TradingErrorCode } from "@dshtrading/api";
+import { DerivativesPoint, InstrumentAssetClass, InstrumentContract, InstrumentRef, Interval, Kline, Orderbook, Ticker, TradeTick, TradingErrorCode } from "@dshtrading/api";
 //#region src/rest.d.ts
 /** api 包 TradingError 契约的运行时 Error 实现（connector-binance 同款）。 */
 declare class TradingServiceError extends Error {
@@ -96,11 +96,18 @@ interface OkxInstrument {
   readonly settleCcy?: string;
   readonly baseCcy?: string;
   readonly quoteCcy?: string;
+  /** 最大杠杆（lever）。 */
+  readonly maxLeverage?: number;
+  /**
+   * 交易所分类标签（instCategory：1=加密、3=股票/ETF、4=大宗）。
+   * **无公开文档**（调研受限），语义靠真实网络实测反推；未登记即留空。
+   */
+  readonly instCategory?: number;
 }
-/** POST /api/v5/trade/order 请求体词汇（R3 只做 market/limit；tdMode 现货=cash、永续=cross）。 */
+/** POST /api/v5/trade/order 请求体词汇（R3 只做 market/limit；tdMode 现货=cash、永续=cross/isolated）。 */
 interface OkxPlaceOrderParams {
   readonly instId: string;
-  readonly tdMode: 'cash' | 'cross';
+  readonly tdMode: 'cash' | 'cross' | 'isolated';
   readonly side: 'buy' | 'sell';
   readonly ordType: 'market' | 'limit';
   /** 字符串数量：SPOT=base 币数（market 单显式 tgtCcy=base_ccy）；SWAP=张（=coins/ctVal）。 */
@@ -108,6 +115,18 @@ interface OkxPlaceOrderParams {
   readonly px?: string;
   readonly tgtCcy?: 'base_ccy' | 'quote_ccy';
 }
+/**
+ * POST /api/v5/account/set-leverage 请求体词汇（P7；仅 SWAP 走本仓接线）。
+ * `mgnMode` 与下单 `tdMode` 同词汇；逐仓/双向持仓模式下 `posSide` 必填（交易所裁定，
+ * 本仓不猜账户持仓模式：缺席即按原样透传，由交易所报错，不本地补位）。
+ */
+interface OkxSetLeverageParams {
+  readonly instId: string;
+  readonly lever: string;
+  readonly mgnMode: 'cross' | 'isolated';
+  readonly posSide?: 'long' | 'short';
+  readonly ccy?: string;
+}
 /** 客户端侧 sz 纪律校验结果：换算后的交易所数量字符串 + 提示（index.ts 组装请求体）。 */
 interface NormalizedSize {
   /** 发给交易所的 sz 字符串（SPOT=币数；SWAP=张）。 */
@@ -115,8 +134,24 @@ interface NormalizedSize {
   /** 现货市价单显式 tgtCcy=base_ccy（消除「buy 缺省按计价币金额」的坑，调研 §4）。 */
   readonly tgtCcy?: 'base_ccy';
 }
+/**
+ * 张 ↔ 币换算（P7 的唯一换算实现，向量判据在 test/contract-trading.test.ts）：
+ * 合约数量（张）= 币数 / ctVal，再按 lotSz 步进**向下**取整。
+ *
+ * 向下取整是安全方向：宁可少开，绝不因浮点误差把敞口放大一档。实现用
+ * **相对**容差吸收 `0.9999999999` 这类表示误差，并用一次硬性比较兜底
+ * （步进结果超过请求张数就退一档）——旧实现的 `Math.floor(x + 1e-9)`
+ * 在商刚好略小于整数时会向上跳一档，与「绝不上取」的注释不符。
+ */
+declare function coinsToContracts(instId: string, instrument: OkxInstrument, quantityCoins: number): number;
+/** 张 → 币（基币数量 = 张数 × ctVal；ctVal 缺席即拒绝，不虚构换算）。 */
+declare function contractsToCoins(instId: string, instrument: OkxInstrument, contracts: number): number;
 /** 把 api 语义的 base 币数量换算成 OKX sz（本地精度校验：minSz/lotSz，省一次 51000 往返）。 */
 declare function normalizeSize(instId: string, instrument: OkxInstrument, quantityCoins: number): NormalizedSize;
+/** instCategory（OKX 回字符串数字，实测；容忍 number 输入）→ 资产类别；未登记 = undefined。 */
+declare function okxAssetClassOf(instCategory: unknown): InstrumentAssetClass | undefined;
+/** SWAP 规格 → InstrumentContract（ctVal/tickSz/lotSz/lever/settleCcy 原样透传，不本地推断）。 */
+declare function okxContractOf(inst: OkxInstrument): InstrumentContract | undefined;
 declare class OkxRestClient {
   #private;
   private readonly baseUrl;
@@ -196,19 +231,28 @@ declare class OkxRestClient {
   /** 合约/币对规格：GET /api/v5/public/instruments（sz 纪律的 ctVal/lotSz/minSz 来源）。 */
   getInstruments(instType: 'SPOT' | 'SWAP', instId?: string): Promise<OkxInstrument[]>;
   /**
-   * 全部可交易现货标的名册（GET /api/v5/public/instruments?instType=SPOT，Issue #15）。
-   * 输出 symbol 归一化为市场规范形（BTC-USDT → BTCUSDT），name 为 baseCcy/quoteCcy。
+   * 全部可交易标的名册 = 现货 ∪ 永续（GET /api/v5/public/instruments，Issue #15 扩展；
+   * 2026-10-08 形态维度落地）。
+   *
+   * - 现货：instType=SPOT → `BTCUSDT`（form=spot），name 取 baseCcy/quoteCcy。
+   * - 永续：instType=SWAP → `BTCUSDT-SWAP`（form=perp，与现货成对），name 取
+   *   ctValCcy 与 instId 的计价段（SWAP 行的 baseCcy/quoteCcy 为空串，实测）；
+   *   assetClass 只由 instCategory 映射，contract 透传 ctVal/tickSz/lotSz/lever/settleCcy。
+   *
+   * 两半都拉取（Promise.all）；任一半失败即抛结构化错误，不返回半份名册。
    */
-  listInstruments(): Promise<Array<{
-    symbol: string;
-    name?: string;
-  }>>;
+  listInstruments(): Promise<InstrumentRef[]>;
   /** 只读余额：GET /api/v5/account/balance（ccy 可选，逗号分隔 ≤20）。 */
   getBalance(auth: SignedAuth, ccy?: string): Promise<unknown[]>;
   /** 只读持仓：GET /api/v5/account/positions（instId 可选过滤）。 */
   getPositions(auth: SignedAuth, instId?: string): Promise<unknown[]>;
   /** 下单：POST /api/v5/trade/order（60 次/2s）。 */
   placeOrder(params: OkxPlaceOrderParams, auth: SignedAuth): Promise<unknown[]>;
+  /**
+   * 设置杠杆/保证金模式：POST /api/v5/account/set-leverage（P7；实盘动作，与下单同门槛）。
+   * 只发请求不判定闸门——三态闸门由 OkxTradeService.setLeverage 在调用本方法前执行。
+   */
+  setLeverage(params: OkxSetLeverageParams, auth: SignedAuth): Promise<unknown[]>;
   /** 撤单：POST /api/v5/trade/cancel-order（ordId 优先于 clOrdId，本切片只支持 ordId）。 */
   cancelOrder(instId: string, ordId: string, auth: SignedAuth): Promise<unknown[]>;
   /** 查单：GET /api/v5/trade/order（query 属于签名 requestPath）。 */
@@ -235,4 +279,4 @@ declare function toCanonicalOkxSymbol(symbol: string): string;
  */
 declare function toOkxSwapInstId(input: string): string;
 //#endregion
-export { BAR_MAP, NormalizedSize, OKX_INTERVAL_VOCABULARY, OkxCredentials, OkxFundingRate, OkxInstrument, OkxOpenInterest, OkxPlaceOrderParams, OkxRestClient, OkxRestOptions, SignedAuth, TradingServiceError, barDurationMs, buildAuthHeaders, isoTimestamp, normalizeOkxSymbol, normalizeSize, signPayload, signaturePrehash, toBar, toCanonicalOkxSymbol, toOkxSwapInstId };
+export { BAR_MAP, NormalizedSize, OKX_INTERVAL_VOCABULARY, OkxCredentials, OkxFundingRate, OkxInstrument, OkxOpenInterest, OkxPlaceOrderParams, OkxRestClient, OkxRestOptions, OkxSetLeverageParams, SignedAuth, TradingServiceError, barDurationMs, buildAuthHeaders, coinsToContracts, contractsToCoins, isoTimestamp, normalizeOkxSymbol, normalizeSize, okxAssetClassOf, okxContractOf, signPayload, signaturePrehash, toBar, toCanonicalOkxSymbol, toOkxSwapInstId };

package/lib/rest.js

@@ -1,3 +1,4 @@
+import { instrumentFormOf } from "@dshtrading/api";
 import { createHmac } from "node:crypto";
 //#region src/rest.ts
 /**
@@ -166,18 +167,51 @@ async function envelopeToError(res, path, parsedBody) {
 	].filter((part) => part !== void 0 && part !== "").join(" ");
 	return new TradingServiceError(tradingCode, `OKX ${path}: ${detail}`, body);
 }
+/**
+* 张 ↔ 币换算（P7 的唯一换算实现，向量判据在 test/contract-trading.test.ts）：
+* 合约数量（张）= 币数 / ctVal，再按 lotSz 步进**向下**取整。
+*
+* 向下取整是安全方向：宁可少开，绝不因浮点误差把敞口放大一档。实现用
+* **相对**容差吸收 `0.9999999999` 这类表示误差，并用一次硬性比较兜底
+* （步进结果超过请求张数就退一档）——旧实现的 `Math.floor(x + 1e-9)`
+* 在商刚好略小于整数时会向上跳一档，与「绝不上取」的注释不符。
+*/
+function coinsToContracts(instId, instrument, quantityCoins) {
+	const ctVal = instrument.ctVal;
+	if (ctVal === void 0 || !Number.isFinite(ctVal) || ctVal <= 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX ${instId}: swap instrument has no usable ctVal (${String(ctVal)}) — refusing to guess a contract multiplier`);
+	const rawContracts = quantityCoins / ctVal;
+	if (!Number.isFinite(rawContracts) || rawContracts <= 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX ${instId}: quantity ${quantityCoins} coins does not convert to a positive contract amount (ctVal=${ctVal})`);
+	if (rawContracts < instrument.minSz) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX ${instId}: quantity ${quantityCoins} coins = ${rawContracts} contracts is below minSz ${instrument.minSz}`);
+	return stepDown(instId, rawContracts, instrument.lotSz, `coins=${quantityCoins}`);
+}
+/** 张 → 币（基币数量 = 张数 × ctVal；ctVal 缺席即拒绝，不虚构换算）。 */
+function contractsToCoins(instId, instrument, contracts) {
+	const ctVal = instrument.ctVal;
+	if (ctVal === void 0 || !Number.isFinite(ctVal) || ctVal <= 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX ${instId}: swap instrument has no usable ctVal (${String(ctVal)})`);
+	return contracts * ctVal;
+}
+/**
+* 按步进向下取整（安全方向：结果恒不超过 `amount`）。
+* 容差是相对的（`Number.EPSILON` 量级），只吸收浮点表示误差；随后用一次
+* 硬比较兜底，保证任何输入都不会被向上放大一档。
+*/
+function stepDown(instId, amount, step, label) {
+	if (!Number.isFinite(step) || step <= 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX ${instId}: instrument has no usable lot step (${String(step)})`);
+	if (amount < step) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX ${instId}: ${label} is below the minimum lot step ${step}`);
+	const rawSteps = amount / step;
+	const tolerance = Math.max(Number.EPSILON * 8 * Math.abs(rawSteps), 1e-12);
+	let steps = Math.floor(rawSteps + tolerance);
+	if (steps * step > amount * (1 + 1e-12)) steps -= 1;
+	if (steps <= 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX ${instId}: ${label} rounds down to 0 at lotSz ${step}`);
+	return steps * step;
+}
 /** 把 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,
+	if (instrument.instType === "SWAP") return { sz: trimNumber(coinsToContracts(instId, instrument, quantityCoins)) };
+	if (!Number.isFinite(quantityCoins) || quantityCoins <= 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX ${instId}: quantity ${quantityCoins} is not a positive base-asset amount`);
+	if (quantityCoins < instrument.minSz) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `OKX ${instId}: quantity ${quantityCoins} coins is below minSz ${instrument.minSz}`);
+	return {
+		sz: trimNumber(stepDown(instId, quantityCoins, instrument.lotSz, `quantity=${quantityCoins} coins`)),
 		tgtCcy: "base_ccy"
 	};
 }
@@ -186,6 +220,37 @@ function trimNumber(n) {
 	const fixed = n.toFixed(12).replace(/0+$/, "").replace(/\.$/, "");
 	return fixed === "" ? "0" : fixed;
 }
+/**
+* OKX instCategory → 资产类别。
+*
+* **无公开文档**（调研受限），语义靠 2026-10-08 真实网络实测反推：SWAP 共 500 个
+* （全部 state=live）中 1=加密 301、3=股票/ETF 190、4=大宗 9；SPOT 1144 个中同样
+* 出现 3（127）/4（4）类。只登记实测到的取值；**未登记/缺失一律 undefined（留空），
+* 禁止按符号猜**——反例硬证据：`SPX-USDT-SWAP` 的 instCategory=1（那是迷因币
+* SPX6900），标普 500 是 `US500-USDT-SWAP`（instCategory=3）。
+* 原始响应与计数见 spikes/impl-crypto-perp-tradfi/EVIDENCE.md。
+*/
+const OKX_INST_CATEGORY_ASSET_CLASS = {
+	"1": "crypto",
+	"3": "equity",
+	"4": "commodity"
+};
+/** instCategory（OKX 回字符串数字，实测；容忍 number 输入）→ 资产类别；未登记 = undefined。 */
+function okxAssetClassOf(instCategory) {
+	if (typeof instCategory !== "string" && typeof instCategory !== "number") return void 0;
+	return OKX_INST_CATEGORY_ASSET_CLASS[String(instCategory).trim()];
+}
+/** SWAP 规格 → InstrumentContract（ctVal/tickSz/lotSz/lever/settleCcy 原样透传，不本地推断）。 */
+function okxContractOf(inst) {
+	if (inst.instType !== "SWAP") return void 0;
+	return {
+		tickSize: inst.tickSz,
+		lotSize: inst.lotSz,
+		...inst.ctVal !== void 0 ? { multiplier: inst.ctVal } : {},
+		...inst.maxLeverage !== void 0 ? { maxLeverage: inst.maxLeverage } : {},
+		...inst.settleCcy !== void 0 ? { settleCcy: inst.settleCcy } : {}
+	};
+}
 var OkxRestClient = class {
 	baseUrl;
 	timeoutMs;
@@ -279,7 +344,7 @@ var OkxRestClient = class {
 		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 volume = instrumentFormOf(id) === "perp" ? 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 {
@@ -343,7 +408,7 @@ var OkxRestClient = class {
 	/** 资金费率：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}`);
+		if (instrumentFormOf(id) !== "perp") 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);
@@ -491,7 +556,7 @@ var OkxRestClient = class {
 	}
 	/** 未平仓合约量：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}`);
+		if (instrumentFormOf(id) !== "perp") 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
@@ -560,6 +625,8 @@ var OkxRestClient = class {
 			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);
+			const maxLeverage = num(d.lever);
+			const instCategory = num(d.instCategory);
 			return {
 				instId: id,
 				instType: str(d.instType) ?? instType,
@@ -570,23 +637,42 @@ var OkxRestClient = class {
 				...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) } : {}
+				...str(d.quoteCcy) !== void 0 ? { quoteCcy: str(d.quoteCcy) } : {},
+				...maxLeverage !== void 0 ? { maxLeverage } : {},
+				...instCategory !== void 0 ? { instCategory } : {}
 			};
 		});
 	}
 	/**
-	* 全部可交易现货标的名册（GET /api/v5/public/instruments?instType=SPOT，Issue #15）。
-	* 输出 symbol 归一化为市场规范形（BTC-USDT → BTCUSDT），name 为 baseCcy/quoteCcy。
+	* 全部可交易标的名册 = 现货 ∪ 永续（GET /api/v5/public/instruments，Issue #15 扩展；
+	* 2026-10-08 形态维度落地）。
+	*
+	* - 现货：instType=SPOT → `BTCUSDT`（form=spot），name 取 baseCcy/quoteCcy。
+	* - 永续：instType=SWAP → `BTCUSDT-SWAP`（form=perp，与现货成对），name 取
+	*   ctValCcy 与 instId 的计价段（SWAP 行的 baseCcy/quoteCcy 为空串，实测）；
+	*   assetClass 只由 instCategory 映射，contract 透传 ctVal/tickSz/lotSz/lever/settleCcy。
+	*
+	* 两半都拉取（Promise.all）；任一半失败即抛结构化错误，不返回半份名册。
 	*/
 	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 } : {}
-			};
-		});
+		const [spot, swap] = await Promise.all([this.getInstruments("SPOT"), this.getInstruments("SWAP")]);
+		return [...spot.map((inst) => this.#toInstrumentRef(inst, "spot")), ...swap.map((inst) => this.#toInstrumentRef(inst, "perp"))];
+	}
+	/** 名册条目 → InstrumentRef：形态由来源端点裁决，类别只信 instCategory（取不到留空）。 */
+	#toInstrumentRef(inst, form) {
+		const parts = inst.instId.split("-");
+		const base = inst.baseCcy ?? inst.ctValCcy ?? parts[0];
+		const quote = inst.quoteCcy ?? parts[1];
+		const name = base !== void 0 && base !== "" && quote !== void 0 && quote !== "" ? `${base}/${quote}` : void 0;
+		const assetClass = okxAssetClassOf(inst.instCategory);
+		const contract = form === "perp" ? okxContractOf(inst) : void 0;
+		return {
+			symbol: toCanonicalOkxSymbol(inst.instId),
+			...name !== void 0 ? { name } : {},
+			form,
+			...assetClass !== void 0 ? { assetClass } : {},
+			...contract !== void 0 ? { contract } : {}
+		};
 	}
 	/** 只读余额：GET /api/v5/account/balance（ccy 可选，逗号分隔 ≤20）。 */
 	async getBalance(auth, ccy) {
@@ -610,6 +696,17 @@ var OkxRestClient = class {
 			auth
 		});
 	}
+	/**
+	* 设置杠杆/保证金模式：POST /api/v5/account/set-leverage（P7；实盘动作，与下单同门槛）。
+	* 只发请求不判定闸门——三态闸门由 OkxTradeService.setLeverage 在调用本方法前执行。
+	*/
+	async setLeverage(params, auth) {
+		return this.request("/api/v5/account/set-leverage", {
+			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", {
@@ -710,7 +807,7 @@ function toCanonicalOkxSymbol(symbol) {
 */
 function toOkxSwapInstId(input) {
 	const id = normalizeOkxSymbol(input);
-	return id.endsWith("-SWAP") ? id : `${id}-SWAP`;
+	return instrumentFormOf(id) === "perp" ? id : `${id}-SWAP`;
 }
 //#endregion
-export { BAR_MAP, OKX_INTERVAL_VOCABULARY, OkxRestClient, TradingServiceError, barDurationMs, buildAuthHeaders, isoTimestamp, normalizeOkxSymbol, normalizeSize, signPayload, signaturePrehash, toBar, toCanonicalOkxSymbol, toOkxSwapInstId };
+export { BAR_MAP, OKX_INTERVAL_VOCABULARY, OkxRestClient, TradingServiceError, barDurationMs, buildAuthHeaders, coinsToContracts, contractsToCoins, isoTimestamp, normalizeOkxSymbol, normalizeSize, okxAssetClassOf, okxContractOf, signPayload, signaturePrehash, toBar, toCanonicalOkxSymbol, toOkxSwapInstId };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dshtrading/connector-okx",
   "description": "OKX market connector plugin for dsh-trading: public market data + signed demo/live trading (R1-R3), mutual-exclusion activation with connector-binance",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -21,8 +21,9 @@
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
   "dependencies": {
-    "@dshtrading/api": "^0.5.0",
-    "@dshtrading/indicators": "^0.5.0"
+    "@dshtrading/authority": "^0.6.1",
+    "@dshtrading/indicators": "^0.6.1",
+    "@dshtrading/api": "^0.6.1"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.0",
@@ -32,7 +33,7 @@
   "devDependencies": {
     "tsdown": "^0.22.0",
     "vitest": "^3.0.0",
-    "@dshtrading/connector-binance": "^0.5.0"
+    "@dshtrading/connector-binance": "^0.6.1"
   },
   "scripts": {
     "build": "tsdown",