Order Lifecycle — Amend, Cancel, Batch, and Fill History

Retrieve, amend, cancel, and batch-cancel orders. Fetch fill history for a subaccount. Endpoints: GET, PATCH, DELETE /v1/orders and GET /v1/fills.

The client.orders namespace provides full lifecycle management for your open and historical orders. Use these methods to inspect order state, amend resting orders, cancel individual orders or all orders at once, submit multiple orders in a single batch request, and retrieve fill records for a subaccount.

---

orders.get

Retrieve a single order by its ID.

Method: client.orders.get(order_id) — GET /v1/orders/{id}

from molecule import Molecule

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

order = client.orders.get("ord_abc123")
print(order["id"], order["status"], order["qty"], order["price"])

order_id · integer | string · required

The Molecule order ID to retrieve. Accepts either the integer ID or its string representation.

---

orders.list

List all orders for a subaccount, optionally filtered by status.

Method: client.orders.list(subaccount_id, status=None) — GET /v1/orders

# Retrieve all open orders for a subaccount
orders = client.orders.list(subaccount_id="sa_abc123", status="OPEN")

for order in orders:
    print(order["id"], order["status"], order["instrument_id"])

subaccount_id · string · required

The subaccount whose orders to retrieve.

status · OrderStatus

Optional status filter. One of PENDING_SUBMISSION, OPEN, PARTIAL, FILLED, CANCELLED, REJECTED, or EXPIRED. Omit to return orders across all statuses.

---

orders.amend

Amend a resting order’s price, quantity, or other mutable fields.

Method: client.orders.amend(order_id, **payload) — PATCH /v1/orders/{id}

# Reprice a resting limit order
amended = client.orders.amend(
    "ord_abc123",
    price="0.52",
    qty="8",
)
print(amended["id"], amended["price"], amended["qty"])

order_id · integer | string · required

The ID of the order to amend. The order must be in an amendable state (OPEN or PARTIAL).

price · string

New limit price as a decimal string.

qty · string

New quantity as a decimal string. May be reduced but not increased beyond the original quantity on some venues.

Only pass fields you want to change. Unspecified fields retain their current values.

---

orders.cancel

Cancel a single open order by ID.

Method: client.orders.cancel(order_id) — DELETE /v1/orders/{id}

result = client.orders.cancel("ord_abc123")
print(result)

order_id · integer | string · required

The ID of the order to cancel.

---

orders.cancel_all

Cancel all open orders for a subaccount. Omit subaccount_id to cancel across all subaccounts.

Method: client.orders.cancel_all(subaccount_id=None) — POST /v1/orders/cancel-all

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

# Cancel all open orders across all subaccounts
client.orders.cancel_all()

subaccount_id · string

The subaccount whose open orders to cancel. Omit to cancel across all subaccounts associated with your key.

This action is irreversible. All resting orders for the specified scope are cancelled immediately.

---

orders.batch

Submit multiple orders in a single atomic request. Useful for placing a set of related orders while minimising round-trips.

Method: client.orders.batch(orders) — POST /v1/orders/batch

result = client.orders.batch([
    {
        "subaccount_id": "sa_1",
        "instrument_id": 42,
        "side": "BUY",
        "type": "LIMIT",
        "tif": "GTC",
        "price": "0.50",
        "qty": "5",
    },
    {
        "subaccount_id": "sa_1",
        "instrument_id": 43,
        "side": "SELL",
        "type": "LIMIT",
        "tif": "IOC",
        "price": "0.55",
        "qty": "3",
    },
])
print(result)

orders · array · required

A list of order objects. Each object accepts the same fields as a single order creation payload, including subaccount_id, instrument_id, side, type, tif, price, qty, and routing.

---

orders.fills

Retrieve all fill records for a subaccount.

Method: client.orders.fills(subaccount_id) — GET /v1/fills

fills = client.orders.fills(subaccount_id="sa_abc123")

for fill in fills:
    print(fill["order_id"], fill["price"], fill["qty"], fill["created_at"])

subaccount_id · string · required

The subaccount whose fill history to retrieve.

Fill records are also accessible via client.portfolio.fills(subaccount_id), which exposes the same GET /v1/fills endpoint. Use whichever namespace is more natural for your workflow.

---

Error reference

Exception	HTTP status	When raised
NotFoundError	404	Order ID does not exist or belongs to a different subaccount
ValidationError	422	Invalid amend payload or missing required batch fields
UnauthorizedError	401	Invalid or missing Ed25519 signature
ForbiddenError	403	Kill switch active or insufficient permissions
ConflictError	409	Idempotency key conflict on batch submission
RateLimitedError	429	Request rate limit exceeded