POST /v1/orders — Create a Prediction Market Order

Submit a LIMIT or MARKET order to a prediction market venue via Molecule. Supports DIRECT, BEST_PRICE, and SPLIT routing modes with idempotent submission.

Submit a single order to a prediction market venue using client.orders.create() or its top-level shortcut client.create_order(). Both methods call POST /v1/orders and return the created order object. The routing mode you choose determines whether you target a specific venue instrument (DIRECT) or let Molecule find the best available price across venues (BEST_PRICE, SPLIT).

Method

client.orders.create(**payload)
client.create_order(**payload)   # shortcut

Endpoint: POST /v1/orders

Example

from molecule import Molecule

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

order = client.create_order(
    subaccount_id="sa_abc123",
    instrument_id=42,
    side="BUY",
    type="LIMIT",
    tif="GTC",
    price="0.48",
    qty="10",
    routing={"mode": "DIRECT"},
    client_order_id="desk-house-1",
)

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

Parameters

subaccount_id · string · required

The subaccount from which to submit the order.

instrument_id · integer

Venue-specific instrument ID. Required when routing.mode is DIRECT. Identifies the exact instrument at a specific venue.

generic_asset_id · integer

Cross-venue asset ID. Required when routing.mode is BEST_PRICE or SPLIT. Molecule resolves the best available instrument(s) across venues automatically.

side · "BUY" | "SELL" · required

Direction of the order.

outcome · "YES" | "NO"

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

type · "LIMIT" | "MARKET" · required

Order type. LIMIT rests at the specified price; MARKET fills at the best available price.

tif · "GTC" | "IOC" | "FOK" | "GTD"

Time-in-force. Controls how long the order remains active.

Value	Behaviour
GTC	Good Till Cancelled — rests until filled or explicitly cancelled (default)
IOC	Immediate Or Cancel — fills what it can, cancels the remainder
FOK	Fill Or Kill — fills in full or cancels entirely
GTD	Good Till Date — rests until a specified expiry

price · string

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

qty · string · required

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

routing · object

Routing configuration object.

Show routing fields

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

Routing strategy to apply.

• DIRECT — send directly to the venue identified by instrument_id
• BEST_PRICE — route to the single venue with the best available price for generic_asset_id
• SPLIT — split quantity across multiple venues for generic_asset_id

client_order_id · string

Your reference ID for this order. Molecule sends this value as the Idempotency-Key request header. Use it to safely retry order submission without risk of duplicate fills.

Response

The API returns the created order object. Key fields:

id · string

Molecule’s unique identifier for the order.

status · OrderStatus

Current order status. One of PENDING_SUBMISSION, OPEN, PARTIAL, FILLED, CANCELLED, REJECTED, or EXPIRED.

client_order_id · string

The client-supplied reference ID echoed back by the API.

Routing modes in detail

DIRECT

Provide instrument_id. Routes the order to that specific venue instrument without any cross-venue logic.

BEST_PRICE

Provide generic_asset_id. Molecule queries live venues and routes the full quantity to whichever offers the best executable price.

SPLIT

Provide generic_asset_id. Molecule distributes the quantity across venues to optimise execution. The router never invents size.

Idempotency

Submitting an order with the same client_order_id and the same request body is safe to retry — Molecule returns the original order response. Submitting the same client_order_id with a different body raises a ConflictError with error code idempotency_conflict.

from molecule.errors import ConflictError

try:
    order = client.create_order(
        subaccount_id="sa_abc123",
        instrument_id=42,
        side="BUY",
        type="LIMIT",
        tif="GTC",
        price="0.48",
        qty="10",
        routing={"mode": "DIRECT"},
        client_order_id="desk-house-1",
    )
except ConflictError as e:
    # e.error == "idempotency_conflict" means same key, different body
    print(e)

Error reference

Exception	HTTP status	When raised
ValidationError	422	Missing required fields or invalid values
UnauthorizedError	401	Invalid or missing Ed25519 signature
ForbiddenError	403	Kill switch active or insufficient permissions
ConflictError	409	client_order_id reused with a different payload
RoutingUnavailableError	400	No live venue available for the requested route
RateLimitedError	429	Request rate limit exceeded