> ## Documentation Index
> Fetch the complete documentation index at: https://molelcule.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CardGroup cols={2}>
  <Card title="ICEBERG" icon="layer-group">
    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.
  </Card>

  <Card title="PEG" icon="arrow-right-arrow-left">
    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.
  </Card>

  <Card title="STOP" icon="hand">
    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.
  </Card>

  <Card title="TP_SL" icon="sliders">
    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.
  </Card>

  <Card title="SMART_ROUTE" icon="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.
  </Card>
</CardGroup>

## 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.

```python theme={"dark"}
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.

```python theme={"dark"}
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

<ParamField body="type" type="string" required>
  The complex order algorithm. One of `ICEBERG`, `PEG`, `STOP`, `TP_SL`, `SMART_ROUTE`.
</ParamField>

<ParamField body="subaccount_id" type="string" required>
  The subaccount under which the order is placed.
</ParamField>

<ParamField body="instrument_id" type="integer">
  The venue-specific instrument. Required when `routing.mode` is `DIRECT` or when targeting a specific instrument.
</ParamField>

<ParamField body="generic_asset_id" type="integer">
  The cross-venue asset identifier. Required when `routing.mode` is `BEST_PRICE`, `SPLIT`, or `SMART_ROUTE`.
</ParamField>

<ParamField body="side" type="string" required>
  `BUY` or `SELL`.
</ParamField>

<ParamField body="outcome" type="string">
  `YES` or `NO`. Required on binary markets where the instrument is identified by outcome.
</ParamField>

<ParamField body="qty" type="string" required>
  Total quantity to execute, as a decimal string (e.g. `"1000"`).
</ParamField>

<ParamField body="price" type="string">
  Limit price for the order or its child orders, as a decimal string (e.g. `"0.52"`). Required for most types.
</ParamField>

<ParamField body="params" type="object">
  Type-specific configuration.

  <Expandable title="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 |
  </Expandable>
</ParamField>

<ParamField body="routing" type="object">
  Routing configuration. Contains a `mode` field: `DIRECT`, `BEST_PRICE`, or `SPLIT`.
</ParamField>

<ParamField body="idempotency_key" type="string">
  A client-supplied string used to deduplicate submissions. The same key with a different request body returns `ConflictError` (`idempotency_conflict`).
</ParamField>

## 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`.

```python theme={"dark"}
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)`.

```python theme={"dark"}
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.

```python theme={"dark"}
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.

```python theme={"dark"}
client.complex_orders.cancel(order_id=98765)
```

### Cancel All Complex Orders

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

```python theme={"dark"}
client.complex_orders.cancel_all(subaccount_id="sub_123")
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.