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

Create ICEBERG, PEG, STOP, TP_SL, and SMART_ROUTE complex orders via Molecule. Parent orders manage child order lifecycle automatically.

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

type · "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

subaccount_id · string · required

The subaccount from which to manage child orders.

instrument_id · integer

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

generic_asset_id · integer

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

side · "BUY" | "SELL"

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

outcome · "YES" | "NO"

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

qty · string

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

price · 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.

params · object

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

Show Common params fields

params.slice_qty · string

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

params.trigger_price · string

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

params.stop_price · string

(TP_SL) The stop-loss trigger price.

params.tp_price · string

(TP_SL) The take-profit trigger price.

routing · object

Routing configuration object.

Show routing fields

routing.mode · "DIRECT" | "BEST_PRICE" | "SPLIT"

Routing strategy. See Create Order for mode descriptions.

idempotency_key · 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