# 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.

```json
[
  {
    "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](order_examples.md) 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.

```json
[
  {
    "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) |