@dshtrading/connector-okx 0.1.0

package/LICENSE

@@ -0,0 +1,75 @@
+Copyright (c) 2026 zhu1090093659 (dsh-trading)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/lib/dataplane.d.ts

@@ -0,0 +1,7 @@
+import { Config } from "./index.js";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/dataplane.d.ts
+declare const inject: string[];
+declare function apply(ctx: Context, config: Config): void;
+//#endregion
+export { apply, inject };

package/lib/dataplane.js

@@ -0,0 +1,41 @@
+import { OkxRestClient } from "./rest.js";
+import { OkxMarketDataService, OkxTradeService, TRADING_CRYPTO_MARKET_DATA_KEY, TRADING_CRYPTO_TRADE_KEY, resolveCredentials } from "./index.js";
+//#region src/dataplane.ts
+const inject = [];
+/** 解析注册表服务；老部署（base/router 未升级）返回 undefined → 调用方回退旧的直接 provide 路径。 */
+function resolveMarketDataRegistry(ctx) {
+	const candidate = ctx.get?.("tradingMarketDataRegistry", false);
+	return candidate !== void 0 ? candidate : void 0;
+}
+/** 解析交易注册表服务（issue #40）；老部署（未升级）返回 undefined → 跳过交易注册。 */
+function resolveTradeRegistry(ctx) {
+	const candidate = ctx.get?.("tradingTradeRegistry", false);
+	return candidate !== void 0 ? candidate : void 0;
+}
+function apply(ctx, config) {
+	if (!config.enabled) return;
+	const registry = resolveMarketDataRegistry(ctx);
+	if (registry === void 0) {
+		const router = ctx.get?.("tradingMarketRouter", false);
+		const active = router?.activeProvider("crypto");
+		if (router !== void 0 && active !== "okx") return;
+		new OkxMarketDataService(ctx);
+		return;
+	}
+	const client = new OkxRestClient();
+	const inner = ctx.isolate(TRADING_CRYPTO_MARKET_DATA_KEY);
+	const service = new OkxMarketDataService(inner, {}, client);
+	ctx.effect(() => registry.register("crypto", "okx", service));
+	const tradeRegistry = resolveTradeRegistry(ctx);
+	if (tradeRegistry !== void 0) {
+		const tradeInner = ctx.isolate(TRADING_CRYPTO_TRADE_KEY);
+		const trade = new OkxTradeService(tradeInner, {
+			client,
+			config,
+			getCredentials: () => resolveCredentials(ctx, config)
+		});
+		ctx.effect(() => tradeRegistry.register("crypto", "okx", trade));
+	}
+}
+//#endregion
+export { apply, inject };

package/lib/index.d.ts

@@ -0,0 +1,227 @@
+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 { 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";
+//#region src/index.d.ts
+/**
+ * Cordis 插件名 = preset 行 id（TEMPLATES §8）：`dsh-trading-crypto-*` 市场命名空间，
+ * 全仓唯一，绝不使用 `base` 等官方保留 id（insert-only 铁律 #1）。
+ */
+declare const name = "dsh-trading-crypto-connector-okx";
+interface Config {
+  /** 互斥激活总开关（默认 false）：false 时本插件不注册任何服务/工具。 */
+  enabled: boolean;
+  /** 三态环境：'demo'（默认，模拟盘 x-simulated-trading:1）| 'live'（实盘）。 */
+  env: 'demo' | 'live';
+  /** 交易安全闸门（铁律 #3）：true 时下单类工具强制 dry-run。 */
+  dryRun: boolean;
+  /** 实盘总闸门（默认 false）：false 时 dryRun=false 的请求被结构化拒绝。
+   *  true 的第一默认目标是 demo（env='demo'），改 env='live' 是第二次显式解锁。 */
+  liveTrading: boolean;
+  /** 实盘凭证 ref（环境变量名，credentialRef 语义）。 */
+  apiKeyRef: string;
+  secretRef: string;
+  passphraseRef: string;
+  /** 模拟盘凭证 ref 组（demo/live key 不通用，调研 §2——按环境取不同 ref 组）。 */
+  demoApiKeyRef: string;
+  demoSecretRef: string;
+  demoPassphraseRef: string;
+}
+declare const Config: Schema<Config>;
+/** 需要宿主提供的 Cordis 服务。 */
+declare const inject: string[];
+/** ctx 服务键（与 @dshtrading/api 的 Context 模块增强一致）。 */
+declare const TRADING_CRYPTO_MARKET_DATA_KEY = "tradingCryptoMarketData";
+declare const TRADING_CRYPTO_TRADE_KEY = "tradingCryptoTrade";
+/**
+ * DSH credentials seam 的结构化最小契约（resolve 每次 {value}|undefined）。
+ * 本仓不引 @deepseek-ai/dsh-credentials 依赖；形状以其 CredentialProvider 为准。
+ */
+interface CredentialResolverLike {
+  resolve(ref: string): Promise<{
+    value: string;
+  } | undefined>;
+}
+/** 凭证解析所需的最小 ctx 面（单测可直接给 { get } 假 ctx）。 */
+interface CredentialsContext {
+  get(name: string): unknown;
+}
+interface ResolvedCredentialRefs {
+  readonly apiKeyRef: string;
+  readonly secretRef: string;
+  readonly passphraseRef: string;
+}
+/** env → ref 组：demo 用 demo*Ref（默认 OKX_DEMO_*），live 用 live 组（默认 OKX_*）。 */
+declare function credentialRefsFor(config: Config, env?: 'demo' | 'live'): ResolvedCredentialRefs;
+/**
+ * 三 ref 凭证解析：每次操作调用（ctx.credentials 的设计意图——换 key 无需重启插件）。
+ * 无 credentials seam 时回落启动环境变量（llm-deepseek 同款降级）。
+ * 任何一处未命中/无效 → TRADING_CREDENTIALS_MISSING，消息只带 ref 名（绝不带值）。
+ */
+declare function resolveCredentials(ctx: CredentialsContext, config: Config): Promise<OkxCredentials>;
+interface SubscribeTickerOptions {
+  /** 轮询间隔（ms）。切片阶段 subscribeTicker 以 REST 轮询实现，WS 在后续任务。 */
+  readonly intervalMs?: number;
+}
+declare class OkxMarketDataService extends Service implements MarketDataService {
+  private readonly client;
+  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;
+  }>>;
+  /** OKX 专属扩展（MarketDataService 契约之外）：SWAP 资金费率。 */
+  getFundingRate(instId: string): Promise<OkxFundingRate>;
+  /** 盘口快照（api 可选契约 getOrderbook，issue #39）：books 20 档透传。 */
+  getOrderbook(symbol: string): Promise<Orderbook>;
+  /** 最近逐笔成交（api 可选契约 getRecentTrades，issue #39），时间升序。 */
+  getRecentTrades(symbol: string, limit?: number): Promise<TradeTick[]>;
+  /**
+   * 衍生品指标快照（api 可选契约 getDerivatives，issue #38）：聚合 OKX 公共端点
+   * （funding-rate / open-interest / rubik 多空账户比 / rubik taker 买卖量）。
+   * 现货输入经 toOkxSwapInstId 升到对应永续（GUI 选中 BTCUSDT 也能看合约指标）。
+   * 任一子查询失败只降级该字段（undefined，面板按缺格隐藏）；全部失败才抛
+   * 结构化错误（桥层转 ok:false，前端不弹横幅）。
+   */
+  getDerivatives(symbol: string): Promise<DerivativesData>;
+  /**
+   * 衍生品历史序列（api 可选契约 getDerivativesHistory，issue #54）：
+   * funding-rate-history + rubik open-interest-history 双端点聚合并发拉取，
+   * 任一失败只降级该序列（字段缺省 → 对应趋势卡隐藏），全部失败才抛结构化错误。
+   */
+  getDerivativesHistory(symbol: string): Promise<DerivativesHistory>;
+  subscribeTicker(instId: string, cb: (ticker: Ticker) => void, options?: SubscribeTickerOptions): Disposable;
+}
+interface OkxTradeServiceOptions {
+  readonly client: OkxRestClient;
+  readonly config: Config;
+  /** 每次操作取三值凭证（内部走 resolveCredentials，未命中抛结构化错误）。 */
+  readonly getCredentials: () => Promise<OkxCredentials>;
+}
+declare class OkxTradeService extends Service implements TradeService {
+  private readonly client;
+  private readonly config;
+  private readonly getCredentials;
+  /** instId → 规格 缓存；key 前缀 demo:/live: —— demo 与实盘 ctVal 是否一致未实证（调研待验证 #5），按环境分桶。 */
+  private readonly instruments;
+  constructor(ctx: Context, options: OkxTradeServiceOptions, serviceName?: string);
+  private get simulated();
+  private auth;
+  /** 规格（带 TTL 缓存；demo/live 分桶）。查不到 → TRADING_UNSUPPORTED_SYMBOL。 */
+  private getInstrument;
+  /**
+   * 下单（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 往返）。
+   */
+  placeOrder(req: OrderRequest): Promise<Order>;
+  /**
+   * 撤单。OKX 按 instId + ordId 双键定位，symbol（instId）必填——api 契约的
+   * cancelOrder(id) 单参形态对 OKX 不够，扩展第二可选参数（api 包 R3 修订）。
+   *
+   * 撤单幂等化（调研 §5「实现期定」）：51400（订单已成交/已撤/不存在）/51603（订单
+   * 不存在）视作终态成功——撤单语义是「确保不再成交」，订单已终态即达成。
+   */
+  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）。 */
+  getPositions(): Promise<Position[]>;
+  /** 只读余额（TradeService 契约外扩展，crypto_get_balance 工具消费）。 */
+  getBalances(): Promise<AccountBalance[]>;
+  /** SWAP 的 sz/accFillSz/fillSz（张）→ base 币数（规格缓存，非 SWAP 原值）。 */
+  private toCoins;
+  /** 当前挂单（TradeService 可选契约，issue #40；只读、需凭证）。 */
+  listOpenOrders(symbol?: string): Promise<Order[]>;
+  /** 最近成交流水（TradeService 可选契约，issue #40；只读、需凭证，时间升序）。 */
+  listTradeFills(symbol?: string, limit?: number): Promise<TradeFill[]>;
+}
+/** OKX state → api OrderStatus（本切片 vocab：live/partially_filled/filled/canceled）。 */
+declare function mapOrderState(state: string): OrderStatus;
+/** crypto_place_order 参数契约（OKX 词汇：instId 带连字符、side/ordType 小写）。 */
+interface PlaceOrderArgs {
+  /** 交易对符号：市场规范形（BTCUSDT / BTCUSDT-SWAP）或 OKX 原生形（BTC-USDT）皆收（docs/symbol-vocabulary.md）。 */
+  readonly instId: string;
+  /** 方向（OKX 词汇小写）。 */
+  readonly side: 'buy' | 'sell';
+  /** 订单类型（OKX ordType 词汇小写）。 */
+  readonly type: 'market' | 'limit';
+  /** **base 币数量**（SPOT 与 SWAP 同语义；SWAP 由连接器按 ctVal 换算成张）。必须 > 0。 */
+  readonly quantity: number;
+  /** LIMIT 单必填（schema 无法条件必填，execute 内校验），必须 > 0。 */
+  readonly price?: number;
+  /** 缺省视为 true：仅模拟。显式 false 即实盘意图，进入三态闸门 ②/③。 */
+  readonly dryRun?: boolean;
+}
+/**
+ * 三态闸门判定（顺序即铁律 #3 修订版的裁决顺序；主 agent 裁决的三态环境映射）：
+ *  - `reject`   —— ① 请求实盘（dryRun!==true）而 liveTrading=false：结构化拒绝；
+ *  - `simulate` —— ② dryRun=true（显式/缺省/被 config.dryRun 强制）：本地模拟回执；
+ *  - `live`     —— ③ dryRun=false 且 liveTrading=true：真实签名下单，environment
+ *                 决定是否带模拟盘头（demo=第一默认目标；live=实盘，base 闸门照旧 ask）。
+ */
+type OrderGateVerdict = {
+  action: 'reject';
+  code: 'TRADING_LIVE_TRADING_DISABLED';
+  message: string;
+} | {
+  action: 'simulate';
+} | {
+  action: 'live';
+  environment: 'demo' | 'live';
+};
+declare function evaluateOrderGate(config: Config, args: PlaceOrderArgs): OrderGateVerdict;
+/** DRY-RUN 回执（connector-binance 同款形状；参照行情来自 OKX 公共 ticker）。 */
+interface DryRunReference {
+  source: 'okx-public-ticker';
+  price?: number;
+  bid?: number;
+  ask?: number;
+  timestamp?: number;
+  unavailable?: string;
+}
+declare function buildDryRunReceipt(args: PlaceOrderArgs, marketData: Pick<OkxMarketDataService, 'getTicker'>): Promise<string>;
+interface PlaceOrderToolDeps {
+  /** 行情服务（dry-run 回执的市价参照），按接口取用，不直连 REST。 */
+  readonly marketData: Pick<OkxMarketDataService, 'getTicker'>;
+  /** 交易服务（闸门 ③ 的真实签名下单路径）。 */
+  readonly trade: TradeService;
+  /** 插件配置（dryRun 强制模拟 / liveTrading 总闸门 / env 三态）。 */
+  readonly config: Config;
+}
+/**
+ * crypto_place_order 工具工厂（独立导出便于单测三态闸门矩阵）。
+ *
+ * 审批不在这里做：dryRun!==true 的调用由 @dshtrading/base 的 gate 插件在
+ * `tools/pre-execute` waterfall 统一 ask（headless 下 ask=deny，fail-closed）；
+ * 工具内不再重复调 ctx.approval。
+ */
+declare function createPlaceOrderTool(deps: PlaceOrderToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** 本连接器的路由 provider slug（docs/exchange-routing.md §2.2）。 */
+declare const ROUTER_PROVIDER = "okx";
+/** 市场路由服务的最小消费面（api 包 MarketRouterService 同构；不定死接口）。 */
+interface MarketRouterLike {
+  activeProvider(market: string): string | undefined;
+}
+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 };