Contract Orders | openAPI-StarEx

# Contract Orders

# Place an order

POST /v1/contract/order/single

Module	Type	Resource Isolation Type	Rate Limit
Contract Order(CONTRACT_ORDER)	Submit(SUBMIT)	Trading Pair(SYMBOL)	5

# Parameters

Name	Type	Required	Description
symbol	String	Yes	Trading pair，eg.BTC/USDT
side	String	Yes	Trading direction，Available values：BUY，SELL
positionType	String	Yes	Position type，Available values：ALL，SINGLE
positionSide	String	Yes	Position direction，Available values：BOTH，LONG，SHORT
type	String	Yes	Order type，Available values：LIMIT，MARKET，PLAN_LIMIT，PLAN_MARKET
price	Decimal	No	Order price
volume	Integer	Yes	Order trading volume
triggerType	String	No	Plan order trigger type，Available values：MARK_PRICE，CONTRACT_PRICE
triggerPrice	Decimal	No	Plan order trigger price
clientOrderId	String	No	User-defined order ID (maximum length of 32 characters, must be unique)

# Response Parameters

Name	Type	Description
orderId	Long	Order ID
clientOrderId	String	User-defined order ID (if provided)

# Request Example

POST /v1/contract/order/single
{
    "symbol": "BTC/USDT",
    "side": "BUY",
    "positionType": "SINGLE",
    "positionSide": "LONG",
    "type": "MARKET",
    "volume": 10,
    "clientOrderId": "COI123456"
}

# Response Example

{
    "code": "200",
    "message": "OK",
    "timestamp": "1698998877091",
    "data": {
        "orderId": "640581852521111552",
        "clientOrderId": "COI123456"
    }
}

# Batch Order Placement

POST /v1/contract/order/batch

Module	Type	Resource Isolation Type	Rate Limit
Contract Order(CONTRACT_ORDER)	Submit(SUBMIT)	Trading Pair(SYMBOL)	5

# Parameters

Name	Type	Required	Description
	Array	Yes	Array of parameters, a batch can contain up to 10 orders
symbol	String	Yes	Trading pair，eg.BTC/USDT
side	String	Yes	Trading direction，Available values：BUY，SELL
positionType	String	Yes	Position type，Available values：ALL，SINGLE
positionSide	String	Yes	Position direction，Available values：BOTH，LONG，SHORT
type	String	Yes	Order type，Available values：LIMIT，MARKET，PLAN_LIMIT，PLAN_MARKET
price	Decimal	No	Order price
volume	Integer	Yes	Order trading volume
triggerType	String	No	Plan order trigger type，Available values：MARK_PRICE，CONTRACT_PRICE
triggerPrice	Decimal	No	Plan order trigger price
clientOrderId	String	No	User-defined order ID (maximum length of 32 characters, must be unique)

# Response Parameters

Name	Type	Description
orderId	Long	Order ID
clientOrderId	String	User-defined order ID (if provided)
errCode	String	Order rejection error code (only applicable for rejected orders)
errMsg	String	Order rejection error message (only applicable for rejected orders)

# Request Example

POST /v1/contract/order/batch
[
    {
    "symbol": "BTC/USDT",
    "side": "BUY",
    "positionType": "SINGLE",
    "positionSide": "LONG",
    "type": "MARKET",
    "volume": 10,
    "clientOrderId": "COI123456"
    },
    {
    "symbol": "ETH/USDT",
    "side": "BUY",
    "positionType": "SINGLE",
    "positionSide": "SHORT",
    "type": "MARKET",
    "volume": 20,
    "clientOrderId": "COI123123"
    }
]

# Response Example

{
    "code": "200",
    "message": "OK",
    "timestamp": "1699003777337",
    "data": [
        {
            "clientOrderId": "COI123456",
            "errCode": "API1100",
            "errMsg": "duplicate clientOrderId：COI123456"
        },
        {
            "orderId": "640603504344637441",
            "clientOrderId": "COI123123"
        }
    ]
}

# Adjust Order Leverage

POST /v1/contract/order/leverage

Module	Type	Resource Isolation Type	Rate Limit
Contract Order(CONTRACT_ORDER)	Submit(SUBMIT)	Trading Pair(SYMBOL)	5

# Parameters

Name	Type	Required	Description
symbol	String	Yes	Trading Pair
leverage	Integer	Yes	Leverage

# Response Parameters

Name	Type	Description
symbol	String	Trading Pair
leverage	Integer	Leverage

# Request Example

POST /v1/contract/order/leverage
{
	"symbol": "BTC/USDT",
	"leverage": 10
}

# Response Example

{
	"code": "200",
	"message": "OK",
	"timestamp": "1698745888704",
	"data": {
		"symbol": "BTC/USDT",
		"leverage": 10
	}
}

# Cancel Order

POST /v1/contract/order/cancel

Module	Type	Resource Isolation Type	Rate Limit
Contract Order(CONTRACT_ORDER)	Submit(SUBMIT)	Trading Pair(SYMBOL)	5

# Parameters

Name	Type	Required	Description
symbol	String	Yes	Trading Pair
orderId	Long	Yes	Order ID
clientOrderId	String	No	User-defined order ID (maximum length of 32 characters, must be unique)

# Response Parameters

Name	Type	Description
orderId	Long	Order ID
clientOrderId	String	User-defined order ID (if provided)
errCode	String	Order rejection error code (only applicable for rejected orders)
errMsg	String	Order rejection error message (only applicable for rejected orders)

# Request Example

POST /v1/contract/order/cancel
{
	"symbol": "BTC/USDT",
	"orderId": 640581735625072640,
	"clientOrderId": "COI123456"
}

# Response Example

{
	"code": "200",
	"message": "OK",
	"timestamp": "1275594006695",
	"data": {
		"symbol": "BTC/USDT",
		"orderId": "640581735625072640",
		"clientOrderId": "COI123456"
	}
}

# Batch Cancel Orders

POST /v1/contract/order/cancel/batch

Module	Type	Resource Isolation Type	Rate Limit
Contract Order(CONTRACT_ORDER)	Submit(SUBMIT)	Trading Pair(SYMBOL)	5

# Parameters

Name	Type	Required	Description
symbol	String	Yes	Trading Pair
orderIds	Array	No	Order IDs, separated by commas, (either orderIds or clientOrderIds must be provided, can only choose one, up to 50 orders). It's recommended to use orderIds for cancellation, which is faster and more stable than clientOrderIds. No more than 50 orders at a time.
clientOrderIds	Array	No	User-defined order IDs, separated by commas, (either orderIds or clientOrderIds must be provided, can only choose one, up to 50 orders). It's recommended to use orderIds for cancellation, which is faster and more stable than clientOrderIds. No more than 50 orders at a time.

# Response Parameters

Name	Type	Description
orderId	Long	Order ID
clientOrderId	String	User-defined order ID (if provided)
errCode	String	Order rejection error code (only applicable for rejected orders)
errMsg	String	Order rejection error message (only applicable for rejected orders)

# Request Example

POST /contract/order/cancel/batch
{
	"symbol": "BTC/USDT",
	"orderIds": [
		640581735625072640,
		640603500010741760
	]
}

# Response Example

{
	"code": "200",
	"message": "OK",
	"timestamp": "1704179637899",
	"data": [
		{
			"orderId": "640581735625072640",
            		"clientOrderId": "OO202404303333"
		},
		{
			"orderId": "640603500010741760",
            		"clientOrderId": "OO202404304444"
		}
	]
}

# Query unfilled orders

GET /v1/contract/order/open

Module	Type	Resource Isolation Type	Rate Limit
Contract Order(CONTRACT_ORDER)	Query(QUERY)	Trading Pair(SYMBOL)	5

# Parameters

Name	Type	Required	Description
symbol	String	Yes	Trading Pair
direction	String	No	Trading direction，Available values：BUY,SELL
positionSide	String	No	Position direction，Available values：BOTH，LONG，SHORT
types	Array	No	Combination of order types to query, separated by commas，Available values：LIMIT，MARKET，PLAN_LIMIT，PLAN_MARKET
limit	Integer	No	Number of orders to return, maximum value is 500

# Response Parameters

Name	Type	Description
symbol	String	Trading Pair
orderId	Long	Order ID
clientOrderId	String	User-defined order ID (if provided)
positionType	String	Position type：ALL，SINGLE
positionSide	String	Position direction：BOTH，LONG，SHORT
type	String	Order type：LIMIT，MARKET，PLAN_LIMIT，PLAN_MARKET
side	String	Trading direction：BUY,SELL
price	BigDecimal	Order price
volume	Integer	Order trading volume
triggerPrice	BigDecimal	Plan order trigger price
triggerType	Integer	Plan order trigger type，1：mark price，2：latest price
dealVolume	Integer	Transaction quantity
leverageLevel	Integer	Leverage
multiplier	BigDecimal	Multiplier
avgPrice	BigDecimal	Average transaction price
freezeAmount	BigDecimal	Freeze margin
feeAmount	BigDecimal	Fee
feeRateMaker	Double	Maker rate
feeRateTaker	Double	Taker rate

# Request Example

GET /v1/contract/order/open?symbol=BTC/USDT&direction=BUY&positionSide=LONG

# Response Example

{
    "code": "200",
    "message": "OK",
    "timestamp": "1704336500885",
    "data": [
        {
            "symbol": "BTC/USDT",
            "orderId": "644549923592282112",
            "clientOrderId": "OO202401031820",
            "positionType": "SINGLE",
            "positionSide": "SHORT",
            "type": "LIMIT",
            "side": "BUY",
            "price": "36666.9",
            "volume": 10,
            "triggerPrice": "0",
            "triggerType": 0,
            "dealVolume": 10,
            "leverageLevel": 1,
            "multiplier": "0.0001",
            "avgPrice": "36667",
            "freezeAmount": "36.66910001",
            "feeRateMaker": 0.0,
            "feeRateTaker": 0.0
        }
    ]
}

# Query historical orders

GET /v1/contract/order/history

Module	Type	Resource Isolation Type	Rate Limit
Contract Order(CONTRACT_ORDER)	Query(QUERY)	Trading Pair(SYMBOL)	5

# Parameters

Name	Type	Required	Description
symbol	String	Yes	Trading Pair
direction	String	No	Trading direction，Available values：BUY,SELL
positionSide	String	No	Position direction，Available values：BOTH，LONG，SHORT
types	Array	No	Combination of order types to query, separated by commas，Available values：LIMIT，MARKET，PLAN_LIMIT，PLAN_MARKET
limit	Integer	No	Number of orders to return, default value is 100，maximum value is 500

# Response Parameters

Name	Type	Description
symbol	String	Trading Pair
orderId	Long	Order ID
clientOrderId	String	User-defined order ID (if provided)
positionType	String	Position type：ALL，SINGLE
positionSide	String	Position direction：BOTH，LONG，SHORT
type	String	Order type：LIMIT，MARKET，PLAN_LIMIT，PLAN_MARKET
side	String	Trading direction：BUY,SELL
price	BigDecimal	Order price
volume	Integer	Order trading volume
triggerPrice	BigDecimal	Plan order trigger price
triggerType	Integer	Plan order trigger type，1：mark price，2：latest price
dealVolume	Integer	The number of transactions
leverageLevel	Integer	Leverage Level
multiplier	BigDecimal	Multiplier
avgPrice	BigDecimal	Average transaction price
freezeAmount	BigDecimal	Freeze margin
feeAmount	BigDecimal	Fee
feeRateMaker	Double	Maker rate
feeRateTaker	Double	Taker rate
realizedAmount	BigDecimal	Realized profit and loss
refundMarginAmount	BigDecimal	Returned margin
status	Integer	Order Status：2 All completed，3 Partially completed，4 Cancelled，8 Execution succeed, 9 Execution failed
canceledVolume	Integer	Cancellation quantity
canceledUserType	Integer	Operator type，0： Not revoked，1：system，2：user
canceledDate	Date	Cancellation time
earningRate	BigDecimal	Earning rate

# Request Example

GET /v1/contract/order/history?symbol=BTC/USDT

# Response Example

{
    "code": "200",
    "message": "OK",
    "timestamp": "1704362423621",
    "data": [
        {
            "symbol": "BTC/USDT",
            "orderId": "644549923592282112",
            "clientOrderId": "OO202401041520",
            "positionType": "SINGLE",
            "positionSide": "LONG",
            "type": "MARKET",
            "side": "BUY",
            "price": "36666.9",
            "volume": 10,
            "triggerPrice": "0",
            "triggerType": 0,
            "dealVolume": 10,
            "leverageLevel": 1,
            "multiplier": "0.0001",
            "avgPrice": "36667",
            "freezeAmount": "36.66910001",
            "feeAmount": "0.00220002",
            "feeRateMaker": 0.0,
            "feeRateTaker": 0.0,
            "realizedAmount": "0",
            "refundMarginAmount": "0",
            "status": 2,
            "canceledVolume": 0,
            "canceledUserType": 0,
            "earningRate": "0"
        },
        {
            "symbol": "BTC/USDT",
            "orderId": "644550281194024961",
            "clientOrderId": "OO202401041530",
            "positionType": "SINGLE",
            "positionSide": "LONG",
            "type": "MARKET",
            "side": "SELL",
            "price": "36681.5",
            "volume": 10,
            "triggerPrice": "0",
            "triggerType": 0,
            "dealVolume": 10,
            "leverageLevel": 1,
            "multiplier": "0.0001",
            "avgPrice": "36681.4",
            "freezeAmount": "0",
            "feeAmount": "0.00220088",
            "feeRateMaker": 0.0,
            "feeRateTaker": 0.0,
            "realizedAmount": "1.13185",
            "refundMarginAmount": "0",
            "status": 2,
            "canceledVolume": 0,
            "canceledUserType": 0,
            "earningRate": "0.0319"
        }
    ]
}

# Query user fee rate

GET /v1/contract/order/fee-rate

Module	Type	Resource Isolation Type	Rate Limit
Contract Order(CONTRACT_ORDER)	Submit(QUERY)	Trading Pair(SYMBOL)	5

# Parameters

Name	Type	Required	Description
symbol	String	Yes	Trading Pair

# Response Parameters

Name	Type	Description
symbol	String	Trading Pair
openTakerFeeRate	BigDecimal	Opening fee rate for taker
openMakerFeeRate	BigDecimal	Opening fee rate for marker
closeTakerFeeRate	BigDecimal	closing fee rate for taker
closeMakerFeeRate	BigDecimal	closing fee rate for takermaker

# Request Example

GET /v1/contract/order/fee-rate?symbol=BTC/USDT

# Response Example

{
    "code": "200",
    "message": "OK",
    "timestamp": "1704336500885",
    "data": [
        {
            "symbol": "BTC/USDT",
            "openTakerFeeRate": "0.0005",
            "openMakerFeeRate": "0.0002",
            "closeTakerFeeRate": "0.0005",
            "closeMakerFeeRate": "0.0002"
        }
    ]
}

← Contract Market Contract Market →