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

# Place your first order

> Buy YES on the round that is currently trading.

Orders need a `trade`-scope key. Keys you create from Settings have it.

## Prices are ticks

A binary contract settles at 100¢ if the outcome happens and 0¢ if it does not.
Prices are integers from **1 to 99**, in cents, representing the market's implied
probability. Buying YES at `47` costs 47¢ per contract and pays 100¢ if YES wins.

Quantities are whole contracts.

## Place a limit order

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/portfolio/orders
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "client_order_id": "42",
  "market_id": 66,
  "side": "buy",
  "outcome": "yes",
  "type": "limit",
  "tick": 47,
  "qty": 500,
  "tif": "gtc"
}
```

The response reports what **actually happened**, not an acknowledgement. The
call is held until the order is sequenced, so by the time you get a `201` the
order has really rested or filled:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "order_id": "16777291",
  "client_order_id": "42",
  "status": "partially_filled",
  "seq": "182391",
  "filled_qty": 100,
  "resting_qty": 400,
  "fills": [{ "tick_yes": 47, "qty": 100, "path": "direct" }]
}
```

`status` is one of `resting`, `partially_filled`, `executed`, or `canceled`
(with a `reason`).

<Note>
  Balance and fee changes are deliberately absent from this response. Placement
  runs on a lane that excludes ledger events. Read
  `GET /v1/portfolio/balance` afterwards, or subscribe to the
  [private WebSocket channel](/websocket/channels).
</Note>

## `client_order_id` is your idempotency key

You choose it, and it must be unique per order. It is what makes retries safe.

<Warning>
  **On a timeout, retry with the same `client_order_id`.**

  A `504` means the request timed out, not that the order was rejected — it may
  still have been sequenced. Retrying with the same `client_order_id` either
  returns the original outcome or places it once. At most one order results.

  Retrying with a *new* id after a timeout is how you accidentally place two
  orders.
</Warning>

## Order types

| `type`   | Behaviour                                            |
| -------- | ---------------------------------------------------- |
| `limit`  | Rests at `tick` unless it crosses. Needs `tif`.      |
| `market` | Executes immediately against the book; forced `ioc`. |

For market **buys**, `max_cost` (in cents) is **required** — it bounds what you
can spend, since a market order has no price limit. Market orders also accept
`worst_tick` to bound the price you will accept; it defaults to 99 for buys and
1 for sells.

Time in force for limit orders: `gtc` (rest until cancelled), `gtt` (needs
`expiry_ts` in nanoseconds), `ioc` (fill what you can, cancel the rest), `fok`
(all or nothing).

Useful flags, all default `false`: `post_only` (never take), `reduce_only` (only
shrink a position), `cancel_on_pause`.

## Cancel

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
DELETE /v1/portfolio/orders/{order_id}      # one order
DELETE /v1/portfolio/orders                 # mass-cancel
```

Rounds are 60 seconds long, so anything still resting when the round freezes is
cancelled for you. `cancel_on_pause` is worth setting if you do not want orders
surviving a pause.

## Unknown fields are rejected

The request schema is closed: an unrecognised field returns `400 unknown_field`
rather than being ignored. A typo'd `post_onlyy` fails loudly instead of
silently not applying.

## Then check your position

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/portfolio/positions
GET /v1/portfolio/fills
GET /v1/portfolio/balance
```