Merge pull request sieblyio#184 from JJ-Cro/update09032025

feat(v3.1.3): enhance API request/response types with new fields and documentation

Author: tiagosiebler

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "okx-api",
-  "version": "3.1.2",
+  "version": "3.1.3",
   "description": "Complete Node.js SDK for OKX's REST APIs and WebSockets, with TypeScript & end-to-end tests",
   "scripts": {
     "test": "jest",

package.json

@@ -297,6 +297,7 @@ import {
   OptionTrade,
   OptionTrades,
   OrderBook,
+  PublicBorrowHistoryRecord,
   SystemTime,
   Ticker,
   Trade,
@@ -566,6 +567,7 @@ export class RestClient extends BaseRestClient {
     instId?: string;
     uly?: string;
     instFamily?: string;
+    groupId?: string;
     ruleType?: string;
   }): Promise<AccountFeeRate[]> {
     return this.getPrivate('/api/v5/account/trade-fee', params);
@@ -2493,6 +2495,8 @@ export class RestClient extends BaseRestClient {
   getConvertCurrencyPair(params: {
     fromCcy: string;
     toCcy: string;
+    /** 0: standard convert (default), 1: large order convert for VIP */
+    convertMode?: '0' | '1';
   }): Promise<any[]> {
     return this.getPrivate('/api/v5/asset/convert/currency-pair', params);
   }
@@ -2772,7 +2776,9 @@ export class RestClient extends BaseRestClient {
     return this.get('/api/v5/finance/savings/lending-rate-summary', params);
   }
 
-  getPublicBorrowHistory(params?: PaginatedSymbolRequest): Promise<any[]> {
+  getPublicBorrowHistory(
+    params?: PaginatedSymbolRequest,
+  ): Promise<PublicBorrowHistoryRecord[]> {
     return this.get('/api/v5/finance/savings/lending-rate-history', params);
   }
 

src/rest-client.ts

@@ -6,6 +6,8 @@ export interface ConvertQuoteEstimateRequest {
   rfqSzCcy: string;
   clTReqId?: string;
   tag?: string;
+  /** 0: standard convert (default), 1: large order convert for VIP */
+  convertMode?: '0' | '1';
 }
 export interface ConvertTradeRequest {
   quoteId: string;
@@ -16,4 +18,6 @@ export interface ConvertTradeRequest {
   szCcy: string;
   clTReqId?: string;
   tag?: string;
+  /** 0: standard convert (default), 1: large order convert for VIP */
+  convertMode?: '0' | '1';
 }

src/types/rest/request/convert.ts

@@ -157,7 +157,10 @@ export interface FillsHistoryRequest {
 }
 
 export interface OrderIdRequest {
-  instId: string;
+  /** Instrument ID. Deprecated March 2026 for WS; use instIdCode for lower latency. */
+  instId?: string;
+  /** Instrument ID code. Takes precedence over instId if both provided. Use Get instruments to map. WS only. */
+  instIdCode?: number;
   ordId?: string;
   clOrdId?: string;
 }
@@ -202,6 +205,8 @@ export interface OrderRequest {
   tradeQuoteCcy?: string;
   /** Self trade prevention mode: cancel_maker, cancel_taker, cancel_both. Default is cancel_maker */
   stpMode?: 'cancel_maker' | 'cancel_taker' | 'cancel_both';
+  /** ELP taker access. true = can trade with ELP orders (speed bump applied). Default false. Only applicable to ioc orders */
+  isElpTakerAccess?: boolean;
   /** Take Profit & Stop Loss params */
   tpTriggerPx?: string;
   tpOrdPx?: string;

src/types/rest/request/trade.ts

@@ -396,17 +396,27 @@ export interface AccountInstrument {
   quoteCcy: string;
   tradeQuoteCcyList: string[]; // List of quote currencies available for trading, e.g. ["USD", "USDC"]
   settleCcy: string;
+  /** Instrument status: live, suspend, rebase (SWAP only), preopen, test */
   state: string;
   stk: string;
   tickSz: string;
+  /** Trading rule types: normal, pre_market, rebase_contract */
   ruleType: string;
   auctionEndTime: string;
   futureSettlement: boolean; // Whether daily settlement for expiry feature is enabled. Applicable to FUTURES cross.
   instIdCode: number; // Instrument ID code. For simple binary encoding, must use instIdCode instead of instId.
+  /** Category of instrument's base currency. "1" = Crypto, "3" = Stocks */
+  instCategory?: string;
   posLmtAmt: string; // Maximum position value (USD) for this instrument at the user level. Applicable to SWAP/FUTURES.
   posLmtPct: string; // Maximum position ratio (e.g., 30 for 30%) a user may hold relative to platform's current total position value. Applicable to SWAP/FUTURES.
   maxPlatOILmt: string; // Platform-wide maximum position value (USD) for this instrument. Applicable to SWAP/FUTURES.
+  /** Remaining long position value (USD) the user is permitted to open. Applicable to SWAP/FUTURES. */
+  longPosRemainingQuota?: string;
+  /** Remaining short position value (USD) the user is permitted to open. Applicable to SWAP/FUTURES. */
+  shortPosRemainingQuota?: string;
   groupId?: string; // Instrument trading fee group ID
+  /** ELP maker permission. "0" = not enabled, "1" = enabled but no permission, "2" = enabled with permission */
+  elp?: string;
 }
 
 export interface QuickMarginBorrowRepayResult {

src/types/rest/response/private-account.ts

@@ -105,6 +105,7 @@ export interface Instrument {
   minSz: string;
   ctType: string;
   alias: string;
+  /** Instrument status: live, suspend, rebase (SWAP only), preopen, test */
   state: string;
   openType?: string; // Open type: fix_price (fix price opening), pre_quote (pre-quote), call_auction (call auction). Only applicable to SPOT/MARGIN.
   maxLmtSz: string;
@@ -115,11 +116,14 @@ export interface Instrument {
   maxIcebergSz: string;
   maxTriggerSz: string;
   maxStopSz: string;
+  /** Trading rule types: normal, pre_market, rebase_contract */
   ruleType: string;
   auctionEndTime: string;
   futureSettlement?: boolean; // Whether daily settlement for expiry feature is enabled. Applicable to FUTURES cross.
   tradeQuoteCcyList?: string[]; // List of quote currencies available for trading, e.g. ["USD", "USDC"]
   instIdCode?: number; // Instrument ID code. For simple binary encoding, must use instIdCode instead of instId.
+  /** Category of instrument's base currency. "1" = Crypto, "3" = Stocks */
+  instCategory?: string;
   posLmtAmt?: string; // Maximum position value (USD) for this instrument at the user level. Applicable to SWAP/FUTURES.
   posLmtPct?: string; // Maximum position ratio (e.g., 30 for 30%) a user may hold relative to platform's current total position value. Applicable to SWAP/FUTURES.
   maxPlatOILmt?: string; // Platform-wide maximum position value (USD) for this instrument. Applicable to SWAP/FUTURES.
@@ -203,6 +207,15 @@ export interface Announcement {
   url: string;
 }
 
+/** Public borrow history record (GET /api/v5/finance/savings/lending-rate-history) */
+export interface PublicBorrowHistoryRecord {
+  ccy: string; // Currency, e.g. BTC
+  amt: string; // Lending amount (deprecated)
+  rate: string; // Annual borrowing interest rate
+  lendingRate: string; // Annual lending interest rate
+  ts: string; // Unix timestamp format in milliseconds
+}
+
 export interface BasicInterestRate {
   ccy: string; // Currency
   rate: string; // Daily borrowing rate

src/types/rest/response/public-data.ts

@@ -7,7 +7,10 @@ import {
 } from '../rest/shared.js';
 
 export interface WSAPIPlaceOrderRequestV5 {
-  instId: string;
+  /** Instrument ID. Deprecated March 2026; use instIdCode for lower latency. */
+  instId?: string;
+  /** Instrument ID code. Takes precedence over instId if both provided. Use Get instruments to map. */
+  instIdCode?: number;
   tdMode: TradeMode;
   ccy?: string;
   clOrdId?: string;
@@ -26,10 +29,15 @@ export interface WSAPIPlaceOrderRequestV5 {
   banAmend?: boolean;
   tradeQuoteCcy?: string;
   stpMode?: 'cancel_maker' | 'cancel_taker' | 'cancel_both';
+  /** ELP taker access. true = can trade with ELP orders (speed bump applied). Default false. Only applicable to ioc orders */
+  isElpTakerAccess?: boolean;
 }
 
 export interface WSAPIAmendOrderRequestV5 {
-  instId: string;
+  /** Instrument ID. Deprecated March 2026; use instIdCode for lower latency. */
+  instId?: string;
+  /** Instrument ID code. Takes precedence over instId if both provided. Use Get instruments to map. */
+  instIdCode?: number;
   cxlOnFail?: boolean;
   ordId?: string;
   clOrdId?: string;