Batch order management

POST 
/v3/batchorder

This endpoint allows sending limit or stop order(s) and/or cancelling open order(s) and/or editing open order(s) for a currently listed Futures contract in batch.

When editing an order, if the trailingStopMaxDeviation and trailingStopDeviationUnit parameters are sent unchanged, the system will recalculate a new stop price upon successful order modification.

Request

application/x-www-form-urlencoded

Body

required

processBefore string

The time before which the request should be processed, otherwise it is rejected.

json stringrequired
info
This parameter is required to be encoded as a json string, please see example.
batchOrder object[]required
A list containing structures of order sending and order cancellation instructions. The list is in no particular order.
Array [
oneOf
BatchOrderSend
order string
Possible values: [send]
Always send.
order_tag stringrequired
An arbitrary string provided client-side to tag the order for the purpose of mapping order sending instructions to the API's response.
orderType stringrequired
Possible values: [lmt, ioc, post, stp, take_profit]
Order type:
• lmt - a limit order,
• post - a post-only limit order,
• take_profit - a take profit order or
• stp - a stop order
• trailing_stop - a trailing stop order
symbol stringrequired
The symbol of the Futures.
side stringrequired
Possible values: [buy, sell]
The direction of the order.
size numberrequired
The size associated with the order.
limitPrice number
The limit price associated with the order. If placing a trailing_stop order then leave undefined.
stopPrice number
The stop price associated with a stop order. Required if orderType is stp. Note that for stp orders, limitPrice is also required and denotes the worst price at which the stp order can get filled
cliOrdId string
Possible values: <= 100 characters
The order identity that is specified from the user. It must be globally unique.
triggerSignal string
Possible values: [mark, spot, last]
reduceOnly boolean
Set as 'true' if you wish the order to only reduce an existing position. Any order which increases an existing position will be rejected. Default 'false'.
trailingStopMaxDeviation number
Required if the order type is trailing_stop.
Is the maximum distance the trailing stop's trigger price may trail behind the requested trigger signal. It defines the threshold at which the trigger price updates.
trailingStopDeviationUnit string
Possible values: [PERCENT, QUOTE_CURRENCY]
Required if the order type is trailing_stop.
This defines how the trailing trigger price is calculated from the requested trigger signal. For example, if the max deviation is set to 10, the unit is 'PERCENT', and the underlying order is a sell, then the trigger price will never be more then 10% below the trigger signal. Similarly, if the deviation is 100, the unit is 'QUOTE_CURRENCY', the underlying order is a sell, and the contract is quoted in USD, then the trigger price will never be more than $100 below the trigger signal.
BatchOrderEdit
cliOrdId stringnull
Possible values: <= 100 characters
Unique client order identifier.
order_id uuid
Order ID.
order string
Possible values: [edit]
Always edit.
size number
The size associated with the order.
limitPrice number
The limit price associated with the order.
stopPrice number
The stop price associated with a stop order. Required if old orderType is stp.
Note that for stp orders, limitPrice is also required and denotes the worst price at which the stp order can get filled.
trailingStopMaxDeviation number
Possible values: >= 0.1 and <= 50
Only relevant for trailing stop orders. Maximum value of 50%, minimum value of 0.1% for 'PERCENT' 'maxDeviationUnit'.
Is the maximum distance the trailing stop's trigger price may trail behind the requested trigger signal. It defines the threshold at which the trigger price updates.
trailingStopDeviationUnit string
Possible values: [PERCENT, QUOTE_CURRENCY]
Only relevant for trailing stop orders.
This defines how the trailing trigger price is calculated from the requested trigger signal. For example, if the max deviation is set to 10, the unit is 'PERCENT', and the underlying order is a sell, then the trigger price will never be more then 10% below the trigger signal. Similarly, if the deviation is 100, the unit is 'QUOTE_CURRENCY', the underlying order is a sell, and the contract is quoted in USD, then the trigger price will never be more than $100 below the trigger signal.
BatchOrderCancel
cliOrdId stringnull
Possible values: <= 100 characters
Unique client order identifier.
order_id uuid
Order ID.
order string
Possible values: [cancel]
Always cancel.
]

Responses

200

application/json

Schema

Schema

oneOf
Success Response
serverTime string
Server time in Coordinated Universal Time (UTC)
result string
Possible values: [success]
batchStatus object[]required
A structure containing information on the send order request.
Array [
cliOrdId string
The unique client order identifier. This field is returned only if the order has a client order ID.
dateTimeReceived stringnull
The date and time the order was received.
orderEvents object[]
Array [
oneOf
PlaceEvent
type ApiOrderEventType (string)
Possible values: [place, cancel, edit, reject, execution]
Always place.
order object
The placed order.
orderId string
The UID associated with the order.
cliOrdId stringnull
The client order id or null if order does not have one.
type string
Possible values: [lmt, ioc, post, liquidation, assignment, stp, unwind, block]
The order type
symbol string
The symbol of the Futures.
side string
Possible values: [buy, sell]
The side associated with the order
quantity number
The quantity (size) associated with the order.
filled number
The total amount of the order that has been filled.
limitPrice number
The limit price associated with a limit order.
reduceOnly boolean
Is the order a reduce only order or not.
timestamp string
The date and time the order was placed.
lastUpdateTimestamp string
The date and time the order was edited.
reducedQuantity numbernull
The amount of quantity that was removed before placement or null if the order is not a reduce only.
CancelEvent
type ApiOrderEventType (string)
Possible values: [place, cancel, edit, reject, execution]
Always cancel.
uid string
The uid associated with the order.
order object
oneOf
OrderJson
orderId string
The UID associated with the order.
cliOrdId stringnull
The client order id or null if order does not have one.
type string
Possible values: [lmt, ioc, post, liquidation, assignment, stp, unwind, block]
The order type
symbol string
The symbol of the Futures.
side string
Possible values: [buy, sell]
The side associated with the order
quantity number
The quantity (size) associated with the order.
filled number
The total amount of the order that has been filled.
limitPrice number
The limit price associated with a limit order.
reduceOnly boolean
Is the order a reduce only order or not.
timestamp string
The date and time the order was placed.
lastUpdateTimestamp string
The date and time the order was edited.
EditEvent
type ApiOrderEventType (string)
Possible values: [place, cancel, edit, reject, execution]
Always edit.
old object
The order before the edit was applied.
orderId string
The UID associated with the order.
cliOrdId stringnull
The client order id or null if order does not have one.
type string
Possible values: [lmt, ioc, post, liquidation, assignment, stp, unwind, block]
The order type
symbol string
The symbol of the Futures.
side string
Possible values: [buy, sell]
The side associated with the order
quantity number
The quantity (size) associated with the order.
filled number
The total amount of the order that has been filled.
limitPrice number
The limit price associated with a limit order.
reduceOnly boolean
Is the order a reduce only order or not.
timestamp string
The date and time the order was placed.
lastUpdateTimestamp string
The date and time the order was edited.
new object
The order after the edit was applied.
orderId string
The UID associated with the order.
cliOrdId stringnull
The client order id or null if order does not have one.
type string
Possible values: [lmt, ioc, post, liquidation, assignment, stp, unwind, block]
The order type
symbol string
The symbol of the Futures.
side string
Possible values: [buy, sell]
The side associated with the order
quantity number
The quantity (size) associated with the order.
filled number
The total amount of the order that has been filled.
limitPrice number
The limit price associated with a limit order.
reduceOnly boolean
Is the order a reduce only order or not.
timestamp string
The date and time the order was placed.
lastUpdateTimestamp string
The date and time the order was edited.
reducedQuantity numbernull
The amount of quantity that was removed from the edited order or null if the order is not a reduce only.
RejectEvent
type ApiOrderEventType (string)
Possible values: [place, cancel, edit, reject, execution]
Always reject.
uid string
The UID associated with the order.
order object
oneOf
OrderJson
orderId string
The UID associated with the order.
cliOrdId stringnull
The client order id or null if order does not have one.
type string
Possible values: [lmt, ioc, post, liquidation, assignment, stp, unwind, block]
The order type
symbol string
The symbol of the Futures.
side string
Possible values: [buy, sell]
The side associated with the order
quantity number
The quantity (size) associated with the order.
filled number
The total amount of the order that has been filled.
limitPrice number
The limit price associated with a limit order.
reduceOnly boolean
Is the order a reduce only order or not.
timestamp string
The date and time the order was placed.
lastUpdateTimestamp string
The date and time the order was edited.
reason string
Possible values: [postWouldExecute, iocWouldNotExecute, wouldNotReducePosition, orderForEditNotFound]
The rejection reason:
• postWouldExecute - The post-only order would be filled upon placement, thus is cancelled.
• iocWouldNotExecute - The immediate-or-cancel order would not execute.
• wouldNotReducePosition - The reduce only order would not reduce position.
• orderForEditNotFound - The order for edit was not found. The order field will be null in this case.
ExecuteEvent
type ApiOrderEventType (string)
Possible values: [place, cancel, edit, reject, execution]
Always execution.
executionId string
The UID associated with the execution.
price number
The price of the execution.
amount number
The executed amount.
orderPriorEdit object
oneOf
OrderJson
orderId string
The UID associated with the order.
cliOrdId stringnull
The client order id or null if order does not have one.
type string
Possible values: [lmt, ioc, post, liquidation, assignment, stp, unwind, block]
The order type
symbol string
The symbol of the Futures.
side string
Possible values: [buy, sell]
The side associated with the order
quantity number
The quantity (size) associated with the order.
filled number
The total amount of the order that has been filled.
limitPrice number
The limit price associated with a limit order.
reduceOnly boolean
Is the order a reduce only order or not.
timestamp string
The date and time the order was placed.
lastUpdateTimestamp string
The date and time the order was edited.
orderPriorExecution object
The order before it executes.
orderId string
The UID associated with the order.
cliOrdId stringnull
The client order id or null if order does not have one.
type string
Possible values: [lmt, ioc, post, liquidation, assignment, stp, unwind, block]
The order type
symbol string
The symbol of the Futures.
side string
Possible values: [buy, sell]
The side associated with the order
quantity number
The quantity (size) associated with the order.
filled number
The total amount of the order that has been filled.
limitPrice number
The limit price associated with a limit order.
reduceOnly boolean
Is the order a reduce only order or not.
timestamp string
The date and time the order was placed.
lastUpdateTimestamp string
The date and time the order was edited.
takerReducedQuantity numbernull
The amount of quantity that was removed from the order before execution or null if the order is not a reduce only.
PlaceTriggerEvent
type ApiOrderEventType (string)
Possible values: [place, cancel, edit, reject, execution]
Always place.
orderTrigger object
uid string
The UID associated with the order.
clientId stringnull
The client order id or null if order does not have one.
type string
Possible values: [lmt, ioc, post, liquidation, assignment, stp, unwind]
The order type
symbol string
The symbol of the Futures.
side string
Possible values: [buy, sell]
The side associated with the order
quantity numbernull
The quantity (size) associated with the order.
limitPrice numbernull
The limit price associated with a limit order.
triggerPrice numbernull
triggerSide stringnull
Possible values: [trigger_above, trigger_below]
triggerSignal stringnull
Possible values: [mark_price, last_price, spot_price]
reduceOnly boolean
Is the order a reduce only order or not.
timestamp string
The date and time the order was placed.
lastUpdateTimestamp string
The date and time the order was edited.
startTime stringnull
CancelTriggerEvent
type ApiOrderEventType (string)
Possible values: [place, cancel, edit, reject, execution]
Always cancel.
uid string
orderTrigger object
oneOf
OrderTriggerJson
uid string
The UID associated with the order.
clientId stringnull
The client order id or null if order does not have one.
type string
Possible values: [lmt, ioc, post, liquidation, assignment, stp, unwind]
The order type
symbol string
The symbol of the Futures.
side string
Possible values: [buy, sell]
The side associated with the order
quantity numbernull
The quantity (size) associated with the order.
limitPrice numbernull
The limit price associated with a limit order.
triggerPrice numbernull
triggerSide stringnull
Possible values: [trigger_above, trigger_below]
triggerSignal stringnull
Possible values: [mark_price, last_price, spot_price]
reduceOnly boolean
Is the order a reduce only order or not.
timestamp string
The date and time the order was placed.
lastUpdateTimestamp string
The date and time the order was edited.
startTime stringnull
RejectTriggerEvent
type ApiOrderEventType (string)
Possible values: [place, cancel, edit, reject, execution]
Always reject.
uid string
orderTrigger object
oneOf
OrderTriggerJson
uid string
The UID associated with the order.
clientId stringnull
The client order id or null if order does not have one.
type string
Possible values: [lmt, ioc, post, liquidation, assignment, stp, unwind]
The order type
symbol string
The symbol of the Futures.
side string
Possible values: [buy, sell]
The side associated with the order
quantity numbernull
The quantity (size) associated with the order.
limitPrice numbernull
The limit price associated with a limit order.
triggerPrice numbernull
triggerSide stringnull
Possible values: [trigger_above, trigger_below]
triggerSignal stringnull
Possible values: [mark_price, last_price, spot_price]
reduceOnly boolean
Is the order a reduce only order or not.
timestamp string
The date and time the order was placed.
lastUpdateTimestamp string
The date and time the order was edited.
startTime stringnull
reason OrderError (string)
Possible values: [MARKET_SUSPENDED, MARKET_NOT_FOUND, INVALID_PRICE, INVALID_QUANTITY, SMALL_ORDER_LIMIT_EXCEEDED, INSUFFICIENT_MARGIN, WOULD_CAUSE_LIQUIDATION, CLIENT_ORDER_ID_IN_USE, CLIENT_ORDER_ID_TOO_LONG, MAX_POSITION_EXCEEDED, PRICE_COLLAR, PRICE_DISLOCATION, EDIT_HAS_NO_EFFECT, ORDER_FOR_CANCELLATION_NOT_FOUND, ORDER_FOR_EDIT_NOT_FOUND, ORDER_CANNOT_HAVE_TRIGGER_PRICE, POST_WOULD_EXECUTE, IOC_WOULD_NOT_EXECUTE, WOULD_EXECUTE_SELF, WOULD_NOT_REDUCE_POSITION, REJECTED_AFTER_EXECUTION, MARKET_IS_POST_ONLY, ORDER_LIMIT_EXCEEDED, FIXED_LEVERAGE_TOO_HIGH, CANNOT_EDIT_TRIGGER_PRICE_OF_TRAILING_STOP, CANNOT_EDIT_LIMIT_PRICE_OF_TRAILING_STOP, TRAILING_STOP_ORDER_LIMIT_EXCEEDED, TRAILING_STOP_PERCENT_DEVIATION_EXCEEDS_MAX_DECIMAL_PLACES, TRAILING_STOP_QUOTE_DEVIATION_NOT_MULTIPLE_OF_TICK_SIZE, TRAILING_STOP_MAX_DEVIATION_TOO_LARGE, TRAILING_STOP_MAX_DEVIATION_TOO_SMALL, INSUFFICIENT_HEADROOM_AROUND_CURRENT_PRICE_TO_EDIT_TRAILING_STOP, NO_REFERENCE_PRICE_AVAILABLE_FOR_CALCULATING_TRAILING_STOP_TRIGGER_PRICE, INSUFFICIENT_CLOSING_MARGIN, LIMIT_PRICE_SET_AS_ABSOLUTE_AND_RELATIVE, LIMIT_PRICE_OFFSET_VALUE_INVALID, LIMIT_PRICE_OFFSET_UNIT_INVALID, LIMIT_PRICE_OFFSET_MUST_HAVE_VALUE_AND_UNIT, LIMIT_PRICE_OFFSET_QUOTE_CURRENCY_VALUE_MUST_BE_MULTIPLE_OF_TICK_SIZE, LIMIT_PRICE_OFFSET_PERCENT_VALUE_TOO_MANY_DECIMAL_PLACES, LIMIT_PRICE_OFFSET_TOO_HIGH, LIMIT_PRICE_OFFSET_TOO_LOW]
]
order_id stringnull
The unique identifier of the order.
order_tag stringnull
The arbitrary string provided client-side when the order was sent for the purpose of mapping order sending instructions to the API's response.
status string
Possible values: [placed, cancelled, invalidOrderType, invalidSide, invalidSize, invalidPrice, insufficientAvailableFunds, selfFill, tooManySmallOrders, marketSuspended, marketInactive, clientOrderIdAlreadyExist, clientOrderIdTooLong, outsidePriceCollar, postWouldExecute, iocWouldNotExecute]
The status of the order:
• placed - the order was placed successfully
• cancelled - the order was cancelled successfully
• invalidOrderType - the order was not placed because orderType is invalid
• invalidSide - the order was not placed because side is invalid
• invalidSize - the order was not placed because size is invalid
• invalidPrice - the order was not placed because limitPrice and/or stopPrice are invalid
• insufficientAvailableFunds - the order was not placed because available funds are insufficient
• selfFill - the order was not placed because it would be filled against an existing order belonging to the same account
• tooManySmallOrders - the order was not placed because the number of small open orders would exceed the permissible limit
• marketSuspended - the order was not placed because the market is suspended
• marketInactive - the order was not placed because the market is inactive
• clientOrderIdAlreadyExist - the specified client ID already exist
• clientOrderIdTooLong - the client ID is longer than the permissible limit
• outsidePriceCollar - the limit order crosses the spread but is an order of magnitude away from the mark price - fat finger control
• postWouldExecute - the post-only order would be filled upon placement, thus is cancelled
• iocWouldNotExecute - the immediate-or-cancel order would not execute
]
ErrorResponse
serverTime string
Server time in Coordinated Universal Time (UTC)
result string
Possible values: [error]
errors Error (string)[]
Possible values: [accountInactive, apiLimitExceeded, authenticationError, insufficientFunds, invalidAccount, invalidAmount, invalidArgument, invalidUnit, Json Parse Error, marketUnavailable, nonceBelowThreshold, nonceDuplicate, notFound, requiredArgumentMissing, Server Error, Unavailable, unknownError]
error Error (string)
Possible values: [accountInactive, apiLimitExceeded, authenticationError, insufficientFunds, invalidAccount, invalidAmount, invalidArgument, invalidUnit, Json Parse Error, marketUnavailable, nonceBelowThreshold, nonceDuplicate, notFound, requiredArgumentMissing, Server Error, Unavailable, unknownError]
Error description.
• accountInactive: The Futures account the request refers to is inactive
• apiLimitExceeded: The API limit for the calling IP address has been exceeded
• authenticationError: The request could not be authenticated
• insufficientFunds: The amount requested for transfer is below the amount of funds available
• invalidAccount: The Futures account the transfer request refers to is invalid
• invalidAmount: The amount the transfer request refers to is invalid
• invalidArgument: One or more arguments provided are invalid
• invalidUnit: The unit the transfer request refers to is invalid
• Json Parse Error: The request failed to pass valid JSON as an argument
• marketUnavailable: The market is currently unavailable
• nonceBelowThreshold: The provided nonce is below the threshold
• nonceDuplicate: The provided nonce is a duplicate as it has been used in a previous request
• notFound: The requested information could not be found
• requiredArgumentMissing: One or more required arguments are missing
• Server Error: There was an error processing the request
• Unavailable: The endpoint being called is unavailable
• unknownError: An unknown error has occurred

success

{
  "result": "success",
  "serverTime": "2019-09-05T16:41:40.996Z",
  "batchStatus": [
    {
      "status": "placed",
      "order_tag": "1",
      "order_id": "022774bc-2c4a-4f26-9317-436c8d85746d",
      "dateTimeReceived": "2019-09-05T16:41:35.173Z",
      "orderEvents": [
        {
          "order": {
            "orderId": "022774bc-2c4a-4f26-9317-436c8d85746d",
            "cliOrdId": null,
            "type": "lmt",
            "symbol": "PI_XBTUSD",
            "side": "buy",
            "quantity": 1000,
            "filled": 0,
            "limitPrice": 9400,
            "reduceOnly": false,
            "timestamp": "2019-09-05T16:41:35.173Z",
            "lastUpdateTimestamp": "2019-09-05T16:41:35.173Z"
          },
          "reducedQuantity": null,
          "type": "PLACE"
        }
      ]
    },
    {
      "status": "edited",
      "order_id": "9c2cbcc8-14f6-42fe-a020-6e395babafd1",
      "orderEvents": [
        {
          "old": {
            "orderId": "9c2cbcc8-14f6-42fe-a020-6e395babafd1",
            "cliOrdId": null,
            "type": "lmt",
            "symbol": "PI_XBTUSD",
            "side": "buy",
            "quantity": 102,
            "filled": 0,
            "limitPrice": 8500,
            "reduceOnly": false,
            "timestamp": "2019-09-04T11:45:48.884Z",
            "lastUpdateTimestamp": "2019-09-04T11:45:48.884Z"
          },
          "new": {
            "orderId": "9c2cbcc8-14f6-42fe-a020-6e395babafd1",
            "cliOrdId": null,
            "type": "lmt",
            "symbol": "PI_XBTUSD",
            "side": "buy",
            "quantity": 1000,
            "filled": 0,
            "limitPrice": 9400,
            "reduceOnly": false,
            "timestamp": "2019-09-04T11:45:48.884Z",
            "lastUpdateTimestamp": "2019-09-05T16:41:40.996Z"
          },
          "reducedQuantity": null,
          "type": "EDIT"
        }
      ]
    },
    {
      "status": "cancelled",
      "order_id": "566942c8-a3b5-4184-a451-622b09493129",
      "orderEvents": [
        {
          "uid": "566942c8-a3b5-4184-a451-622b09493129",
          "order": {
            "orderId": "566942c8-a3b5-4184-a451-622b09493129",
            "cliOrdId": null,
            "type": "lmt",
            "symbol": "PI_XBTUSD",
            "side": "buy",
            "quantity": 100,
            "filled": 0,
            "limitPrice": 8500,
            "reduceOnly": false,
            "timestamp": "2019-09-02T12:54:08.005Z",
            "lastUpdateTimestamp": "2019-09-02T12:54:08.005Z"
          },
          "type": "CANCEL"
        }
      ]
    }
  ]
}

Loading...