# Bulk Orders

# Overview

Bulk Orders allow traders to atomically apply multiple order instructions in a single command. This means no other matching or exchange operations occur while the instructions are being applied, ensuring consistent state transitions for complex trading strategies.

This feature is particularly useful for market-makers and algorithmic traders who need to update multiple orders simultaneously without the risk of partial state changes.

# Purpose

Bulk orders provide several key advantages:

Atomicity: All instructions are processed as a single unit without interference from other operations
Efficiency: Submit up to 400 instructions in a single API call
Consistency: Predictable execution order matches the submission sequence
Error Handling: Configurable failure behavior for robust trading strategies

# Instruction Limits

A single bulk order request can contain:

Up to 200 new order and amend instructions combined
Up to 200 cancel instructions
Maximum total of 400 instructions per request

# How to Use Bulk Orders

# Endpoint

POST http://user-gateway:8080/Order/BulkOrder

# Request Format

The endpoint accepts a JSON array containing order instructions. Each element can contain either a newOrder, cancelOrder, or amendOrder object.

Instructions are processed in sequence - in the order they appear in the array.

[
  {
    "newOrder": {
      "symbol": "string",
      "side": "string",
      "account": 0,
      "orderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "orderQty": 0,
      "price": 0,
      "displayQty": 0,
      "stopPx": 0,
      "clOrdID": "string",
      "clOrdLinkID": "string",
      "pegOffsetValue": 0,
      "pegPriceType": "string",
      "ordType": "string",
      "timeInForce": "None",
      "expireTime": 0,
      "execInst": "string",
      "contingencyType": "string",
      "text": "string",
      "binaryData": "string",
      "signer": "0xFfa95c49ff77193ACd3E3A483dbf436aff545FcA",
      "nonce": 0
    },
    "cancelOrder": {
      "account": 0,
      "orderID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "clOrdID": "string",
      "text": "string",
      "signer": "0x02AaF2D7d65AAe50e4f8e8fB1F10756ace05CC5D",
      "nonce": 0
    },
    "amendOrder": {
      "account": 0,
      "orderID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "origClOrdID": "string",
      "clOrdID": "string",
      "orderQty": 0,
      "leavesQty": 0,
      "price": 0,
      "stopPx": 0,
      "pegOffsetValue": 0,
      "expireTime": 0,
      "text": "string"
    }
  }
]

# Instruction Types

# New Order

Creates a new order with the specified parameters. Refer to the Order Types documentation for details on order parameters.

Field	Type	Description
`symbol`	String	Instrument symbol (e.g., `BTCUSD`)
`side`	String	Order side (`Buy` or `Sell`)
`account`	Integer	Account number
`orderQty`	Long	Order quantity
`price`	Double	Limit price
`displayQty`	Long	Visible quantity for hidden or iceberg orders
`stopPx`	Double	Stop trigger price
`clOrdID`	String	Client order ID
`clOrdLinkID`	String	Link ID for contingent orders
`ordType`	String	Order type (`Market`, `Limit`, `Stop`, etc.)
`timeInForce`	String	Time in force (`GoodTillCancel`, `ImmediateOrCancel`, etc.)
`expireTime`	Long	Expiration time (epoch milliseconds)
`execInst`	String	Execution instructions
`contingencyType`	String	Contingency type (`OneCancelsTheOther`, `OneTriggersTheOther`)
`text`	String	Optional text annotation

# Cancel Order

Cancels an existing order.

Field	Type	Description
`account`	Integer	Account number (available only on the Control Gateway API)
`orderID`	UUID	Order ID to cancel
`clOrdID`	String	Client order ID
`text`	String	Optional text annotation

# Amend Order

Modifies an existing order's parameters.

Field	Type	Description
`account`	Integer	Account number
`orderID`	UUID	Order ID to amend
`origClOrdID`	String	Original client order ID
`clOrdID`	String	New client order ID
`orderQty`	Long	New order quantity
`leavesQty`	Long	New remaining quantity
`price`	Double	New limit price
`stopPx`	Double	New stop price
`pegOffsetValue`	Double	New peg offset
`expireTime`	Long	New expiration time
`text`	String	Optional text annotation

# Failure Behavior

Bulk orders support two failure behavior modes that determine how the system handles individual instruction failures:

# ContinueOnFailure

When an individual instruction fails, subsequent instructions are still attempted.

# StopOnFailure

When an individual instruction fails, all subsequent instructions are also failed.

# Response Format

The response contains one element for each instruction that was submitted, in the same order as the request.

[
  {
    "items": [
      {
        "orderResponse": {
          "orderID": "string",
          "clOrdID": "string",
          "clOrdLinkID": "string",
          "account": 0,
          "symbol": "string",
          "side": "Buy",
          "orderQty": 0,
          "price": 0,
          "displayQty": 0,
          "stopPx": 0,
          "pegOffsetValue": 0,
          "pegOffsetType": "MarketPeg",
          "currency": "string",
          "settlCurrency": "string",
          "ordType": "Market",
          "timeInForce": "Day",
          "execInst": "string",
          "contingencyType": "OneCancelsTheOther",
          "ordStatus": "PartiallyFilled",
          "triggered": "NotTriggered",
          "workingIndicator": true,
          "ordRejReason": "CausesImmediateLiquidation",
          "leavesQty": 0,
          "cumQty": 0,
          "avgPx": 0,
          "text": "string",
          "transactTime": "2025-11-20T08:05:10.519Z",
          "timestamp": "2025-11-20T08:05:10.519Z",
          "orderCancelError": "NotFound",
          "updateTime": 0,
          "expireTime": 0
        },
        "newOrderFailure": "None",
        "amendFailure": "None",
        "cancellationFailure": "None"
      }
    ]
  }
]

# Response Fields

# Order Response

The orderResponse object contains details about the processed order:

Field	Type	Description
`orderID`	UUID	System-generated order ID
`clOrdID`	String	Client order ID
`clOrdLinkID`	String	Contingent order link ID
`account`	Integer	Account number
`symbol`	String	Instrument symbol
`side`	String	Order side (`Buy` or `Sell`)
`orderQty`	Long	Order quantity
`price`	Double	Limit price
`displayQty`	Long	Display quantity
`stopPx`	Double	Stop price
`ordType`	String	Order type
`timeInForce`	String	Time in force
`ordStatus`	String	Order status (`New`, `PartiallyFilled`, `Filled`, `Canceled`, etc.)
`ordRejReason`	String	Rejection reason if order was rejected
`leavesQty`	Long	Remaining quantity
`cumQty`	Long	Cumulative filled quantity
`avgPx`	Double	Average fill price
`transactTime`	DateTime	Transaction timestamp
`timestamp`	DateTime	Response timestamp
`orderCancelError`	String	Cancel error if applicable

# Failure Indicators

Each response item includes failure indicators for each instruction type:

Field	Description
`newOrderFailure`	Failure reason for new order instruction (`None` if successful)
`amendFailure`	Failure reason for amend instruction (`None` if successful)
`cancellationFailure`	Failure reason for cancel instruction (`None` if successful)