API Reference

Complete API Reference

Kuant.ai Exchange Futures API - Complete Endpoint Reference

Contract Basic Information

Contract Info

Basic Info

/dex/v1/future/contract POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description

Response Data

Name	Type	Required	Description
code	string	Required
msg	string	Required
data	object	Required
contractList	object []	Required	Contract list
id	number	Required	Contract ID
contractName	string	Required	Contract name
contractOtherName	string	Required	Contract alias (frontend display)
classification	string	Required	Contract classification: 1 USDT contract, 2 Coin-margined contract, 3 Mixed contract, 4 Demo contract
symbol	string	Required	Contract trading pair
contractType	string	Required	Contract type, E: Perpetual contract, H: Mixed contract
contractShowType	string	Required	Contract type, display field after conversion
deliveryKind	string	Required	Delivery cycle
contractSide	number	Required	Contract direction (Inverse: 0, Linear: 1)
multiplier	number	Required	Contract face value
multiplierCoin	string	Required	Contract face value unit (currency name when base currency)
marginCoin	string	Required	Margin currency (note: alias)
originalCoin	string	Required	Actual margin currency
capitalStartTime	number	Required	Funding rate collection start time (hour 0-23)
capitalFrequency	string	Required	Interval duration (unit: hours)
capitalPremiumMin	number	Required	Premium deviation ratio minimum (without percentage)
capitalPremiumMax	number	Required	Premium deviation ratio maximum (without percentage)
settlementFrequency	number	Required	Settlement frequency (unit: minutes)
nextCapitalSettTime	number	Required	Next funding fee settlement timestamp
brokerId	number	Required	Exclusive client ID, 1 means none
base	string	Required	Base currency (quantity unit)
quote	string	Required	Quote currency (price unit)
marginRate	number	Required	Margin exchange rate
maxLever	number	Required	System configured max leverage
minLever	number	Required	System configured min leverage
sort	string	Required	Sort order
subSymbol	string	Required	Actual type_trading pair
defaultLevel	number	Required	Contract default leverage
coType	string	Required	Contract classification type
coinResultVo	object	Required	Currency pair configuration object
symbolPricePrecision	number	Required	Contract pair price precision
marginCoinPrecision	string	Required	Margin currency display precision
depth	string []	Required	Depth array
minOrderVolume	number	Required	Minimum order volume
minOrderMoney	number	Required	Minimum order amount
maxMarketVolume	number	Required	Maximum market order volume
maxMarketMoney	number	Required	Maximum market order amount
maxLimitVolume	number	Required	Maximum limit order volume
maxLimitMoney	number	Required	Maximum limit order amount
priceRange	number	Required	Maximum order price deviation ratio (without percentage sign)
minPriceRange	number	Required
marketPriceRange	number	Required	Market price deviation ratio
liquidationRate	number	Required	Liquidation fee rate
currentTimeMillis	number	Required	Request timestamp
marginCoinList	string []	Required	Margin currency list (aliases)
		Optional	Margin currency (alias)
originalCoinList	string []	Required	Actual margin currency set
		Optional	Actual margin currency
wsUrl	number	Required	WebSocket URL
contractProInfo	string	Required	Contract product description URL
positionSharePicMap	object	Required
1	object []	Required	Daytime
id	string	Required	id
picType	string	Required	1 Profit background image, 2 Loss background image, 3 Base image
rateRange	string	Required	Ratio: 0 (0~20), 1 (21~40), 2 (41~60), 3 (61~80), 4 (80+)
url	string	Required	url
positionShareLanList	object []	Required
id	string	Required
rateRange	number	Required	Ratio: 0 (0~20), 1 (21~40), 2 (41~60), 3 (61~80), 4 (80+)
content	string	Required	Content
type	string	Required	1 Profit, 2 Loss
contractProList	object []	Required	Contract tutorial configuration
contractProInfo	string	Required	Contract product description URL
showContractProInfoFlag	string	Required	Contract tutorial entry: 0 Hidden, 1 Shown
contractProDayIcon	string	Required	Contract tutorial daytime icon
contractProNightIcon	string	Required	Contract tutorial nighttime icon
contractDataList	object []	Required	Contract data configuration
showContractDataFlag	string	Required	Contract data entry: 0 Hidden, 1 Shown
contractDataDayIcon	string	Required	Contract data daytime icon
contractDataNightIcon	string	Required	Contract data nighttime icon
showContractProInfoFlag	string	Required	Contract tutorial entry: 0 Hidden, 1 Shown
companyId	string	Required	Merchant ID

Conditional Orders & Order History

Current/Historical Conditional Orders

Basic Info

/dex/v1/future/trigger_record POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Required	Chain ID
account	string	Optional	Wallet address
contractName	string	Optional	Contract name
orderStatus	number	Optional	Status: 0 Triggered conditional orders, 1 Currently active conditional orders
page	number	Optional	Page number
pageSize	number	Optional	Page size

Response Data

Name	Type	Required	Description
code	string	Required
msg	string	Required
data	object	Required
triggerOrderList	object []	Required
positionType	number	Optional	Position type (1 Cross margin, 2 Isolated margin)
orderId	string	Optional	Order ID after conditional order triggered
memo	number	Optional	Order status note
source	number	Optional	Order source (1 web, 2 app, 3 api, 4 other)
type	number	Optional	0 Regular conditional order
mtime	number	Optional	Update time
uid	number	Optional	User ID
price	number	Optional	Order price
ctime	number	Optional	Creation time
contractName	string	Optional	Contract name
triggerOrderId	number	Optional	Conditional order primary key ID
side	string	Optional	Buy/sell direction (buy: Buy, sell: Sell)
brokerId	number	Optional	Merchant ID
clientId	string	Optional	Client order identifier
triggerPrice	number	Optional	Trigger price
leverageLevel	number	Optional	Leverage multiplier
volume	number	Optional	Order quantity (market order for opening: amount)
masterId	number	Optional	OTO associated main order ID
expireTime	number	Optional	Conditional order expiration time
positionId	number	Optional	Position ID for take-profit or stop-loss order
timeinForce	number	Optional	Time in force (1 limit, 2 market, 3 IOC, 4 FOK, 5 POST_ONLY)
contractId	number	Optional	Contract ID
triggerType	number	Optional	Conditional order type (1 Stop loss, 2 Take profit, 3 Chase long, 4 Chase short)
open	string	Optional	Open/close position direction (open: Open position, close: Close position)
status	number	Optional	Active status (0 Active, 1 Expired, 2 Completed, 3 Trigger failed)
triggerCount	string	Required	Count

Order History

Basic Info

/dex/v1/future/orderHistorical POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Required	Chain ID
account	string	Required	Wallet address
contractName	string	Required	Contract name
page	number	Optional	Page number
limit	number	Optional	Page size

Response Data

Name	Type	Required	Description
code	string	Required
msg	string	Required
data	object	Required
list	object []	Required
side	string	Required	Direction
clientId	string	Required	Client order identifier
ctimeMs	number	Required	Creation time (ms)
positionType	number	Required	Position type
orderId	number	Required	Order ID
avgPrice	number	Required	Close position average price (this field is not provided if the source is a liquidation order)
openOrClose	string	Required	Open/close direction (open: Open position, close: Close position), same as open value
leverageLevel	number	Required	Leverage
type	number	Required	Order type
closeTakerFeeRate	number	Required	Close position taker fee rate
openEndPrice	number	Required	Order quantity
openMakerFeeRate	number	Required	Open position maker fee rate
dealVolume	number	Required	Filled quantity
price	number	Required	Order price (this field is not provided if the source is a liquidation order)
closeMakerFeeRate	number	Required	Close position maker fee rate
contractId	number	Required	Contract ID
ctime	string	Required	Creation time
contractName	string	Required	Contract name
openTakerFeeRate	number	Required	Open position taker fee rate
dealMoney	number	Required	Filled amount
status	number	Required	Status
realizedAmount	number	Required	Cumulative order profit/loss

futures-api

Futures Trading

get_ladder_info Contract Endpoint

Basic Info

/dex/v1/future/get_ladder_info POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
contractId	string	Optional	Contract ID

Response Data

Name	Type	Required	Description
code	string	Optional
msg	string	Optional
data	object	Optional
leverList	object	Optional	List
leverList	object []	Optional
level	number	Required
maxHoldAmount	number	Required
maxLever	number	Required
minLever	number	Required
maxLever	number	Optional	Maximum
name	string	Optional	Contract name
ctime	string	Optional	Creation time
minLever	number	Optional	Minimum
id	number	Optional	Contract ID
mtime	string	Optional	Modification time
leverConfig	string	Optional	Basic configuration
leverOriginCeiling	object	Optional	Multiplier corresponding values
1	number	Optional
2	number	Optional
3	number	Optional
4	number	Optional
5	number	Optional
10	number	Optional
25	number	Optional
50	number	Optional
75	number	Optional
ladderList	object	Optional	Tier list
ladderConfig	string	Optional	Basic configuration
ladderList	object []	Optional
level	number	Required
minMarginRate	number	Required	Minimum margin rate
minPositionValue	number	Required	Minimum position value
maxPositionValue	number	Required	Maximum position value
name	string	Optional	Contract name
ctime	string	Optional	Creation time
id	number	Optional	Contract ID
mtime	string	Optional	Update time
leverCeiling	object	Optional	Maximum position held for leverage
1	number	Optional
2	number	Optional
3	number	Optional
4	number	Optional
5	number	Optional
10	number	Optional
25	number	Optional
50	number	Optional
75	number	Optional

price_list Contract Endpoint

Basic Info

/dex/v1/future/price_list POST

API Description:

Request Parameters

Response Data

Name	Type	Required	Description
code	string	Optional
msg	string	Optional
data	object []	Optional
E-BTC-USDT	object	Optional
buyOne	number	Optional	Best bid
tagPrice	number	Optional	Mark price
sellOne	number	Optional	Best ask
lastPrice	number	Optional	Last price

Positions

Basic Info

/dex/v1/future/account POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
account	string	Required	Wallet address
chainId	number	Required	Chain ID

Response Data

Name	Type	Required	Description
account	object []	Optional
marginCoin	string	Required	Margin currency
canUse	string	Required	Available
canAmount	string	Required	Available amount max(accountNormal - totalCost, 0)
totalAmount	string	Required	max(partEquity + totalEquity + accountLock, 0)
totalMargin	string	Required	totalEquity
accountNormal	string	Required	Balance account
accountLock	string	Required	Margin frozen account
partPositionNormal	string	Required	Isolated margin balance
totalPositionNormal	string	Required	Cross margin initial margin used
achievedAmount	string	Required	Realized PnL
unrealizedAmount	string	Required	Unrealized PnL
totalMarginRate	string	Required	Cross margin rate
totalEquity	string	Required	Cross margin equity
partEquity	string	Required	Isolated margin equity
totalCost	string	Required	Cross margin cost used
sumMarginRate	string	Required	Total account margin rate
positionVos	object []	Required	Position contract records
contractId	string	Required	Contract ID
contractName	string	Required	Contract name
contractSymbol	string	Required	Contract trading pair
positions	object	Required	Position details
id	string	Required	Position ID
positionType	string	Required	Position type (1 Cross margin, 2 Isolated margin)
side	string	Required	Position direction: SELL Long position, BUY Short position
volume	string	Required	Position quantity
openPrice	string	Required	Open price
avgPrice	string	Required	Position average price
closePrice	string	Required	Close position average price
leverageLevel	string	Required	Leverage multiplier
holdAmount	string	Required	Position margin
closeVolume	string	Required	Closed quantity
pendingCloseVolume	string	Required	Pending close order quantity
realizedAmount	string	Required	Realized PnL
historyRealizedAmount	string	Required	Historical cumulative realized PnL
tradeFee	string	Required	Trading fee
capitalFee	string	Required	Funding fee
closeProfit	string	Required	Close position PnL
shareAmount	string	Required	Shared amount
freezeLock	string	Required	Position freeze status: 0 Normal, 1 Liquidation frozen, 2 Delivery frozen
status	string	Required	Position validity: 0 Invalid, 1 Valid
ctime	string	Required
mtime	string	Required
brokerId	string	Required	Merchant ID
lockTime	string	Required	Liquidation lock time
marginRate	string	Required	Margin rate
reducePrice	string	Required	Auto-deleveraging price
returnRate	string	Required	Return rate (yield)
unRealizedAmount	string	Required	Unrealized PnL
openRealizedAmount	string	Required	Open position unrealized PnL
positionBalance	string	Required	Position value
indexPrice	string	Required	Latest mark price
keepRate	string	Required	Tier minimum maintenance margin rate
maxFeeRate	string	Required	Maximum close position fee rate
type		Optional

Create Conditional Order (Open/Close Position)

Basic Info

/dex/v1/future/trigger_order POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
account	string	Optional	Wallet address
contractName	string	Required	Contract name, e.g. BTC-USDT
volume	number	Required	Order quantity (contracts), for market orders opening positions this value unit is in notional value
price	number	Required	Order price
type	string	Required	Order type: MARKET / LIMIT
side	string	Required	Buy/sell direction: BUY / SELL
open	string	Required	Open/close direction: OPEN / CLOSE
positionType	string	Required	Position type: 1 Cross margin / 2 Isolated margin
clientOrderId	string	Optional	Client order ID, max 32 characters
timeInForce	string	Optional	GTC / IOC / FOK / POST_ONLY
triggerPrice	number	Required	Trigger price
triggerType	string	Required	Conditional order: 3 Chase long / 4 Chase short

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	object	Optional
triggerIds	string []	Optional	Conditional order IDs
ids	string []	Optional	Order IDs
cancelIds	string []	Optional	Cancelled order IDs

Cancel All Orders

Basic Info

/dex/v1/future/cancel_orders POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
account	string	Required	User address
contractName	string	Optional	Filter by contract
isConditionOrder	boolean	Required	Whether it is a conditional order (true/false)

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	null	Optional

Cancel Conditional Order (Single)

Basic Info

/dex/v1/future/trigger_cancel POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
account	string	Required	User address
orderId	string	Required	Conditional order ID (triggerOrderId)
contractName	string	Required	Contract name

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	null	Optional

Current/Historical Conditional Orders with Count (New)

Basic Info

/dex/v1/future/trigger_record POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
account	string	Optional	Wallet address
contractName	string	Optional	Contract name
orderStatus	number	Optional	1 Not triggered, 0 Triggered
page	number	Optional	Page number
pageSize	number	Optional	Page size

Response Data

Name	Type	Required	Description
code	string	Required
msg	string	Required
data	object	Required
triggerOrderList	object []	Required
orderId	string	Required	Order ID (system generated)
contractName	string	Required	Contract name
price	string	Required	Order price
origQty	string	Required	Order quantity
executedQty	string	Required	Filled order quantity
avgPrice	string	Required	Average filled price of the order
type	string	Required	Order type. Possible values: LIMIT and MARKET
side	string	Required	Order direction. Possible values: BUY (buy/long) and SELL (sell/short)
status	string	Required	Order status. Possible values: NEW (new order, no fills), PARTIALLY_FILLED (partially filled), FILLED (fully filled), CANCELED (cancelled), and REJECTED (order rejected).
action	string	Required	OPEN/CLOSE
transactTime	number	Required	Order creation time
triggerCount	string	Required	Count

Current Orders with Count (New)

Basic Info

/dex/v1/future/openOrdersCount POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Required	Chain ID
account	string	Optional	Wallet address
contractName	string	Optional	Contract name
page	number	Optional	Page number
pageSize	number	Optional	Page size

Response Data

Name	Type	Required	Description
code	string	Required
msg	string	Required
data	object	Required
orderList	object []	Required
orderId	string	Required	Order ID (system generated)
contractName	string	Required	Contract name
price	string	Required	Order price
origQty	string	Required	Order quantity
executedQty	string	Required	Filled order quantity
avgPrice	string	Required	Average filled price of the order
type	string	Required	Order type. Possible values: LIMIT and MARKET
side	string	Required	Order direction. Possible values: BUY (buy/long) and SELL (sell/short)
status	string	Required	Order status. Possible values: NEW (new order, no fills), PARTIALLY_FILLED (partially filled), FILLED (fully filled), CANCELED (cancelled), and REJECTED (order rejected).
action	string	Required	OPEN/CLOSE
transactTime	number	Required	Order creation time
count	string	Required	Count

Trade Records (New)

Basic Info

/dex/v1/future/tradesRecord POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Required	Chain ID
account	string	Optional	Wallet address
contractName	string	Required	Contract name
page	string	Optional	Page number
limit	string	Optional	Page size

Response Data

Name	Type	Required	Description
code	string	Required
msg	string	Required
data	object	Required
list	object []	Required
symbol	string	Required	Currency name (trading pair)
tradeId	string	Required	Trade ID
bidId	string	Required	Buyer order ID
askId	string	Required	Seller order ID
bidUserId	string	Required	Buyer user ID
askUserId	string	Required	Seller user ID
price	string	Required	Trade price
qty	string	Required	Trade quantity
amount	string	Required	Trade amount
time	string	Required	Trade timestamp
fee	string	Required	Trading fee
side	string	Required	Current order direction: BUY Buy, SELL Sell
contractName	string	Required	Contract name
isMaker	string	Required	Whether maker
isBuyer	string	Required	Whether buyer

Take Profit/Stop Loss - Create Conditional Order

Basic Info

/dex/v1/future/profitLossOrder POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
account	string	Optional	Wallet address
contractName	string	Required	Contract name
positionType	string	Required	Position type: 1 Cross margin / 2 Isolated margin
side	string	Required	Direction (opposite to position side)
orderList	object []	Required	TP/SL sub-order list
triggerType	number	Required	Conditional order type: 1 Stop loss, 2 Take profit
type	number	Required	Order type: 1 Limit, 2 Market
price	number	Required	Order price
volume	number	Required	Quantity (contracts)
triggerPrice	number	Required	Trigger price

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	object	Optional
ids	string []	Optional

User Deposit Records

Basic Info

/dex/v1/futures/margin/increase_records POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
account	string	Optional	Wallet address
page	number	Optional	Page number (default 1)
size	number	Optional	Page size (default 10)

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	object []	Optional
chainId	number	Optional	Chain ID
userAddress	string	Optional	User wallet address
marginAddress	string	Optional	Margin currency address
amount	number	Optional	Deposit amount
status	number	Optional	Withdrawal status: 0 Processing, 1 Processed successfully, 2 Processing failed
txid	string	Optional	Deposit on-chain hash
blockExplorerUrl	string	Optional	Blockchain explorer URL, e.g. https://polygonscan.com
depositTime	number	Optional	Deposit on-chain time, millisecond timestamp

User Signature Authentication

Basic Info

/dex/v1/user/auth POST

API Description:

New signatureType parameter added
2 EIP712 structured signature
3 ethSign legacy signature, pass 3 to continue using the legacy version

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Required	Chain ID
userAddress	string	Required	User wallet address
signatureType	integer	Required	Signature type: 2 EIP712, 3 ethSign
r	string	Required	ETH signature r
s	string	Required	ETH signature s
v	string	Required	ETH signature v
invitedCode	string	Optional	Referrer invitation code

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	object	Optional
token	string	Optional

Query Futures Trading Settings

Basic Info

/dex/v1/user/futures_ext_info POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
contractId	string	Required	Contract ID

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	object	Optional
positionModel	number	Optional	Position type: 1 One-way position
coUnit	number	Optional	PC page order confirmation popup switch: 0 Enabled, 1 Disabled
pcSecondConfirm	number	Optional	Contract unit: 1 Base currency, 2 Contracts
nowLevel	string	Required	Leverage multiplier
leverOriginCeiling	string	Required
priceBasis	string	Required	Price basis: 0 Latest price, 1 Mark price
conditionExpiredTime	string	Required	Conditional order expiration time

Save Futures Trading Settings

Basic Info

/dex/v1/user/save_futures_ext POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
coUnit	number	Optional	Contract unit: 1 Base currency, 2 Contracts
pcSecondConfirm	number	Optional	PC page order confirmation popup switch: 0 Enabled, 1 Disabled
priceBasis	string	Required
conditionExpiredTime	string	Required	Conditional order expiration time

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	null	Optional

Contract Market Price

Basic Info

/dex/v1/future/public_market_info POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
contractId	string	Required	Get ID from contract endpoint

Response Data

Name	Type	Required	Description
code	string	Optional
msg	string	Optional
data	object	Optional
currentFundRate	number	Optional	Current funding rate
indexPrice	number	Optional	Index price
tagPrice	number	Optional	Mark price
nextFundRate	number	Optional	Predicted next funding rate

Modify Current Leverage

Basic Info

/dex/v1/future/level_edit POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
contractId	string	Required	Contract ID
nowLevel	number	Required	Leverage multiplier

Response Data

Name	Type	Required	Description
code	string	Optional
msg	string	Optional
data	null	Optional
succ	boolean	Optional

Query Current Leverage

Basic Info

/dex/v1/future/level POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
contractId	string	Required	Contract ID

Response Data

Name	Type	Required	Description
code	string	Optional
msg	string	Optional
data	object	Optional
nowLevel	string	Optional	Leverage multiplier

Deposit/Increase Margin

Basic Info

/dex/v1/futures/margin/increase POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
account	string	Optional	Wallet address
amount	string	Required	Deposit USDT amount

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	object	Optional
recordHash	number	Optional

Sync Deposit Margin On-chain Transaction

Basic Info

/dex/v1/futures/margin/sync_increase_margin POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional
account	string	Optional
recordHash	string	Required	Returned from increase endpoint
txid	string	Required	On-chain transaction hash

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	null	Optional

Estimate Withdrawal Fee

Basic Info

/dex/v1/futures/margin/estimate_decrease_fee POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	object	Optional
decreaseFee	string	Optional

Withdraw/Decrease Margin

Basic Info

/dex/v1/futures/margin/decrease POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
account	string	Optional	Wallet address
amount	string	Required	Withdrawal USDT amount

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	null	Optional

Query Margin Withdrawal Status

Basic Info

/dex/v1/futures/margin/decrease_status POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
recordHash	string	Required	Withdrawal hash

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	object	Optional
status	number	Optional	Withdrawal status: 0 Withdrawing, 1 Withdrawal completed

User Withdrawal Records

Basic Info

/dex/v1/futures/margin/decrease_records POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
account	string	Optional	Wallet address
page	number	Optional	Page number (default 1)
size	number	Optional	Page size (default 10)

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	object []	Optional
chainId	number	Optional	Chain ID
userAddress	string	Optional	User wallet address
marginAddress	string	Optional	Margin currency address
amount	number	Optional	Withdrawal amount (actual received amount when withdrawal is completed = withdrawal amount - fee)
fee	number	Optional	Fee
status	number	Optional	Withdrawal status: 0 Withdrawing, 1 Withdrawal completed, 2 Withdrawal failed
txid	string	Optional	Withdrawal on-chain hash
blockExplorerUrl	string	Optional	Blockchain explorer URL, e.g. https://polygonscan.com
withdrawTime	number	Optional	Withdrawal time, millisecond timestamp

Create Order (Open/Close Position)

Basic Info

/dex/v1/future/order POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
account	string	Optional	Wallet address
contractName	string	Required	Contract name, e.g. BTC-USDT
volume	number	Required	Order quantity (contracts), for market orders opening positions this value unit is in notional value
price	number	Required	Order price (0 for market orders)
type	string	Required	Order type: MARKET / LIMIT
side	string	Required	Buy/sell direction: BUY / SELL
open	string	Required	Open/close direction: OPEN / CLOSE
positionType	string	Required	Position type: 1 Cross margin / 2 Isolated margin
clientOrderId	string	Optional	Client order ID, max 32 characters
timeInForce	string	Optional	GTC / IOC / FOK / POST_ONLY

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	object	Optional
orderId	string	Optional

Cancel Order

Basic Info

/dex/v1/future/cancel POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
account	string	Required	User address
orderId	string	Required	Order ID
contractName	string	Required	Contract name

Response Data

Name	Type	Required	Description
code	number	Optional
msg	string	Optional
data	null	Optional

Contract Info

Basic Info

/dex/v1/future/contract POST

API Description:

{
"code":"0",
"msg":"success",
"data": {
"wsUrl":"ws://cows.dw2nn.com/kline-api/ws",
"marginCoinList": [
"BTC",
"EXUSD",
"USDT"
],
"contractList": [
{
"symbol":"BTC-USDT",
"contractOtherName":"BTCUSDT",
"contractShowType":"USDT Contract",
"contractType":"E",
"maxLever":125,
"deliveryKind":"0",
"multiplierCoin":"BTC",
"marginRate":1.00000000,
"quote":"USDT",
"contractName":"E-BTC-USDT",
"id":127,
"coinResultVo": {
"depth": [
"1",
"0"
],
"marginCoinPrecision":4,
"fundsOutStatus":1,
"maxMarketVolume":50000,
"symbolPricePrecision":1,
"minOrderVolume":1,
"minOrderMoney":10.5550000000000000,
"maxMarketMoney":50000.0000000000000000,
"maxLimitMoney":200000.0000000000000000,
"fundsInStatus":1,
"priceRange":0.5000000000,
"maxLimitVolume":50000
},
"settlementFrequency":1,
"contractSide":1,
"brokerId":1,
"originalCoin":"USDT",
"multiplier":0.0001000000000000,
"marginCoin":"USDT",
"sort":1,
"classification":1,
"capitalFrequency":8,
"subSymbol":"e_btcusdt",
"coType":"E",
"minLever":1,
"capitalStartTime":0,
"base":"BTC"
},
{
"symbol":"DOGE-USDT",
"contractOtherName":"DOGEUSDT",
"contractShowType":"USDT Contract",
"contractType":"E",
"maxLever":60,
"deliveryKind":"0",
"multiplierCoin":"DOGE",
"marginRate":1.00000000,
"quote":"USDT",
"contractName":"E-DOGE-USDT",
"id":146,
"coinResultVo": {
"depth": [
"6",
"4",
"2"
],
"marginCoinPrecision":4,
"fundsOutStatus":1,
"maxMarketVolume":99999999,
"symbolPricePrecision":6,
"minOrderVolume":1,
"minOrderMoney":3.0000010000000000,
"maxMarketMoney":99999999.0000000000000000,
"maxLimitMoney":999999.0000000000000000,
"fundsInStatus":1,
"priceRange":0.8000000000,
"maxLimitVolume":99999999
},
"settlementFrequency":1,
"contractSide":1,
"brokerId":1,
"originalCoin":"USDT",
"multiplier":1.0000000000000000,
"marginCoin":"USDT",
"sort":8,
"classification":1,
"capitalFrequency":8,
"subSymbol":"e_dogeusdt",
"coType":"E",
"minLever":1,
"capitalStartTime":0,
"base":"DOGE"
},
{
"symbol":"EOS-USDT",
"contractOtherName":"EOSUSDT",
"contractShowType":"USDT Contract",
"contractType":"E",
"maxLever":100,
"deliveryKind":"0",
"multiplierCoin":"EOS",
"marginRate":1.00000000,
"quote":"USDT",
"contractName":"E-EOS-USDT",
"id":135,
"coinResultVo": {
"depth": [
"3",
"1",
"0"
],
"marginCoinPrecision":4,
"fundsOutStatus":1,
"maxMarketVolume":250000,
"symbolPricePrecision":3,
"minOrderVolume":1,
"minOrderMoney":5.0000000000000000,
"maxMarketMoney":500000.0000000000000000,
"maxLimitMoney":2000000.0000000000000000,
"fundsInStatus":1,
"priceRange":0.5000000000,
"maxLimitVolume":300000
},
"settlementFrequency":1,
"contractSide":1,
"brokerId":1,
"originalCoin":"USDT",
"multiplier":1.0000000000000000,
"marginCoin":"USDT",
"sort":5,
"classification":1,
"capitalFrequency":8,
"subSymbol":"e_eosusdt",
"coType":"E",
"minLever":1,
"capitalStartTime":0,
"base":"EOS"
},
{
"symbol":"BTC-USDT",
"contractOtherName":"BTCEXUSD",
"contractShowType":"Demo Contract",
"contractType":"S",
"maxLever":125,
"deliveryKind":"0",
"multiplierCoin":"BTC",
"marginRate":1.00000000,
"quote":"USDT",
"contractName":"S-BTC-USDT",
"id":130,
"coinResultVo": {
"depth": [
"1",
"0"
],
"marginCoinPrecision":8,
"fundsOutStatus":0,
"maxMarketVolume":50000,
"symbolPricePrecision":1,
"minOrderVolume":1,
"minOrderMoney":10.5550000000000000,
"maxMarketMoney":50000.0000000000000000,
"maxLimitMoney":200000.0000000000000000,
"fundsInStatus":0,
"priceRange":0.5000000000,
"maxLimitVolume":50000
},
"settlementFrequency":1,
"contractSide":1,
"brokerId":1,
"originalCoin":"EXUSD",
"multiplier":0.0001000000000000,
"marginCoin":"EXUSD",
"sort":4,
"classification":4,
"capitalFrequency":8,
"subSymbol":"s_btcusdt",
"coType":"S",
"minLever":1,
"capitalStartTime":0,
"base":"BTC"
},
{
"symbol":"ETH-USDT",
"contractOtherName":"ETHUSDT",
"contractShowType":"USDT Contract",
"contractType":"E",
"maxLever":75,
"deliveryKind":"0",
"multiplierCoin":"ETH",
"marginRate":1.00000000,
"quote":"USDT",
"contractName":"E-ETH-USDT",
"id":128,
"coinResultVo": {
"depth": [
"1",
"0"
],
"marginCoinPrecision":4,
"fundsOutStatus":1,
"maxMarketVolume":20000,
"symbolPricePrecision":1,
"minOrderVolume":1,
"minOrderMoney":0.1000000000000000,
"maxMarketMoney":50000.0000000000000000,
"maxLimitMoney":50000.0000000000000000,
"fundsInStatus":1,
"priceRange":0.5000000000,
"maxLimitVolume":50000
},
"settlementFrequency":1,
"contractSide":1,
"brokerId":1,
"originalCoin":"USDT",
"multiplier":0.0100000000000000,
"marginCoin":"USDT",
"sort":2,
"classification":1,
"capitalFrequency":8,
"subSymbol":"e_ethusdt",
"coType":"E",
"minLever":1,
"capitalStartTime":0,
"base":"ETH"
},
{
"symbol":"BTC-USDT",
"contractOtherName":"H$1021-BTC-USDT",
"contractShowType":"Mixed Contract",
"contractType":"H1021",
"maxLever":125,
"deliveryKind":"0",
"multiplierCoin":"BTC",
"marginRate":1.00000000,
"quote":"USDT",
"contractName":"H$1021-BTC-USDT",
"id":142,
"coinResultVo": {
"depth": [
"1",
"0"
],
"marginCoinPrecision":4,
"fundsOutStatus":1,
"maxMarketVolume":50000,
"symbolPricePrecision":1,
"minOrderVolume":1,
"minOrderMoney":10.5550000000000000,
"maxMarketMoney":50000.0000000000000000,
"maxLimitMoney":200000.0000000000000000,
"fundsInStatus":1,
"priceRange":0.5000000000,
"maxLimitVolume":50000
},
"settlementFrequency":1,
"contractSide":1,
"brokerId":1021,
"originalCoin":"USDT",
"multiplier":0.0001000000000000,
"marginCoin":"USDT",
"sort":7,
"classification":1,
"capitalFrequency":2,
"subSymbol":"h1021_btcusdt",
"coType":"H",
"minLever":1,
"capitalStartTime":1,
"base":"BTC"
},
{
"symbol":"BTC-USD",
"contractOtherName":"BTCUSD",
"contractShowType":"Coin-margined Contract",
"contractType":"E",
"maxLever":125,
"deliveryKind":"0",
"multiplierCoin":"USD",
"marginRate":1.00000000,
"quote":"USD",
"contractName":"E-BTC-USD",
"id":129,
"coinResultVo": {
"depth": [
"1",
"0"
],
"marginCoinPrecision":8,
"fundsOutStatus":1,
"maxMarketVolume":500000,
"symbolPricePrecision":1,
"minOrderVolume":1,
"minOrderMoney":10.0000000000000000,
"maxMarketMoney":5000000.0000000000000000,
"maxLimitMoney":2000000.0000000000000000,
"fundsInStatus":1,
"priceRange":0.5000000000,
"maxLimitVolume":200000
},
"settlementFrequency":1,
"contractSide":0,
"brokerId":1,
"originalCoin":"BTC",
"multiplier":10.0000000000000000,
"marginCoin":"BTC",
"sort":3,
"classification":2,
"capitalFrequency":8,
"subSymbol":"e_btcusd",
"coType":"E",
"minLever":1,
"capitalStartTime":0,
"base":"BTC"
}
],
"currentTimeMillis":1675217617219,
"originalCoinList": [
"BTC",
"EXUSD",
"USDT"
],
"langList": [
{
"fileName":"",
"brokerId":1021,
"langKey":"en_US",
"backupFileAddress":"https://saas-oss.oss-cn-hongkong.aliyuncs.com/futures_lang_test/en_US_1.json",
"langName":"English",
"ctime":"2023-01-04T17:03:06",
"id":2020,
"sort":14,
"type":1,
"nowFileAddress":"http://dev-saas-oss.oss-cn-hongkong.aliyuncs.com/test-futures/20230105165643873.json",
"mtime":"2023-01-05T16:56:44",
"status":1
},
{
"fileName":"",
"brokerId":1021,
"langKey":"zh_CN",
"backupFileAddress":"https://saas-oss.oss-cn-hongkong.aliyuncs.com/futures_lang_test/zh_CN_1.json",
"langName":"Simplified Chinese",
"ctime":"2023-01-04T17:03:06",
"id":2023,
"sort":17,
"type":1,
"nowFileAddress":"https://saas-oss.oss-cn-hongkong.aliyuncs.com/futures_lang_test/zh_CN_1.json",
"mtime":"2023-01-04T17:03:06",
"status":1
}
],
"contractProInfo":"https://futuresdoc.gitbook.io/help-center/v/en/"
}
}

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description

Response Data

Name	Type	Required	Description
code	string	Required
msg	string	Required

Current Orders (Deprecated)

Basic Info

/dex/v1/future/openOrdersCount POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
account	string	Optional	Wallet address
contractName	string	Optional	Contract name

Response Data

Name	Type	Required	Description
code	string	Required
msg	string	Required
data	object	Required
list	object []	Required
orderId	string	Required	Order ID (system generated)
contractName	string	Required	Contract name
price	string	Required	Order price
origQty	string	Required	Order quantity
executedQty	string	Required	Filled order quantity
avgPrice	string	Required	Average filled price of the order
type	string	Required	Order type. Possible values: LIMIT and MARKET
side	string	Required	Order direction. Possible values: BUY (buy/long) and SELL (sell/short)
status	string	Required	Order status. Possible values: NEW (new order, no fills), PARTIALLY_FILLED (partially filled), FILLED (fully filled), CANCELED (cancelled), and REJECTED (order rejected).
action	string	Required	OPEN/CLOSE
transactTime	number	Required	Order creation time

Order History

Basic Info

/dex/v1/future/orderHistorical POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Required	Chain ID
account	string	Required	Wallet address
contractName	string	Required	Contract name
page	number	Optional	Page number
limit	number	Optional	Page size

Response Data

Name	Type	Required	Description
code	string	Required
msg	string	Required
data	object	Required
list	object []	Required
orderId	string	Required	Order ID (system generated)
contractName	string	Required	Contract name
price	string	Required	Order price
origQty	string	Required	Order quantity
executedQty	string	Required	Filled order quantity
avgPrice	string	Required	Average filled price of the order
type	string	Required	Order type. Possible values: LIMIT and MARKET
side	string	Required	Order direction. Possible values: BUY (buy/long) and SELL (sell/short)
status	string	Required	Order status. Possible values: NEW (new order, no fills), PARTIALLY_FILLED (partially filled), FILLED (fully filled), CANCELED (cancelled), and REJECTED (order rejected).
action	string	Required	OPEN/CLOSE
transactTime	number	Required	Order creation time

PnL Records

Basic Info

/dex/v1/future/profitHistorical POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Required	Chain ID
account	string	Required	Wallet address
contractName	string	Optional	Contract name
fromId	string	Optional	Start retrieving from this record
limit	number	Optional	Page size

Response Data

Name	Type	Required	Description
code	string	Required
msg	string	Required
data	object	Required
list	object []	Required
id	string	Required
contractId	string	Required	Contract ID
positionType	string	Required
leverageLevel	string	Required
side	string	Required
volume	string	Required
openPrice	string	Required
openEndPrice	string	Required
realizedAmount	string	Required
historyRealizedAmount	string	Required
tradeFee	string	Required
capitalFee	string	Required
closeProfit	string	Required
settleProfit	string	Required
shareAmount	string	Required
ctime	string	Required

Trade Records (Deprecated)

Basic Info

/dex/v1/future/tradesRecord POST

API Description:

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Description
Content-Type	application/json	Yes

Body

Name	Type	Required	Description
chainId	number	Optional	Chain ID
account	string	Optional	Wallet address
contractName	string	Required	Contract name
page	number	Optional	Page number
limit	number	Optional	Page size

Response Data

Name	Type	Required	Description
code	string	Required
msg	string	Required
data	object	Required
list	object []	Required
symbol	string	Required	Currency name (trading pair)
tradeId	string	Required	Trade ID
bidId	string	Required	Buyer order ID
askId	string	Required	Seller order ID
bidUserId	string	Required	Buyer user ID
askUserId	string	Required	Seller user ID
price	string	Required	Trade price
qty	string	Required	Trade quantity
amount	string	Required	Trade amount
time	string	Required	Trade timestamp
fee	string	Required	Trading fee
side	string	Required	Current order direction: BUY Buy, SELL Sell
contractName	string	Required	Contract name
isMaker	string	Required	Whether maker
isBuyer	string	Required	Whether buyer

User Permission Signature Guide

User Permission Signature Guide

Note: This is an informational document, not a callable API endpoint.

When **signatureType** is 3:

Rules for generating the r, s, v signature parameters in the user signature authentication endpoint

Signature calculation rules:

The string to be signed consists of the following 3 parts:

1. Fixed prefix 0x1901

2. Domain information

Consists of 4 parameters in the following order, each 64 bits, padded with zeros on the left if insufficient; values are in hexadecimal

"c2f8787176b8ac6bf7215b4adcc1e069bf4ab82d9ab1df05a57a91d425935b6e"
Hash.sha3(Numeric.toHexString("Dex".getBytes())))
Hash.sha3(Numeric.toHexString("1.0.0".getBytes())))
chainId

The chainId uses different data depending on the chain; concatenate the above 4 parameters and perform a hash calculation

3. User authentication structure parameter information

Consists of 3 parameters in the following order, each 64 bits, padded with zeros on the left if insufficient; values are in hexadecimal

"2540efc69c85c5b2f84446a1811ad6b635ebacdd63315e05cc65bfd0e22c2be5"
Hash.sha3(Numeric.toHexString("Enable Trading".getBytes()))
signDomain

The signDomain is based on the domain parameter returned by the public_info endpoint; concatenate the above 3 parameters and perform a hash calculation

String to sign = Fixed prefix + Domain information + User authentication structure parameter information. Note that during concatenation the 0x prefix should only appear once at the leftmost position; then sign using the eth_sign method, you can use web3.eth.personal.sign

Signature demo reference (Java):

// userAddress private key
private static Credentials credentials = Credentials.create("");



public static void main(String[] args){
   Long chainId = 1;
   String signDomain = "saas-dex.com";



   List<Type> structInputParameters = Arrays.asList(
       new Bytes32(Numeric.hexStringToByteArray("0x2540efc69c85c5b2f84446a1811ad6b635ebacdd63315e05cc65bfd0e22c2be5")),
       new Bytes32(Numeric.hexStringToByteArray(Hash.sha3(Numeric.toHexString("Enable Trading".getBytes())))));
       new Bytes32(Numeric.hexStringToByteArray(Hash.sha3(Numeric.toHexString(signDomain.getBytes())))));
   String structEncodeParametersHash = Hash.sha3(new DefaultFunctionEncoder().encodeParameters(structInputParameters));



   List<Type> eip712DomainInputParameters = Arrays.asList(
       new Bytes32(Numeric.hexStringToByteArray("0xc2f8787176b8ac6bf7215b4adcc1e069bf4ab82d9ab1df05a57a91d425935b6e")),
       new Bytes32(Numeric.hexStringToByteArray(Hash.sha3(Numeric.toHexString("Dex".getBytes())))),
       new Bytes32(Numeric.hexStringToByteArray(Hash.sha3(Numeric.toHexString("1.0.0".getBytes())))),
       new Uint(new BigInteger(chainId.toString())));
   String eip712DomainEncodeParametersHash = Hash.sha3(new DefaultFunctionEncoder().encodeParameters(eip712DomainInputParameters));



   String eip712Hash = Hash.sha3("0x1901"+ Numeric.cleanHexPrefix(eip712DomainEncodeParametersHash) + Numeric.cleanHexPrefix(structEncodeParametersHash));



   Sign.SignatureData signMessage = Sign.signPrefixedMessage(Numeric.hexStringToByteArray(eip712Hash), credentials.getEcKeyPair());
   logger.info("signature v:{} r:{} s:{}", new BigInteger(Numeric.cleanHexPrefix(Numeric.toHexString(signMessage.getV())), 16), Numeric.toHexString(signMessage.getR()), Numeric.toHexString(signMessage.getS()));
}

Maven dependency:

<dependency>
   <groupId>org.web3j</groupId>
   <artifactId>core</artifactId>
   <version>4.5.11</version>
</dependency>

When **signatureType** is 2:

Rules for generating the r, s, v signature parameters in the user signature authentication endpoint

Simply use the eth_signTypedData_v4 method to sign

Signature data is as follows:

const typedData = {
    types: {
      EIP712Domain: [
        { name: 'name', type: 'string' },
        { name: 'version', type: 'string' },
        { name: 'chainId', type: 'uint256' },
      ],
      UserAuth: [
        { type: 'string', name: 'action' },
        { type: 'string', name: 'signDomain' },
      ],
    },
    domain: {
      name: 'Dex',
      version: '1.0.0',
      chainId: '80001',
    },
    primaryType: 'UserAuth',
    message: {
      action: 'Enable Trading',
      signDomain: 'saas-dex.com',
    },
  };

Note: 1. The chainId in domain should match the specific chain being used

2. The action in message is fixed, signDomain uses the parameter returned by the public_info endpoint