Ctrlk
Go to website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Multi Order

Operations for interacting with multi orders.

Get Multi Order

GET /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

{
    "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"
}

Get Multi Orders

GET /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 statusesMultiOrderStatus [Enum]

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

Response Codes

Submit Multi Order

POST /api/multi_orders/

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

Name
Type
Required
Description

accounts

array[string]

Yes

List of account names to use for the multi-order

duration

integer

Yes

Duration of the multi-order in seconds

strategy

string

Yes

Strategy name to use for execution. Ex. VWAP

engine_passiveness

decimal

Yes

Engine passiveness value (0.0 to 1.0)

schedule_discretion

decimal

Yes

Schedule discretion value (0.0 to 1.0)

child_orders

array[object]

Yes

Array of child order objects

strategy_params

object

No

Strategy-specific parameters

alpha_tilt

decimal

No

Alpha tilt value for order execution

exposure_tolerance

decimal

No

Exposure tolerance for the multi-order

limit_price_spread

decimal

No

Dynamic limit price spread for spread trades

order_condition

string

No

Conditional order expression

start_timedate

string

No

ISO 8601 timestamp for order start (defaults to now)

custom_order_id

string

No

Custom identifier for the multi-order

notes

string

No

Additional notes for the multi-order

Child Order Object

Name
Type
Required
Description

pair

string

Yes

Trading pair symbol

side

string

Yes

Order side: buy or sell

base_asset_qty

decimal

Yes

Base asset quantity

accounts

array[string]

No

Specific accounts for this child order (overrides parent accounts)

quote_asset_qty

decimal

No

Quote asset quantity (alternative to base_asset_qty)

notes

string

No

Notes specific to this child order

alpha_tilt

decimal

No

Alpha tilt specific to this child order

pos_side

string

No

Position side: long or short. Required if exchange account is configured to be in Hedge Mode.

Example Request

Response

Cancel Multi Orders

POST /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

Pause Multi Order

POST /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*

string

Name of the user

Example Request

Response Codes

Occurs when:

  • The multi_order_id field is missing from the request body

  • The multi-order is already paused or terminated

Occurs when:

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

Occurs when:

  • No multi-order exists with the given multi_order_id

Resume Multi Order

POST /api/resume_multi_order/

Resume all legs of the multi order

Request Body

Name
Type
Description

multi_order_id*

string

UUID of the multi-order to resume. Required Field

Example Request

Response Codes

Occurs when:

  • The multi_order_id field is missing from the request body

  • The multi-order is not currently paused

Occurs when:

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

Occurs when:

  • An error occurs while resuming one or more child orders

  • There is a backend error during the resume operation

Get Placements

GET /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.

Last updated

Was this helpful?