Place Complex Orders with Molecule: ICEBERG, STOP, and More

Submit ICEBERG, PEG, STOP, TP_SL, and SMART_ROUTE complex orders via Molecule. Cancelling a parent order automatically cancels all its children.

Complex orders extend simple limit and market orders with algorithmic execution logic. Each complex order is a parent that the Molecule engine decomposes into one or more child orders. Cancelling the parent propagates automatically to every child — you never need to track or cancel children individually. Complex orders use idempotency_key (not client_order_id) as the idempotency key, and the API enforces that the same key cannot be reused with a different request body.

Complex Order Types

ICEBERG

Slices a large order into smaller child orders. Only the current slice size is exposed to the market at any time, hiding the true total quantity from other participants.

PEG

Continuously tracks a reference price, adjusting the resting order as the market moves. Use this to maintain a position relative to the best bid, ask, or mid.

STOP

Remains passive until a specified trigger price is reached. When the market trades through the trigger, the engine submits a child order on your behalf.

TP_SL

Places a take-profit and stop-loss bracket around an existing position. Both legs are managed as children of a single parent; cancelling the parent removes both.

SMART_ROUTE

Routes a single order across multiple venues to achieve best overall execution. Requires generic_asset_id so the router can identify the same market across venues.

Creating a Complex Order

Submit a complex order using client.create_complex_order(**payload) (top-level shortcut) or client.complex_orders.create(**payload). Both call POST /v1/complex-orders.

The type field selects the algorithm; the params object carries type-specific configuration.

ICEBERG Example

An ICEBERG order exposes only slice_qty contracts to the market at a time. Once a slice fills, the engine submits the next slice automatically until the full qty is complete.

from molecule import Molecule

client = Molecule(
    base_url="https://api.molecule.fi",
    key_id="your-key-id",
    private_key="your-base64-private-key",
)

order = client.create_complex_order(
    type="ICEBERG",
    subaccount_id="sub_123",
    instrument_id=4001,
    side="BUY",
    qty="1000",
    price="0.52",
    params={"slice_qty": "50"},
    routing={"mode": "DIRECT"},
    idempotency_key="iceberg-btc-1",
)

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

STOP Example

A STOP order submits a child order only when the market price reaches trigger_price. The child order is placed at the price you specify.

order = client.create_complex_order(
    type="STOP",
    subaccount_id="sub_123",
    instrument_id=4001,
    side="SELL",
    qty="100",
    price="0.40",
    params={"trigger_price": "0.38"},
    idempotency_key="stop-1",
)

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

Parameters

type · string · required

The complex order algorithm. One of ICEBERG, PEG, STOP, TP_SL, SMART_ROUTE.

subaccount_id · string · required

The subaccount under which the order is placed.

instrument_id · integer

The venue-specific instrument. Required when routing.mode is DIRECT or when targeting a specific instrument.

generic_asset_id · integer

The cross-venue asset identifier. Required when routing.mode is BEST_PRICE, SPLIT, or SMART_ROUTE.

side · string · required

BUY or SELL.

outcome · string

YES or NO. Required on binary markets where the instrument is identified by outcome.

qty · string · required

Total quantity to execute, as a decimal string (e.g. "1000").

price · string

Limit price for the order or its child orders, as a decimal string (e.g. "0.52"). Required for most types.

params · object

Type-specific configuration.

Show Type-specific params keys

Type	Key	Description
ICEBERG	slice_qty	Quantity exposed per child slice
STOP	trigger_price	Price level that activates the child order
PEG	type-specific	Reference and offset configuration
TP_SL	type-specific	Take-profit and stop-loss price levels
SMART_ROUTE	type-specific	Venue routing preferences

routing · object

Routing configuration. Contains a mode field: DIRECT, BEST_PRICE, or SPLIT.

idempotency_key · string

A client-supplied string used to deduplicate submissions. The same key with a different request body returns ConflictError (idempotency_conflict).

Idempotency

Complex orders use the idempotency_key field — not client_order_id — as the deduplication key. The SDK sends this value in the Idempotency-Key request header. If you retry a request with the same idempotency_key and an identical body, the API returns the original response. If the body differs, the API raises a ConflictError with error code idempotency_conflict.

from molecule.errors import ConflictError

try:
    order = client.create_complex_order(
        type="ICEBERG",
        subaccount_id="sub_123",
        instrument_id=4001,
        side="BUY",
        qty="1000",
        price="0.52",
        params={"slice_qty": "50"},
        idempotency_key="iceberg-unique-run-id",
    )
except ConflictError as e:
    print("Duplicate or conflicting request:", e)

Managing Complex Orders

Retrieve a Single Complex Order

Fetch the current state of a complex order — including its status and any child order references — using client.complex_orders.get(order_id).

order = client.complex_orders.get(order_id=98765)
print(order["type"], order["status"], order["qty_filled"])

List Complex Orders for a Subaccount

Retrieve all active and historical complex orders for a given subaccount.

orders = client.complex_orders.list(subaccount_id="sub_123")
for o in orders:
    print(o["id"], o["type"], o["status"])

Cancel a Complex Order

Cancel a single complex order by ID. Cancelling the parent automatically cancels all its outstanding child orders.

client.complex_orders.cancel(order_id=98765)

Cancel All Complex Orders

Cancel every open complex order for a subaccount in a single call.

client.complex_orders.cancel_all(subaccount_id="sub_123")

Cancelling a parent complex order propagates to all child orders immediately. You do not need to track or cancel child order IDs individually.