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

# 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

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

<ParamField body="subaccount_id" type="string" required>
  The subaccount from which to submit the order.
</ParamField>

<ParamField body="instrument_id" type="integer">
  Venue-specific instrument ID. Required when `routing.mode` is `DIRECT`. Identifies the exact instrument at a specific venue.
</ParamField>

<ParamField body="generic_asset_id" type="integer">
  Cross-venue asset ID. Required when `routing.mode` is `BEST_PRICE` or `SPLIT`. Molecule resolves the best available instrument(s) across venues automatically.
</ParamField>

<ParamField body="side" type="&#x22;BUY&#x22; | &#x22;SELL&#x22;" required>
  Direction of the order.
</ParamField>

<ParamField body="outcome" type="&#x22;YES&#x22; | &#x22;NO&#x22;">
  Binary outcome leg. Required for binary markets where the instrument tracks a specific resolution outcome.
</ParamField>

<ParamField body="type" type="&#x22;LIMIT&#x22; | &#x22;MARKET&#x22;" required>
  Order type. `LIMIT` rests at the specified price; `MARKET` fills at the best available price.
</ParamField>

<ParamField body="tif" type="&#x22;GTC&#x22; | &#x22;IOC&#x22; | &#x22;FOK&#x22; | &#x22;GTD&#x22;">
  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 |
</ParamField>

<ParamField body="price" type="string">
  Limit price as a decimal string (e.g., `"0.48"`). Required for `LIMIT` orders.
</ParamField>

<ParamField body="qty" type="string" required>
  Order quantity as a decimal string (e.g., `"10"`).
</ParamField>

<ParamField body="routing" type="object">
  Routing configuration object.

  <Expandable title="routing fields">
    <ParamField body="routing.mode" type="&#x22;DIRECT&#x22; | &#x22;BEST_PRICE&#x22; | &#x22;SPLIT&#x22;">
      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`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="client_order_id" type="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.
</ParamField>

## Response

The API returns the created order object. Key fields:

<ResponseField name="id" type="string">
  Molecule's unique identifier for the order.
</ResponseField>

<ResponseField name="status" type="OrderStatus">
  Current order status. One of `PENDING_SUBMISSION`, `OPEN`, `PARTIAL`, `FILLED`, `CANCELLED`, `REJECTED`, or `EXPIRED`.
</ResponseField>

<ResponseField name="client_order_id" type="string">
  The client-supplied reference ID echoed back by the API.
</ResponseField>

## Routing modes in detail

<CardGroup cols={3}>
  <Card title="DIRECT" icon="arrow-right">
    Provide `instrument_id`. Routes the order to that specific venue instrument without any cross-venue logic.
  </Card>

  <Card title="BEST_PRICE" icon="trophy">
    Provide `generic_asset_id`. Molecule queries live venues and routes the full quantity to whichever offers the best executable price.
  </Card>

  <Card title="SPLIT" icon="code-branch">
    Provide `generic_asset_id`. Molecule distributes the quantity across venues to optimise execution. The router never invents size.
  </Card>
</CardGroup>

## Idempotency

<Note>
  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`.
</Note>

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


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