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

# Orders

> Place, track, and cancel orders through one API.

`POST /v1/orders` is the canonical trade. Mithril risk-checks it, signs it with
your attached venue credentials, submits it, and maps the venue's response to one
status model.

## Place an order

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.trymithril.com/v1/orders \
    -H "Authorization: Bearer $MITHRIL_API_KEY" \
    -H "Content-Type: application/json" \
    -H "idempotency-key: $(uuidgen)" \
    -d '{
      "subaccount_id": "sub_...",
      "market_id": "mkt_...",
      "token_id": "7194...",
      "action": "buy",
      "order_type": "limit",
      "quantity": "5",
      "price": "0.40"
    }'
  ```

  ```python Python theme={null}
  import uuid

  order = s.post(
      f"{BASE}/v1/orders",
      headers={"idempotency-key": str(uuid.uuid4())},
      json={
          "subaccount_id": sub_id,
          "market_id": market["id"],
          "token_id": token_id,
          "action": "buy",
          "order_type": "limit",
          "quantity": "5",
          "price": "0.40",
      },
  ).json()
  print(order["id"], order["status"])
  ```
</CodeGroup>

### Request fields

<ParamField body="subaccount_id" type="string" required>
  Which subaccount (and its credentials + limits) to trade under.
</ParamField>

<ParamField body="market_id" type="string" required>
  The unified `mkt_` market identifier.
</ParamField>

<ParamField body="token_id" type="string" required>
  The outcome token to trade, read from the market's orderbook.
</ParamField>

<ParamField body="action" type="string" required>
  `buy` or `sell`.
</ParamField>

<ParamField body="order_type" type="string" required>
  `limit` or `market`.
</ParamField>

<ParamField body="quantity" type="string" required>
  Decimal number of shares, as a string (e.g. `"5"`).
</ParamField>

<ParamField body="price" type="string">
  Limit price — a probability in `(0, 1]` as a string. Required for `limit`
  orders.
</ParamField>

<Note>
  The `idempotency-key` header is **required**. See [Idempotency](/concepts/idempotency).
</Note>

### Response

Both placing and fetching an order return the same `OrderView`:

```json theme={null}
{
  "id": "ord_...",
  "subaccount_id": "sub_...",
  "exchange": "polymarket",
  "market_id": "mkt_...",
  "token_id": "7194...",
  "side": "yes",
  "action": "buy",
  "order_type": "limit",
  "quantity": "5",
  "price": "0.40",
  "status": "open",
  "traded_qty": "0",
  "average_price": "0",
  "fees_paid": "0",
  "remaining_qty": "5",
  "external_ref": "0xabc...",
  "created_at": "2026-07-16T14:30:00Z",
  "updated_at": "2026-07-16T14:30:01Z",
  "submitted_at": "2026-07-16T14:30:01Z"
}
```

<ResponseField name="status" type="string">
  Lifecycle state — see the table below.
</ResponseField>

<ResponseField name="traded_qty / remaining_qty" type="string">
  Filled and outstanding size.
</ResponseField>

<ResponseField name="average_price" type="string">
  Weighted average fill price so far.
</ResponseField>

<ResponseField name="reject_reason" type="string">
  Present only when `status` is `rejected` — e.g. a guardrail message.
</ResponseField>

## Track an order

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.trymithril.com/v1/orders/ord_... \
    -H "Authorization: Bearer $MITHRIL_API_KEY"
  ```

  ```python Python theme={null}
  order = s.get(f"{BASE}/v1/orders/{order['id']}").json()
  print(order["status"])
  ```
</CodeGroup>

### Order statuses

| Status      | Meaning                                     |
| ----------- | ------------------------------------------- |
| `submitted` | Sent to the venue, awaiting acknowledgement |
| `open`      | Resting on the book                         |
| `partial`   | Partially filled, remainder resting         |
| `filled`    | Fully filled                                |
| `cancelled` | Cancelled (by you or the venue)             |
| `rejected`  | Refused by a guardrail or the venue         |

## Cancel

<CodeGroup>
  ```bash cURL theme={null}
  # Cancel one
  curl -X POST https://api.trymithril.com/v1/orders/ord_.../cancel \
    -H "Authorization: Bearer $MITHRIL_API_KEY"

  # Cancel everything on a subaccount
  curl -X POST https://api.trymithril.com/v1/orders/cancel_all \
    -H "Authorization: Bearer $MITHRIL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "subaccount_id": "sub_..." }'
  ```

  ```python Python theme={null}
  s.post(f"{BASE}/v1/orders/{order['id']}/cancel")
  ```
</CodeGroup>

<Tip>
  A cancel only marks the order terminal once the venue confirms — so the API
  never reports a cancellation that didn't actually happen.
</Tip>

## List orders

```bash theme={null}
curl "https://api.trymithril.com/v1/orders?limit=50" \
  -H "Authorization: Bearer $MITHRIL_API_KEY"
```

<Card title="Next: Smart execution" icon="wand-magic-sparkles" href="/guides/smart-execution">
  Work large orders into thin books instead of clipping the print.
</Card>