Complex Orders — ICEBERG, PEG, STOP, TP_SL, SMART_ROUTE

Complex orders are parent orders that Molecule manages on your behalf, spawning and cancelling child orders automatically according to the order type’s logic. Use them when you need execution strategies beyond a single resting or market order — for example, splitting a large position into hidden slices (ICEBERG), pegging to the best available price (PEG), or triggering on a price condition (STOP, TP_SL). Call client.complex_orders.create() or the top-level shortcut client.create_complex_order() to submit a complex order to POST /v1/complex-orders.

Method

client.complex_orders.create(**payload)
client.create_complex_order(**payload)   # shortcut

Endpoint: POST /v1/complex-orders

Parameters

"ICEBERG" | "PEG" | "STOP" | "TP_SL" | "SMART_ROUTE"

required

The complex order type that determines execution behaviour.

Type	Behaviour
`ICEBERG`	Shows only a slice of the total quantity; replenishes as slices fill
`PEG`	Continuously adjusts the child order price to track the market
`STOP`	Submits a child order when the market touches a trigger price
`TP_SL`	Manages a take-profit and stop-loss pair for an open position
`SMART_ROUTE`	Dynamically routes across venues for optimal execution

string

required

The subaccount from which to manage child orders.

integer

Venue-specific instrument ID. Required when using DIRECT routing.

integer

Cross-venue asset ID. Required when using BEST_PRICE or SPLIT routing.

"BUY" | "SELL"

Direction of child orders. Required for most complex order types.

"YES" | "NO"

Binary outcome leg. Required for binary markets where the instrument tracks a specific resolution outcome.

string

Total quantity as a decimal string. For ICEBERG, this is the full hidden quantity.

string

Reference price as a decimal string. Interpretation varies by type: limit price for STOP child orders, initial peg price for PEG, and so on.

object

Type-specific configuration parameters. The fields accepted here depend on type.

Show Common params fields

string

(ICEBERG) The visible slice quantity to show on the book at any one time.

string

(STOP, TP_SL) The market price that triggers child order submission.

string

(TP_SL) The stop-loss trigger price.

string

(TP_SL) The take-profit trigger price.

object

Routing configuration object.

Show routing fields

"DIRECT" | "BEST_PRICE" | "SPLIT"

Routing strategy. See Create Order for mode descriptions.

string

Idempotency key for this complex order. Unlike simple orders (which use client_order_id), complex orders use this dedicated field. Retrying with the same key and body is safe; retrying with the same key and a different body raises ConflictError.

Examples

ICEBERG order

An ICEBERG order hides the full quantity and exposes only a slice_qty at a time. As each slice fills, a new child order is automatically placed until the total quantity is exhausted.

from molecule import Molecule

client = Molecule(
    base_url="https://api.molecule.trade",
    key_id="key_abc123",
    private_key="<base64-encoded-ed25519-seed>",
)

iceberg = client.create_complex_order(
    type="ICEBERG",
    subaccount_id="sa_abc123",
    instrument_id=42,
    side="BUY",
    qty="100",
    price="0.47",
    params={"slice_qty": "10"},
    routing={"mode": "DIRECT"},
    idempotency_key="iceberg-desk-001",
)

print(iceberg["id"], iceberg["type"], iceberg["status"])

STOP order

A STOP order watches the market and submits a child order when the price crosses trigger_price.

stop = client.create_complex_order(
    type="STOP",
    subaccount_id="sa_abc123",
    instrument_id=42,
    side="SELL",
    qty="25",
    price="0.40",
    params={"trigger_price": "0.42"},
    routing={"mode": "DIRECT"},
    idempotency_key="stop-desk-002",
)

print(stop["id"], stop["status"])

TP_SL order

A TP_SL order places a take-profit and stop-loss simultaneously, managing both legs until one triggers and the other is cancelled.

tp_sl = client.create_complex_order(
    type="TP_SL",
    subaccount_id="sa_abc123",
    instrument_id=42,
    side="SELL",
    qty="50",
    params={
        "tp_price": "0.75",
        "stop_price": "0.35",
    },
    routing={"mode": "DIRECT"},
    idempotency_key="tp-sl-desk-003",
)

print(tp_sl["id"], tp_sl["status"])

Managing complex orders

Use client.complex_orders to retrieve, list, and cancel complex orders:

# Retrieve a specific complex order
order = client.complex_orders.get("co_xyz789")

# List all complex orders for a subaccount
all_orders = client.complex_orders.list(subaccount_id="sa_abc123")

# Cancel a specific complex order
client.complex_orders.cancel("co_xyz789")

# Cancel all complex orders for a subaccount
client.complex_orders.cancel_all(subaccount_id="sa_abc123")

Cancelling a parent complex order immediately cancels all child orders it has spawned. There is no partial-cancel option at the parent level.

Idempotency

Complex orders use the idempotency_key field — not client_order_id. Sending the same idempotency_key with the same body is safe to retry and returns the original response. Sending the same key with a different body raises ConflictError with error code idempotency_conflict.

Error reference

Exception	HTTP status	When raised
`ValidationError`	422	Missing required fields or invalid `params` for the given `type`
`UnauthorizedError`	401	Invalid or missing Ed25519 signature
`ForbiddenError`	403	Kill switch active or insufficient permissions
`ConflictError`	409	`idempotency_key` reused with a different payload
`RoutingUnavailableError`	400	No live venue available for the requested route
`NotFoundError`	404	Complex order ID not found on cancel or get

Python SDK

Markets

Orders

Portfolio

WebSockets

Complex Orders — ICEBERG, PEG, STOP, TP_SL, SMART_ROUTE

Method

Parameters

Examples

ICEBERG order

STOP order

TP_SL order

Managing complex orders

Idempotency

Error reference

​Method

​Parameters

​Examples

​ICEBERG order

​STOP order

​TP_SL order

​Managing complex orders

​Idempotency

​Error reference

Method

Parameters

Examples

ICEBERG order

STOP order

TP_SL order

Managing complex orders

Idempotency

Error reference