Submit and Manage Orders Using the Molecule Orders API

The client.orders namespace lets you submit orders to any live venue, amend or cancel them individually or in bulk, poll for status updates, and retrieve your fill history. Routing decisions — whether to target a specific venue instrument or to let Molecule find the best available price — are controlled per order through the routing field.

Creating an Order

Submit a single order with client.orders.create() or the top-level shortcut client.create_order(). Both call POST /v1/orders.

import os
from molecule import Molecule

client = Molecule(
    base_url=os.environ["MOLECULE_BASE_URL"],
    key_id=os.environ["MOLECULE_KEY_ID"],
    private_key=os.environ["MOLECULE_PRIVATE_KEY"],
)

order = client.create_order(
    subaccount_id=os.environ["MOLECULE_SUBACCOUNT_ID"],
    instrument_id=98712,          # venue-specific ID, used with DIRECT routing
    side="BUY",
    outcome="YES",
    type="LIMIT",
    tif="GTC",
    price="0.62",
    qty="100",
    routing={"mode": "DIRECT"},
    client_order_id="strat-alpha-001",   # idempotency key
)

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

Order parameters

string

required

The subaccount to trade from. All risk checks and fill attribution apply to this subaccount.

integer

Venue-specific instrument identifier. Required when routing.mode is DIRECT. Obtain this from client.markets.get() or client.markets.search().

integer

Cross-venue asset identifier. Required when routing.mode is BEST_PRICE or SPLIT.

"BUY" | "SELL"

required

Order direction.

"YES" | "NO"

Outcome side for binary markets. Specifies which contract you are buying or selling.

"LIMIT" | "MARKET"

required

Order type. LIMIT requires a price. MARKET fills at the best available price.

"GTC" | "IOC" | "FOK" | "GTD"

Time-in-force policy.

GTC — Good Till Cancelled. Rests on the book until filled or explicitly cancelled.
IOC — Immediate Or Cancel. Fills whatever is available immediately; cancels the remainder.
FOK — Fill Or Kill. Must fill in full immediately, or the entire order is cancelled.
GTD — Good Till Date. Rests until a specified expiry.

string

Limit price expressed as a decimal string (e.g., "0.62"). Required for LIMIT orders.

string

required

Order quantity expressed as a decimal string (e.g., "100").

object

Routing configuration object.

Show routing fields

"DIRECT" | "BEST_PRICE" | "SPLIT"

Routing strategy. See Routing Modes below.

string

Your reference ID for this order. Sent as the Idempotency-Key header — use it to safely retry order submission. See Idempotency.

Routing Modes

Every order declares how Molecule should route it to execution venues.

DIRECT

Routes to a single venue-specific instrument. Requires instrument_id. Use this when you have a strong venue preference or are responding to a specific market condition on one venue.

BEST_PRICE

Finds the best available price across all live venues for the given generic_asset_id. Molecule selects the optimal venue at execution time.

SPLIT

Splits the order quantity across multiple live venues using generic_asset_id, improving fill probability for larger sizes.

DIRECT routing requires instrument_id. BEST_PRICE and SPLIT routing require generic_asset_id. Passing the wrong identifier for the routing mode results in a ValidationError.

# BEST_PRICE — let Molecule find the best venue
order = client.create_order(
    subaccount_id=os.environ["MOLECULE_SUBACCOUNT_ID"],
    generic_asset_id=4401,
    side="BUY",
    outcome="YES",
    type="LIMIT",
    tif="IOC",
    price="0.60",
    qty="200",
    routing={"mode": "BEST_PRICE"},
    client_order_id="strat-alpha-002",
)

# SPLIT — distribute across venues
order = client.create_order(
    subaccount_id=os.environ["MOLECULE_SUBACCOUNT_ID"],
    generic_asset_id=4401,
    side="BUY",
    outcome="YES",
    type="LIMIT",
    tif="GTC",
    price="0.59",
    qty="500",
    routing={"mode": "SPLIT"},
    client_order_id="strat-alpha-003",
)

Idempotency

The client_order_id field doubles as an idempotency key. The SDK sends it as an Idempotency-Key HTTP header on every POST /v1/orders call.

Same key, same body — safe to retry after a network timeout. The API returns the original order response without creating a duplicate.
Same key, different body — the API raises a ConflictError with error="idempotency_conflict".

import uuid
from molecule.errors import ConflictError

client_order_id = f"strat-alpha-{uuid.uuid4()}"

payload = dict(
    subaccount_id=os.environ["MOLECULE_SUBACCOUNT_ID"],
    instrument_id=98712,
    side="BUY",
    outcome="YES",
    type="LIMIT",
    tif="GTC",
    price="0.55",
    qty="50",
    routing={"mode": "DIRECT"},
    client_order_id=client_order_id,
)

for attempt in range(3):
    try:
        order = client.create_order(**payload)
        print("Submitted:", order["id"])
        break
    except ConflictError as exc:
        if exc.error == "idempotency_conflict":
            # Different payload sent with the same key — do not retry
            raise
        raise

Generate a fresh client_order_id for each logically distinct order. Reusing the same key with different parameters raises ConflictError and the order will not be submitted.

Order Lifecycle

Orders move through a defined sequence of states:

PENDING_SUBMISSION → OPEN → PARTIAL → FILLED
                          ↘ CANCELLED
                          ↘ REJECTED
                          ↘ EXPIRED

Status definitions

Status	Meaning
`PENDING_SUBMISSION`	Accepted by Molecule, not yet acknowledged by the venue.
`OPEN`	Live on the venue order book, no fills yet.
`PARTIAL`	Partially filled; remainder still resting.
`FILLED`	Fully filled.
`CANCELLED`	Cancelled by you or the venue.
`REJECTED`	Rejected at submission by the venue or risk checks.
`EXPIRED`	Expired per the time-in-force policy (e.g., `GTD` deadline reached).

Fetch a single order by ID, or list all orders for a subaccount:

# GET /v1/orders/{id}
order = client.orders.get(order_id="ord_8kXq2Lp9")
print(order["id"], order["status"], order["filled_qty"])

# GET /v1/orders
orders = client.orders.list(
    subaccount_id=os.environ["MOLECULE_SUBACCOUNT_ID"],
    status="OPEN",  # omit to return all statuses
)
for o in orders:
    print(o["id"], o["status"], o["qty"], o["filled_qty"])

import time

order_id = "ord_8kXq2Lp9"
TERMINAL = {"FILLED", "CANCELLED", "REJECTED", "EXPIRED"}

while True:
    order = client.orders.get(order_id)
    status = order["status"]
    print(status, order.get("filled_qty"))
    if status in TERMINAL:
        break
    time.sleep(0.5)

For real-time order updates without polling, subscribe to the WebSocket stream at /v1/ws/orders using client.iter_ws("/v1/ws/orders").

Amending an Order

Modify the price or quantity of a resting order with client.orders.amend(). Only open or partially filled orders can be amended.

# PATCH /v1/orders/{id}
updated = client.orders.amend(
    "ord_8kXq2Lp9",
    price="0.57",
    qty="75",
)
print(updated["id"], updated["price"], updated["qty"])

Not all venues support in-flight amends. If the venue requires a cancel-replace, Molecule handles this transparently. Check the returned order object for the current state.

Cancelling Orders

Cancel a single order or all open orders for a subaccount.

# DELETE /v1/orders/{id}
result = client.orders.cancel("ord_8kXq2Lp9")
print(result)

# POST /v1/orders/cancel-all
result = client.orders.cancel_all(
    subaccount_id=os.environ["MOLECULE_SUBACCOUNT_ID"]
)
print(result)

cancel_all() cancels every open and partially filled order for the specified subaccount across all venues simultaneously. Use client.risk.kill_switch(enabled=True) to halt all activity at the account level.

Batch Orders

Submit multiple orders in a single request to reduce round trips and ensure consistent timing.

# POST /v1/orders/batch
orders = [
    {
        "subaccount_id": os.environ["MOLECULE_SUBACCOUNT_ID"],
        "instrument_id": 98712,
        "side": "BUY",
        "outcome": "YES",
        "type": "LIMIT",
        "tif": "GTC",
        "price": "0.48",
        "qty": "100",
        "routing": {"mode": "DIRECT"},
        "client_order_id": "batch-leg-1",
    },
    {
        "subaccount_id": os.environ["MOLECULE_SUBACCOUNT_ID"],
        "instrument_id": 98713,
        "side": "SELL",
        "outcome": "YES",
        "type": "LIMIT",
        "tif": "GTC",
        "price": "0.52",
        "qty": "100",
        "routing": {"mode": "DIRECT"},
        "client_order_id": "batch-leg-2",
    },
]

results = client.orders.batch(orders)
for r in results:
    print(r["client_order_id"], r.get("id"), r.get("status"))

Each order in the batch is subject to the same validation and risk checks as individual orders. The response includes one entry per submitted order. A validation failure on one leg does not necessarily cancel the rest — inspect each entry’s status independently.

Fills

Retrieve the fill history for a subaccount. Fills represent confirmed executions and are the source of truth for realized P&L.

# GET /v1/fills
fills = client.orders.fills(
    subaccount_id=os.environ["MOLECULE_SUBACCOUNT_ID"]
)
for fill in fills:
    print(
        fill["order_id"],
        fill["instrument_id"],
        fill["side"],
        fill["price"],
        fill["qty"],
        fill["timestamp"],
    )

Fills are also available via client.portfolio.fills(), which calls the same /v1/fills endpoint. The client.orders.fills() shortcut is provided for convenience when working primarily in the orders namespace.

Overview

Authentication

Guides

Venues

Security

Submit and Manage Orders Using the Molecule Orders API

Creating an Order

Order parameters

Routing Modes

DIRECT

BEST_PRICE

SPLIT

Idempotency

Order Lifecycle

Amending an Order

Cancelling Orders

Batch Orders

Fills

​Creating an Order

​Order parameters

​Routing Modes

DIRECT

BEST_PRICE

SPLIT

​Idempotency

​Order Lifecycle

​Amending an Order

​Cancelling Orders

​Batch Orders

​Fills

Creating an Order

Order parameters

Routing Modes

Idempotency

Order Lifecycle

Amending an Order

Cancelling Orders

Batch Orders

Fills