Orders

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

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"
  }'

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"])

Request fields

string

required

Which subaccount (and its credentials + limits) to trade under.

string

required

The unified mkt_ market identifier.

string

required

The outcome token to trade, read from the market’s orderbook.

string

required

buy or sell.

string

required

limit or market.

string

required

Decimal number of shares, as a string (e.g. "5").

string

Limit price — a probability in (0, 1] as a string. Required for limit orders.

The idempotency-key header is required. See Idempotency.

Response

Both placing and fetching an order return the same OrderView:

{
  "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"
}

string

Lifecycle state — see the table below.

string

Filled and outstanding size.

string

Weighted average fill price so far.

string

Present only when status is rejected — e.g. a guardrail message.

Track an order

curl https://api.trymithril.com/v1/orders/ord_... \
  -H "Authorization: Bearer $MITHRIL_API_KEY"

order = s.get(f"{BASE}/v1/orders/{order['id']}").json()
print(order["status"])

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

# 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_..." }'

s.post(f"{BASE}/v1/orders/{order['id']}/cancel")

A cancel only marks the order terminal once the venue confirms — so the API never reports a cancellation that didn’t actually happen.

List orders

curl "https://api.trymithril.com/v1/orders?limit=50" \
  -H "Authorization: Bearer $MITHRIL_API_KEY"

Next: Smart execution

Work large orders into thin books instead of clipping the print.

Get started

Clients & SDKs

Core concepts

Guides

Place an order

Request fields

Response

Track an order

Order statuses

Cancel

List orders

Next: Smart execution

​Place an order

​Request fields

​Response

​Track an order

​Order statuses

​Cancel

​List orders

Next: Smart execution

Place an order

Request fields

Response

Track an order

Order statuses

Cancel

List orders