/* eslint-disable @typescript-eslint/no-explicit-any */ import { APIResponseV3, APIResponseWithTime, ContractActiveOrdersRequest, ContractCancelOrderRequest, ContractClosedPNLRequest, ContractHistoricOrder, ContractHistoricOrdersRequest, ContractListResult, ContractModifyOrderRequest, ContractOrderRequest, ContractPositionsRequest, ContractSetAutoAddMarginRequest, ContractSetMarginSwitchRequest, ContractSetPositionModeRequest, ContractSetTPSLRequest, ContractSymbolTicker, ContractUserExecutionHistoryRequest, ContractWalletFundRecordRequest, PaginatedResult, UMCandlesRequest, UMCategory, UMFundingRateHistoryRequest, UMInstrumentInfoRequest, UMOpenInterestRequest, UMOptionDeliveryPriceRequest, UMPublicTradesRequest, } from './types'; import { REST_CLIENT_TYPE_ENUM } from './util'; import BaseRestClient from './util/BaseRestClient'; /** * REST API client for Derivatives V3 Contract APIs * @deprecated WARNING * These endpoints are being switched off gradually and are expected to be completely turned off by the end of 2024. * They may stop working at any point before then. * Please update your code as soon as possible to use the V5 APIs instead. */ export class ContractClient extends BaseRestClient { getClientType() { // Follows the same authentication mechanism as other v3 APIs (e.g. USDC) return REST_CLIENT_TYPE_ENUM.v3; } async fetchServerTime(): Promise { const res = await this.getServerTime(); return Number(res.time_now); } /** * * Market Data Endpoints : these seem exactly the same as the unified margin market data endpoints * */ /** Query order book info. Each side has a depth of 25 orders. */ getOrderBook( symbol: string, category?: string, limit?: number, ): Promise> { return this.get('/derivatives/v3/public/order-book/L2', { category, symbol, limit, }); } /** Get candles/klines */ getCandles(params: UMCandlesRequest): Promise> { return this.get('/derivatives/v3/public/kline', params); } /** Get a symbol price/statistics ticker */ getSymbolTicker( category: UMCategory | '', symbol?: string, ): Promise>> { return this.get('/derivatives/v3/public/tickers', { category, symbol }); } /** Get trading rules per symbol/contract, incl price/amount/value/leverage filters */ getInstrumentInfo( params: UMInstrumentInfoRequest, ): Promise> { return this.get('/derivatives/v3/public/instruments-info', params); } /** Query mark price kline (like getCandles() but for mark price). */ getMarkPriceCandles(params: UMCandlesRequest): Promise> { return this.get('/derivatives/v3/public/mark-price-kline', params); } /** Query Index Price Kline */ getIndexPriceCandles(params: UMCandlesRequest): Promise> { return this.get('/derivatives/v3/public/index-price-kline', params); } /** * The funding rate is generated every 8 hours at 00:00 UTC, 08:00 UTC and 16:00 UTC. * For example, if a request is sent at 12:00 UTC, the funding rate generated earlier that day at 08:00 UTC will be sent. */ getFundingRateHistory( params: UMFundingRateHistoryRequest, ): Promise> { return this.get( '/derivatives/v3/public/funding/history-funding-rate', params, ); } /** Get Risk Limit */ getRiskLimit( category: UMCategory, symbol: string, ): Promise> { return this.get('/derivatives/v3/public/risk-limit/list', { category, symbol, }); } /** Get option delivery price */ getOptionDeliveryPrice( params: UMOptionDeliveryPriceRequest, ): Promise> { return this.get('/derivatives/v3/public/delivery-price', params); } /** Get public trading history */ getTrades(params: UMPublicTradesRequest): Promise> { return this.get('/derivatives/v3/public/recent-trade', params); } /** * Gets the total amount of unsettled contracts. * In other words, the total number of contracts held in open positions. */ getOpenInterest(params: UMOpenInterestRequest): Promise> { return this.get('/derivatives/v3/public/open-interest', params); } /** * * Contract Account Endpoints * */ /** -> Order API */ /** Place an order */ submitOrder(params: ContractOrderRequest): Promise> { return this.postPrivate('/contract/v3/private/order/create', params); } /** * Query order history. * * As order creation/cancellation is asynchronous, the data returned from the interface may be delayed. * To access order information in real-time, call getActiveOrders(). */ getHistoricOrders( params: ContractHistoricOrdersRequest, ): Promise>> { return this.getPrivate('/contract/v3/private/order/list', params); } /** Cancel order */ cancelOrder(params: ContractCancelOrderRequest): Promise> { return this.postPrivate('/contract/v3/private/order/cancel', params); } /** Cancel all orders */ cancelAllOrders(symbol: string): Promise> { return this.postPrivate('/contract/v3/private/order/cancel-all', { symbol, }); } /** * Replace order * * Active order parameters (such as quantity, price) and stop order parameters * cannot be modified in one request at the same time. * * Please request modification separately. */ modifyOrder(params: ContractModifyOrderRequest): Promise> { return this.postPrivate('/contract/v3/private/order/replace', params); } /** Query Open Order(s) (real-time) */ getActiveOrders( params: ContractActiveOrdersRequest, ): Promise> { return this.getPrivate( '/contract/v3/private/order/unfilled-orders', params, ); } /** -> Positions API */ /** * Query my positions real-time. Accessing personal list of positions. * Either symbol or settleCoin is required. * Users can access their position holding information through this interface, such as the number of position holdings and wallet balance. */ getPositions(params?: ContractPositionsRequest): Promise> { return this.getPrivate('/contract/v3/private/position/list', params); } /** Set auto add margin, or Auto-Margin Replenishment. */ setAutoAddMargin( params: ContractSetAutoAddMarginRequest, ): Promise> { return this.postPrivate( '/contract/v3/private/position/set-auto-add-margin', params, ); } /** Switch cross margin mode/isolated margin mode */ setMarginSwitch( params: ContractSetMarginSwitchRequest, ): Promise> { return this.postPrivate( '/contract/v3/private/position/switch-isolated', params, ); } /** Supports switching between One-Way Mode and Hedge Mode at the coin level. */ setPositionMode( params: ContractSetPositionModeRequest, ): Promise> { return this.postPrivate( '/contract/v3/private/position/switch-mode', params, ); } /** * Switch mode between Full or Partial */ setTPSLMode( symbol: string, tpSlMode: 'Full' | 'Partial', ): Promise> { return this.postPrivate('/contract/v3/private/position/switch-tpsl-mode', { symbol, tpSlMode, }); } /** Leverage setting. */ setLeverage( symbol: string, buyLeverage: string, sellLeverage: string, ): Promise> { return this.postPrivate('/contract/v3/private/position/set-leverage', { symbol, buyLeverage, sellLeverage, }); } /** * Set take profit, stop loss, and trailing stop for your open position. * If using partial mode, TP/SL/TS orders will not close your entire position. */ setTPSL(params: ContractSetTPSLRequest): Promise> { return this.postPrivate( '/contract/v3/private/position/trading-stop', params, ); } /** Set risk limit */ setRiskLimit( symbol: string, riskId: number, /** 0-one-way, 1-buy side, 2-sell side */ positionIdx: 0 | 1 | 2, ): Promise> { return this.postPrivate('/contract/v3/private/position/set-risk-limit', { symbol, riskId, positionIdx, }); } /** * Get user's trading records. * The results are ordered in descending order (the first item is the latest). Returns records up to 2 years old. */ getUserExecutionHistory( params: ContractUserExecutionHistoryRequest, ): Promise> { return this.getPrivate('/contract/v3/private/execution/list', params); } /** * Get user's closed profit and loss records. * The results are ordered in descending order (the first item is the latest). */ getClosedProfitAndLoss( params: ContractClosedPNLRequest, ): Promise> { return this.getPrivate('/contract/v3/private/position/closed-pnl', params); } /** Get the information of open interest limit. */ getOpenInterestLimitInfo(symbol: string): Promise> { return this.getPrivate('/contract/v3/private/position/limit-info', { symbol, }); } /** -> Account API */ /** Query wallet balance */ getBalances(coin?: string): Promise> { return this.getPrivate('/contract/v3/private/account/wallet/balance', { coin, }); } /** Get user trading fee rate */ getTradingFeeRate(symbol?: string): Promise> { return this.getPrivate('/contract/v3/private/account/fee-rate', { symbol, }); } /** * Get wallet fund records. * This endpoint also shows exchanges from the Asset Exchange, * where the types for the exchange are ExchangeOrderWithdraw and ExchangeOrderDeposit. * * This endpoint returns incomplete information for transfers involving the derivatives wallet. * Use the account asset API for creating and querying internal transfers. */ getWalletFundRecords( params?: ContractWalletFundRecordRequest, ): Promise> { return this.getPrivate( '/contract/v3/private/account/wallet/fund-records', params, ); } /** * * API Data Endpoints * */ getServerTime(): Promise { return this.get('/v2/public/time'); } }