@dshtrading/connector-okx 0.1.0

package/lib/rest.d.ts

@@ -0,0 +1,238 @@
+import { DerivativesPoint, Interval, Kline, Orderbook, Ticker, TradeTick, TradingErrorCode } from "@dshtrading/api";
+//#region src/rest.d.ts
+/** api 包 TradingError 契约的运行时 Error 实现（connector-binance 同款）。 */
+declare class TradingServiceError extends Error {
+  readonly code: TradingErrorCode;
+  constructor(code: TradingErrorCode, message: string, cause?: unknown);
+}
+/**
+ * 拼接签名 prehash：`timestamp + METHOD + requestPath + body`（调研 §1）。
+ * GET 的 query 必须已并入 requestPath；无 body 时省略（传 undefined）。
+ */
+declare function signaturePrehash(timestamp: string, method: 'GET' | 'POST', requestPath: string, body?: string): string;
+/** OK-ACCESS-SIGN：Base64(HMAC-SHA256(secret, prehash))。 */
+declare function signPayload(secret: string, prehash: string): string;
+/** OK-ACCESS-TIMESTAMP：UTC ISO 8601 毫秒精度（Date.toISOString 即该形态）。 */
+declare function isoTimestamp(epochMs: number): string;
+/** OKX 三值凭证（BYOK：由插件层每次操作从 ctx.credentials 解析，绝不落盘/打日志）。 */
+interface OkxCredentials {
+  readonly key: string;
+  readonly secret: string;
+  readonly passphrase: string;
+}
+/** 签名请求的鉴权参数：三值凭证 + 是否打模拟盘。 */
+interface SignedAuth {
+  readonly credentials: OkxCredentials;
+  /** true → 附加 `x-simulated-trading: 1`（模拟盘头级开关，调研 §2）。 */
+  readonly simulated: boolean;
+}
+/** 四头 + 模拟盘头的构造（导出供单测断言头部集合）。 */
+declare function buildAuthHeaders(auth: SignedAuth, timestamp: string, method: 'GET' | 'POST', requestPath: string, body?: string): Record<string, string>;
+/**
+ * api Interval（Binance 词汇）→ OKX bar 词汇。
+ *
+ * **1d → 1Dutc（口径裁决，回应调研待验证 #3）**：OKX `1D` 按 UTC+8 零点开盘
+ * （用户实证记忆：1D 日线边界对齐 UTC+8），而本仓 `Interval` 的 `1d` 语义继承自
+ * Binance = UTC 零点。crypto 24/7 交易、UTC 是跨所通用口径，取 `1Dutc` 才能与
+ * connector-binance 的日线对齐同一日界；`1D`（UTC+8）会导致同一标的跨连接器日 K
+ * 错位 8 小时，故不取。6h/12h/3d/1w/1M 同理取 utc 变体。
+ *
+ * **8h 无映射**：OKX bar 词汇没有 8 小时档（1m..4H、6Hutc、12Hutc、1Dutc、2Dutc、
+ * 3Dutc、1Wutc、1Mutc、3Mutc），8h 请求返回 TRADING_UNSUPPORTED_INTERVAL。
+ */
+declare const BAR_MAP: Readonly<Record<string, string>>;
+/** 支持的 interval 词汇（工具 enum 用；8h 刻意缺席，见 BAR_MAP 注释）。 */
+declare const OKX_INTERVAL_VOCABULARY: readonly string[];
+/** bar → 毫秒时长（closeTime 补算用；UTC 变体与本地变体时长相同）。 */
+declare function barDurationMs(bar: string): number;
+/** Interval → OKX bar；不支持（含 8h）抛 TRADING_UNSUPPORTED_INTERVAL。 */
+declare function toBar(interval: Interval): string;
+interface OkxRestOptions {
+  /** 覆盖 API base（测试/反代用），末尾不带斜杠。 */
+  readonly baseUrl?: string;
+  /** 单请求超时（ms），默认 10s。 */
+  readonly timeoutMs?: number;
+  /** 注入 fetch 实现；缺省用全局 fetch（Node 22+ 内置）。 */
+  readonly fetchImpl?: typeof fetch;
+  /** 禁用自动对时（离线单测）；缺省 true。 */
+  readonly clockSync?: boolean;
+  /** 注入当前墙钟（ms）；缺省 Date.now（单测固定时间用）。 */
+  readonly now?: () => number;
+  /** 预置服务器偏移（ms）；设置后跳过网络对时。 */
+  readonly clockOffsetMs?: number;
+}
+/** OKX 资金费率快照（GET /api/v5/public/funding-rate，SWAP 专用）。 */
+interface OkxFundingRate {
+  readonly instId: string;
+  readonly fundingRate: number;
+  readonly nextFundingRate?: number;
+  readonly fundingTime: number;
+  readonly nextFundingTime?: number;
+}
+/** OKX 未平仓合约量快照（GET /api/v5/public/open-interest，SWAP 专用）。 */
+interface OkxOpenInterest {
+  readonly instId: string;
+  /** 持仓量（张）。 */
+  readonly oi: number;
+  /** 持仓量（base 币数；= 张数 × ctVal，OKX 直接回填）。 */
+  readonly oiCcy?: number;
+  /** 持仓量价值（USD 计价）。 */
+  readonly oiUsd?: number;
+  readonly ts: number;
+}
+/** OKX 合约/币对规格（GET /api/v5/public/instruments；sz 单位纪律的依据，调研 §4）。 */
+interface OkxInstrument {
+  readonly instId: string;
+  readonly instType: string;
+  /** 数量步进（SPOT=base 币；SWAP=张）。 */
+  readonly lotSz: number;
+  /** 最小下单量（单位同 lotSz）。 */
+  readonly minSz: number;
+  /** 价格步进。 */
+  readonly tickSz: number;
+  /** 一张合约含多少币（仅 SWAP/FUTURES；SPOT 无此字段）。 */
+  readonly ctVal?: number;
+  readonly ctValCcy?: string;
+  readonly settleCcy?: string;
+  readonly baseCcy?: string;
+  readonly quoteCcy?: string;
+}
+/** POST /api/v5/trade/order 请求体词汇（R3 只做 market/limit；tdMode 现货=cash、永续=cross）。 */
+interface OkxPlaceOrderParams {
+  readonly instId: string;
+  readonly tdMode: 'cash' | 'cross';
+  readonly side: 'buy' | 'sell';
+  readonly ordType: 'market' | 'limit';
+  /** 字符串数量：SPOT=base 币数（market 单显式 tgtCcy=base_ccy）；SWAP=张（=coins/ctVal）。 */
+  readonly sz: string;
+  readonly px?: string;
+  readonly tgtCcy?: 'base_ccy' | 'quote_ccy';
+}
+/** 客户端侧 sz 纪律校验结果：换算后的交易所数量字符串 + 提示（index.ts 组装请求体）。 */
+interface NormalizedSize {
+  /** 发给交易所的 sz 字符串（SPOT=币数；SWAP=张）。 */
+  readonly sz: string;
+  /** 现货市价单显式 tgtCcy=base_ccy（消除「buy 缺省按计价币金额」的坑，调研 §4）。 */
+  readonly tgtCcy?: 'base_ccy';
+}
+/** 把 api 语义的 base 币数量换算成 OKX sz（本地精度校验：minSz/lotSz，省一次 51000 往返）。 */
+declare function normalizeSize(instId: string, instrument: OkxInstrument, quantityCoins: number): NormalizedSize;
+declare class OkxRestClient {
+  #private;
+  private readonly baseUrl;
+  private readonly timeoutMs;
+  private readonly fetchImpl;
+  private readonly clockSyncEnabled;
+  private readonly now;
+  /** 服务器偏移缓存（server - local，ms）；null = 未对时。 */
+  private clockOffsetMs;
+  constructor(options?: OkxRestOptions);
+  /** 当前对时后的墙钟（ms）。clockOffsetMs 预置或已缓存时直接用；否则按需对时。 */
+  private timestampMs;
+  /** 使缓存偏移失效（50102 重试路径）。 */
+  invalidateClock(): void;
+  /**
+   * 统一请求：query 拼 URL 与签名 requestPath；签名头经 buildAuthHeaders；
+   * envelope code!=='0'（含 '1' 失败 / '2' 部分成功——本客户端只发单条操作）映射为
+   * 结构化错误；50102（时差）重对时重试一次。
+   */
+  private request;
+  /** envelope/HTTP 状态处理：code==='0' → data；单行 trade 端点的 sCode 非 0 → 失败。 */
+  private processEnvelope;
+  /** 最新行情：GET /api/v5/market/ticker。 */
+  getTicker(instId: string): Promise<Ticker>;
+  /** K 线：GET /api/v5/market/candles（单请求上限 300，超出走 after 游标翻页；响应新→旧，翻转为旧→新）。 */
+  getKlines(instId: string, interval: Interval, limit?: number): Promise<Kline[]>;
+  /** 资金费率：GET /api/v5/public/funding-rate（仅 SWAP；10 次/2s）。 */
+  getFundingRate(instId: string): Promise<OkxFundingRate>;
+  /** 标记价格：GET /api/v5/public/mark-price（仅 SWAP；2026-09-03 真实网络实证）。 */
+  getMarkPrice(instId: string): Promise<{
+    instId: string;
+    markPrice: number;
+    ts: number;
+  }>;
+  /**
+   * 指数价格：GET /api/v5/market/index-tickers（现货指数成分 instId，如 HYPE-USDT；
+   * 与永续 markPx 配对算基差。2026-09-03 真实网络实证）。
+   */
+  getIndexPrice(instId: string): Promise<{
+    instId: string;
+    indexPrice: number;
+    ts: number;
+  }>;
+  /** 资金费率历史：GET /api/v5/public/funding-rate-history（响应新→旧 → 反转为升序）。 */
+  getFundingRateHistory(instId: string, limit?: number): Promise<DerivativesPoint[]>;
+  /**
+   * OI 历史：GET /api/v5/rubik/stat/contracts/open-interest-history（period=1D）。
+   * 响应是时间序列行 `[ts, oi张, oiCcy币, oiUsd]`（字符串数值，新→旧；
+   * 2026-09-03 真实网络实证）；取值列与快照同纪律——优先币数（oiCcy），退张数。
+   */
+  getOpenInterestHistory(instId: string, limit?: number): Promise<DerivativesPoint[]>;
+  /** 盘口快照：GET /api/v5/market/books（sz=20 档；bids 降序 / asks 升序，OKX 原生序）。 */
+  getOrderbook(instId: string): Promise<Orderbook>;
+  /** 最近逐笔成交：GET /api/v5/market/trades（响应新→旧 → 反转为时间升序）。 */
+  getRecentTrades(instId: string, limit?: number): Promise<TradeTick[]>;
+  /** 未平仓合约量：GET /api/v5/public/open-interest（仅 SWAP；oi=张、oiCcy=币、oiUsd=USD）。 */ getOpenInterest(instId: string): Promise<OkxOpenInterest>;
+  /**
+   * 多空账户人数比：GET /api/v5/rubik/stat/contracts/long-short-account-ratio（ccy=base 资产，period=1H）。
+   * 响应是时间序列行 `[ts, ratio]`（字符串数值，新→旧；2026-09-02 真实网络实证，
+   * spikes/impl-crypto-derivatives），取最新一行。
+   */
+  getLongShortAccountRatio(ccy: string): Promise<{
+    ccy: string;
+    ratio: number;
+    ts?: number;
+  }>;
+  /**
+   * 合约主动买卖量：GET /api/v5/rubik/stat/taker-volume（ccy=base 资产，instType=CONTRACTS）。
+   * 响应是时间序列行 `[ts, buyVol, sellVol]`（字符串数值，新→旧；2026-09-02 真实网络
+   * 实证，spikes/impl-crypto-derivatives），取最新一行。
+   */
+  getContractTakerVolume(ccy: string): Promise<{
+    ccy: string;
+    buyVol: number;
+    sellVol: number;
+  }>;
+  /** 合约/币对规格：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。
+   */
+  listInstruments(): Promise<Array<{
+    symbol: string;
+    name?: string;
+  }>>;
+  /** 只读余额：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/trade/cancel-order（ordId 优先于 clOrdId，本切片只支持 ordId）。 */
+  cancelOrder(instId: string, ordId: string, auth: SignedAuth): Promise<unknown[]>;
+  /** 查单：GET /api/v5/trade/order（query 属于签名 requestPath）。 */
+  getOrder(instId: string, ordId: string, auth: SignedAuth): Promise<unknown[]>;
+  /** 当前挂单：GET /api/v5/trade/orders-pending（instId 可选过滤；issue #40 交易台）。 */
+  listPendingOrders(instId: string | undefined, auth: SignedAuth): Promise<unknown[]>;
+  /** 最近成交明细：GET /api/v5/trade/fills-history（instId/limit 可选；issue #40 交易台）。 */
+  listFillsHistory(instId: string | undefined, limit: number | undefined, auth: SignedAuth): Promise<unknown[]>;
+}
+/**
+ * 输入归一 → OKX 原生 instId。接受规范形（BTCUSDT / BTCUSDT-SWAP）与原生形
+ *（BTC-USDT / BTC-USDT-SWAP）；都解析不出才报 TRADING_UNSUPPORTED_SYMBOL。
+ */
+declare function normalizeOkxSymbol(input: string): string;
+/**
+ * 输出归一 → 规范形（下游永远看到市场规范词汇）。原生 BTC-USDT → BTCUSDT；
+ * BTC-USDT-SWAP → BTCUSDT-SWAP；已是规范形则原样返回。
+ */
+declare function toCanonicalOkxSymbol(symbol: string): string;
+/**
+ * 衍生品端点输入归一：现货与合约输入一律升到永续 SWAP instId——
+ * BTCUSDT / BTC-USDT / BTCUSDT-SWAP / BTC-USDT-SWAP → BTC-USDT-SWAP。
+ * （GUI 选中的现货标的也要能看到对应合约的衍生品指标，issue #38。）
+ */
+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 };