# Multi Order

## Get Multi Order

<mark style="color:blue;">GET</mark> `/api/multi_order/{id}`

Get detailed information about a specific multi-order including its child orders, execution status, and key parameters. This endpoint provides comprehensive information about the multi-order structure and its current state.

**Path Parameters**

| Name | Type   | Description                        |
| ---- | ------ | ---------------------------------- |
| `id` | string | UUID of multi order. **Required.** |

**Query Parameters**

| Name                   | Type    |                                                                    |
| ---------------------- | ------- | ------------------------------------------------------------------ |
| `include_child_orders` | boolean | Include full child order details in the response (default: false). |

**Example Request**

```
GET /api/multi_order/6debb950-614a-4366-b73b-7d7574fd9e15?include_child_orders=true
Authorization: Bearer <token>
```

**Response Codes**

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "id": "397e42c1-a617-458b-9db9-dc51f326b918",
    "created_at": "2025-01-13T20:33:22.331268Z",
    "updated_at": "2025-01-13T20:33:22.331288Z",
    "start_datetime": "2025-01-13T20:33:22.323949Z",
    "duration": 600,
    "exposure_tolerance": "0.50000000000000000000",
    "notional_exposure": 34.554926518,
    "executed_notional": 93712.607473482,
    "is_active": false,
    "child_order_ids": [
        "5ee11fdd-334d-418a-b138-7df74f17e417",
        "54509111-7204-4626-8513-d7f040f76bf3"
    ],
    "strategy": "ccb82677-249d-4b01-8f60-7a02379e963a",
    "strategy_params": {},
    "engine_passiveness": "0.02000000000000000000",
    "schedule_discretion": "0.06000000000000000000",
    "alpha_tilt": "0.00000000000000000000",
    "pov_limit": null,
    "limit_price_spread": null,
    "order_condition": "ETH-USDT@Binance ETH:PERP-USDT@Binance - 1 >",
    "order_condition_vars": {},
    "order_condition_expiry": null,
    "user": "13",
    "status": "SCHEDULED",
    "failure_reason": "",
    "completely_filled": true,
    "is_paused": false,
    "pct_filled": 100.0,
    "account_names": [
        "mock"
    ],
    "pairs": "BTC-USDT,BTC:PERP-USDT",
    "calculated_status": "COMPLETE",
    "sell_token_amount": "0.50000000000000000000, 46871.66540000000000000000",
    "buy_token": "USDT, BTC:PERP",
    "sell_token": "BTC, USDT"
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```json
{
    "error": "unable to get multi order"
}
```

{% endtab %}

{% tab title="404: Notfound" %}

```
{
    "error": "multi order not found"
}
```

{% endtab %}
{% endtabs %}

## Get Multi Orders

<mark style="color:blue;">GET</mark> `/api/multi_orders/`

Paginated multi orders fetched given the filter options

**Query Parameters**

| Name                   | Type    |                                                                                                                                                               |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `include_child_orders` | boolean | Include full child order details in the response (default: false).                                                                                            |
| `custom_order_ids`     | string  | comma separated list of values                                                                                                                                |
| `statuses`             | string  | comma separated list of order statuses[#multiorderstatus-enum](https://docs.tread.fi/interacting-with-the-api/type-reference#multiorderstatus-enum "mention") |
| `before`               | string  | iso format datetime ex. 2025-08-11T12:00:00                                                                                                                   |
| `after`                | string  | iso format datetime ex. 2025-08-11T12:00:00                                                                                                                   |
| `page_number`          | integer | default: 1                                                                                                                                                    |
| `page_size`            | integer | default: 100                                                                                                                                                  |

**Example Request**

```
GET /api/multi_order/6debb950-614a-4366-b73b-7d7574fd9e15?include_child_orders=true
Authorization: Bearer <token>
```

**Response Codes**

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "multi_orders": [
    {
      "id": "6debb950-614a-4366-b73b-7d7574fd9e15",
      "created_at": "2023-12-01T10:00:00Z",
      "updated_at": "2023-12-01T10:30:00Z",
      "start_timedate": "2023-12-01T10:00:00Z",
      "duration": 3600,
      "exposure_tolerance": "0.05",
      "notional_exposure": "22500.00",
      "executed_notional": "22500.00",
      "child_order_ids": [
        "7fecb951-725b-5477-c84c-8e8685ge0f26",
        "8gfdca62-836c-6588-d95d-9f9796hf1g37"
      ],
      "accounts": ["binance_main", "coinbase_pro"],
      "strategy": "TWAP",
      "strategy_params": {
        "interval": 300,
        "slices": 12
      },
      "engine_passiveness": "0.5",
      "schedule_discretion": "0.3",
      "alpha_tilt": "0.1",
      "limit_price_spread": null,
      "failure_reason": null,
      "pct_filled": "100.00",
      "account_names": ["binance_main", "coinbase_pro"],
      "pairs": "BTC-USD,ETH-USD",
      "status": "COMPLETED",
      "is_active": false,
      "is_paused": false,
      "fee_notional": "22.50",
      "order_condition": "",
      "custom_order_id": "multi_order_123",
      "child_orders": [
        {
          "id": "7fecb951-725b-5477-c84c-8e8685ge0f26",
          "custom_order_id": "child_order_1",
          "parent_order_id": "6debb950-614a-4366-b73b-7d7574fd9e15",
          "notes": "",
          "pair": "BTC-USD",
          "side": "buy",
          "exchanges": ["binance"],
          "buy_token": "BTC",
          "buy_token_amount": "0.25",
          "sell_token": "USD",
          "sell_token_amount": "11250.00",
          "strategy": "TWAP",
          "strategy_params": {
            "interval": 300,
            "slices": 6
          },
          "status": "COMPLETED",
          "executed_notional": "11250.00",
          "pct_filled": "100.00",
          "created_at": "2023-12-01T10:00:00Z",
          "updated_at": "2023-12-01T10:30:00Z",
          "time_start": "2023-12-01T10:00:00Z",
          "duration": 1800,
          "limit_price": "45000.00",
          "engine_passiveness": "0.5",
          "schedule_discretion": "0.3",
          "alpha_tilt": "0.1",
          "is_active": false,
          "is_paused": false,
          "failure_reason": null,
          "fee": "11.25",
          "fills": [
            {
              "id": "fill_001",
              "timestamp": "2023-12-01T10:05:00Z",
              "quantity": "0.04166667",
              "price": "45000.00",
              "notional": "1875.00",
              "venue": "binance",
              "fee": "1.875"
            }
          ]
        }
      ]
    }
  ],
  "page_number": 1,
  "page_size": 100,
  "num_pages": 2,
  "multi_order_count": 144
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```json
{
    "errors": ["<field_name> is invalid"]
}
```

{% endtab %}
{% endtabs %}

## Submit Multi Order

<mark style="color:green;">`POST`</mark> `/api/multi_orders/`&#x20;

Submit a multi-order containing multiple child orders for scheduling and execution. This endpoint allows you to create a group of related orders that share common parameters while allowing individual customization for each child order.

**Request Body**

<table><thead><tr><th>Name</th><th>Type</th><th>Required<select><option value="BwDrg5Fsd3xb" label="Yes" color="blue"></option><option value="qafzwkzoVOe9" label="No" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><code>accounts</code></td><td>array[string]</td><td><span data-option="BwDrg5Fsd3xb">Yes</span></td><td>List of account names to use for the multi-order</td></tr><tr><td><code>duration</code></td><td>integer</td><td><span data-option="BwDrg5Fsd3xb">Yes</span></td><td>Duration of the multi-order in seconds</td></tr><tr><td><code>strategy</code></td><td>string</td><td><span data-option="BwDrg5Fsd3xb">Yes</span></td><td>Strategy name to use for execution.  Ex. VWAP</td></tr><tr><td><code>engine_passiveness</code></td><td>decimal</td><td><span data-option="BwDrg5Fsd3xb">Yes</span></td><td>Engine passiveness value (0.0 to 1.0)</td></tr><tr><td><code>schedule_discretion</code></td><td>decimal</td><td><span data-option="BwDrg5Fsd3xb">Yes</span></td><td>Schedule discretion value (0.0 to 1.0)</td></tr><tr><td><code>child_orders</code></td><td>array[object]</td><td><span data-option="BwDrg5Fsd3xb">Yes</span></td><td>Array of child order objects</td></tr><tr><td><code>strategy_params</code></td><td>object</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>Strategy-specific parameters</td></tr><tr><td><code>alpha_tilt</code></td><td>decimal</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>Alpha tilt value for order execution</td></tr><tr><td><code>exposure_tolerance</code></td><td>decimal</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>Exposure tolerance for the multi-order</td></tr><tr><td><code>limit_price_spread</code></td><td>decimal</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>Dynamic limit price spread for spread trades</td></tr><tr><td><code>order_condition</code></td><td>string</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>Conditional order expression</td></tr><tr><td><code>start_timedate</code></td><td>string</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>ISO 8601 timestamp for order start (defaults to now)</td></tr><tr><td><code>custom_order_id</code></td><td>string</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>Custom identifier for the multi-order</td></tr><tr><td><code>notes</code></td><td>string</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>Additional notes for the multi-order</td></tr></tbody></table>

### Child Order Object

<table><thead><tr><th>Name</th><th>Type</th><th>Required<select><option value="wsO8iQjmz9aI" label="Yes" color="blue"></option><option value="K3QTZ5iCzExW" label="No" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><code>pair</code></td><td>string</td><td><span data-option="wsO8iQjmz9aI">Yes</span></td><td>Trading pair symbol</td></tr><tr><td><code>side</code></td><td>string</td><td><span data-option="wsO8iQjmz9aI">Yes</span></td><td>Order side: buy or sell</td></tr><tr><td><code>base_asset_qty</code></td><td>decimal</td><td><span data-option="wsO8iQjmz9aI">Yes</span></td><td>Base asset quantity</td></tr><tr><td><code>accounts</code></td><td>array[string]</td><td><span data-option="K3QTZ5iCzExW">No</span></td><td>Specific accounts for this child order (overrides parent accounts)</td></tr><tr><td><code>quote_asset_qty</code></td><td>decimal</td><td><span data-option="K3QTZ5iCzExW">No</span></td><td>Quote asset quantity (alternative to <code>base_asset_qty</code>)</td></tr><tr><td><code>notes</code></td><td>string</td><td><span data-option="K3QTZ5iCzExW">No</span></td><td>Notes specific to this child order</td></tr><tr><td><code>alpha_tilt</code></td><td>decimal</td><td><span data-option="K3QTZ5iCzExW">No</span></td><td>Alpha tilt specific to this child order</td></tr><tr><td><code>pos_side</code></td><td>string</td><td><span data-option="K3QTZ5iCzExW">No</span></td><td>Position side: long or short.  Required if exchange account is configured to be in Hedge Mode.</td></tr></tbody></table>

#### Example Request

```
POST /api/multi_orders/
Authorization: Bearer <token>
Content-Type: application/json

{
  "accounts": ["binance_main"],
  "duration": 3600,
  "strategy": "TWAP",
  "engine_passiveness": 0.5,
  "schedule_discretion": 0.3,
  "alpha_tilt": 0.1,
  "exposure_tolerance": 0.05,
  "custom_order_id": "multi_order_123",
  "notes": "for xyz",
  "child_orders": [
    {
      "pair": "BTC:PERP-USDT",
      "side": "buy",
      "quote_asset_qty": 100000,
    },
    {
      "pair": "ETH:PERP-USDT",
      "side": "sell",
      "quote_asset_qty": 100000,
    }
  ]
}
```

**Response**

{% tabs %}
{% tab title="201: Created" %}

```json
{
    "id": "397e42c1-a617-458b-9db9-dc51f326b918",
    "created_at": "2025-01-13T20:33:22.331268Z",
    "updated_at": "2025-01-13T20:33:22.331288Z",
    "start_datetime": "2025-01-13T20:33:22.323949Z",
    "duration": 600,
    "exposure_tolerance": "0.50000000000000000000",
    "notional_exposure": 34.554926518,
    "executed_notional": 93712.607473482,
    "is_active": false,
    "child_order_ids": [
        "5ee11fdd-334d-418a-b138-7df74f17e417",
        "54509111-7204-4626-8513-d7f040f76bf3"
    ],
    "strategy": "ccb82677-249d-4b01-8f60-7a02379e963a",
    "strategy_params": {},
    "engine_passiveness": "0.02000000000000000000",
    "schedule_discretion": "0.06000000000000000000",
    "alpha_tilt": "0.00000000000000000000",
    "pov_limit": null,
    "limit_price_spread": null,
    "order_condition": "ETH-USDT@Binance ETH:PERP-USDT@Binance - 1 >",
    "order_condition_vars": {},
    "order_condition_expiry": null,
    "user": "13",
    "status": "SCHEDULED",
    "failure_reason": "",
    "completely_filled": true,
    "is_paused": false,
    "pct_filled": 100.0,
    "account_names": [
        "mock"
    ],
    "pairs": "BTC-USDT,BTC:PERP-USDT",
    "calculated_status": "COMPLETE",
    "sell_token_amount": "0.50000000000000000000, 46871.66540000000000000000",
    "buy_token": "USDT, BTC:PERP",
    "sell_token": "BTC, USDT"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity" %}

```
{
  "errors": [
    "Need at least one top level account or individual child order accounts",
    "Cannot have more than one of the qty fields: ['base_asset_qty', 'quote_asset_qty', 'sell_token_amount']"
  ]
}
```

{% endtab %}
{% endtabs %}

## Cancel Multi Orders

<mark style="color:green;">`POST`</mark> `/api/cancel_multi_orders/`

Cancel multi orders identified by the provided list of order IDs or custom order IDs, canceling all child orders and their active placements.  Must provide either `order_ids` or `custom_order_ids`.

**Request Body**

| Name               | Type           | Description                              |
| ------------------ | -------------- | ---------------------------------------- |
| `order_ids`        | array\[string] | list of multi order UUIDs                |
| `custom_order_ids` | array\[string] | array of user specified custom order IDs |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "message": "Multi orders canceled!"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "errors": ["Missing required field: order_ids or custom_order_ids"]
}
```

{% endtab %}

{% tab title="422" %}

```json
{
  "errors": ["Unexpected failure while cancelling order"]
}
```

{% endtab %}
{% endtabs %}

## Pause Multi Order

<mark style="color:green;">`POST`</mark> `/api/pause_multi_order/`

Pause a multi-order and all its child orders, canceling all active placements and stopping execution until resumed. The multi-order will maintain its current state and can be resumed later.

**Request Body**

| Name                                               | Type   | Description      |
| -------------------------------------------------- | ------ | ---------------- |
| `multi_order_id`<mark style="color:red;">\*</mark> | string | Name of the user |

#### Example Request

```
POST /api/pause_multi_order/
Authorization: Bearer <token>
Content-Type: application/json

{
  "multi_order_id": "6debb950-614a-4366-b73b-7d7574fd9e15"
}
```

**Response Codes**

{% tabs %}
{% tab title="202: Accepted" %}

```json
{
    "message": "Successfully paused multi order."
}
```

{% endtab %}

{% tab title="400: Bad Request" %}
Occurs when:

* The `multi_order_id` field is missing from the request body
* The multi-order is already paused or terminated

```json
{
    "error": "Multi Order already paused or terminated"
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}
Occurs when:

* The user does not have permission to pause the specified multi-order (not the owner or not a superuser)

{% code title="Sample Error Message" %}

```json
{
    "error": "Unauthorized"
}
```

{% endcode %}
{% endtab %}

{% tab title="404: Not Found" %}
Occurs when:

* No multi-order exists with the given `multi_order_id`

{% code title="Sample Error Message" %}

```json
{
    "error": "No multi order found with given ID!"
}
```

{% endcode %}
{% endtab %}

{% tab title="422:  Unprocessable Entity" %}
{% code title="Sample Error Message" %}

```json
{
    "error": "Failed to pause all child orders: <error details>"
}
```

{% endcode %}
{% endtab %}

{% tab title="500" %}

```json
{
  "error": "Internal server error"
}
```

{% endtab %}
{% endtabs %}

## Resume Multi Order

<mark style="color:green;">`POST`</mark> `/api/resume_multi_order/`

Resume all legs of the multi order

**Request Body**

| Name                                               | Type   | Description                                           |
| -------------------------------------------------- | ------ | ----------------------------------------------------- |
| `multi_order_id`<mark style="color:red;">\*</mark> | string | UUID of the multi-order to resume. **Required Field** |

#### Example Request

```
POST /api/resume_multi_order/
Authorization: Bearer <token>
Content-Type: application/json

{
  "multi_order_id": "6debb950-614a-4366-b73b-7d7574fd9e15"
}
```

**Response Codes**

{% tabs %}
{% tab title="202: Accepted" %}

```json
{
    "message": "Successfully resumed multi order."
}
```

{% endtab %}

{% tab title="400: Bad Request" %}
Occurs when:

* The multi\_order\_id field is missing from the request body
* The multi-order is not currently paused

{% code title="Sample Error Messages" %}

```json
{
  "error": "Missing required field: multi_order_id"
}
```

{% endcode %}
{% endtab %}

{% tab title="401: Unauthorized" %}
Occurs when:

* The user does not have permission to resume the specified multi-order (not the owner or not a superuser)

{% code title="Sample Error Message" %}

```json
{
    "example": "Unauthorized"
}
```

{% endcode %}
{% endtab %}

{% tab title="422: Unprocessable Entity" %}
Occurs when:

* An error occurs while resuming one or more child orders
* There is a backend error during the resume operation

{% code title="Sample Error Message" %}

```json
{
    "error": "Failed to resume all child orders: <error details>"
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Get Placements

<mark style="color:blue;">`GET`</mark> `/api/placements/`

Returns placements (child orders) for a specific order.

### Query Parameters

| Name          | Type              | Description                                                                 |
| ------------- | ----------------- | --------------------------------------------------------------------------- |
| `order_id`    | string (UUID)     | UUID of the order to retrieve placements for. This is a required parameter. |
| `statuses`    | string            | comma separated list of statuses to filter by                               |
| `before`      | string (ISO 8601) | ISO 8601 timestamp (UTC). Filter placements created before this time.       |
| `after`       | string (ISO 8601) | ISO 8601 timestamp (UTC). Filter placements created after this time.        |
| `page_number` | number (integer)  | default: 1                                                                  |
| `page_size`   | number (integer)  | default: 100                                                                |

### **Request Body**

#### Top-Level Response Fields

| Field Name    | Type             | Nullable | Purpose                                        |
| ------------- | ---------------- | -------- | ---------------------------------------------- |
| `placements`  | array (object)   | No       | Array of placement objects                     |
| `page_number` | number (integer) | No       | Current page number                            |
| `page_size`   | number (integer) | No       | Number of items per page                       |
| `num_pages`   | number (integer) | No       | Total number of pages                          |
| `count`       | number (integer) | No       | Total count of placements matching the filters |

#### Placement Object Fields

| Field Name          | Type              | Nullable | Purpose                                                                                                                                           |
| ------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                | string (UUID)     | No       | Unique placement identifier                                                                                                                       |
| `exchange`          | string            | Yes      | Exchange name where the placement was sent (e.g., "Bybit", "Deribit", "Binance"). Can be null for certain placement types                         |
| `qty`               | number (float)    | No       | Total placement quantity (decimal as number). This is the target quantity for the placement                                                       |
| `executed_qty`      | number (float)    | No       | Executed quantity for this placement (decimal as number). Amount that has been filled                                                             |
| `base_qty`          | number (float)    | Yes      | Base asset quantity (decimal as number, nullable). Used when tracking in base asset terms                                                         |
| `executed_base_qty` | number (float)    | Yes      | Executed base asset quantity (decimal as number, nullable). Base asset amount that has been filled                                                |
| `price`             | number (float)    | Yes      | Placement price (decimal as number, nullable). Limit price for limit orders, null for market orders                                               |
| `status`            | string            | No       | Placement status. Possible values: "PENDING", "ACTIVE", "FILLED", "CANCELED", "CANCEL\_PENDING", "FAILED", "MISSING"                              |
| `placement_type`    | string            | No       | Type of placement. Possible values: "TAKE" (market/taker order), "MAKE" (limit/maker order), "TAKE-PROFIT" (take profit order)                    |
| `passiveness`       | number (float)    | No       | Passiveness parameter (decimal as number). Controls how passive/aggressive the placement is (0.0 = most aggressive, higher values = more passive) |
| `failure_reason`    | string            | No       | Failure reason if placement failed (empty string if no failure). Provides details about why a placement failed                                    |
| `created_at`        | string (ISO 8601) | No       | Timestamp when the placement was created (UTC)                                                                                                    |
| `pct_filled`        | number (float)    | No       | Percentage filled (decimal as number, 0-100). Percentage of the placement quantity that has been executed                                         |
| `external_id`       | string            | No       | External exchange order ID (empty string if not yet assigned). The order ID returned by the exchange for this placement                           |

#### Notes

1. **Type Inconsistency:** Unlike other endpoints that return decimal values as strings, this endpoint returns `qty`, `executed_qty`, `price`, `pct_filled`, `base_qty`, and `executed_base_qty` as numbers (float). This is due to the `GetPlacements` implementation returning raw Decimal values which are serialized as numbers, rather than using `TrimmedDecimalField` like other endpoints.
2. **Empty Strings vs Null:** The `failure_reason` and `external_id` fields are strings that can be empty strings (`""`) rather than `null` when they have no value.