# Order book

HermesTrade uses a **central limit order book** (CLOB) for all prediction market trading. This page explains how the CLOB works, what order types are available, how orders move through their lifecycle, and what negRisk means for multi-outcome markets.

***

## How the order book works

The order book matches buyers and sellers directly by **price-time priority**:

1. The best (highest) bid and the best (lowest) ask are always matched first
2. Among orders at the same price, earlier orders are filled first
3. Every price reflects a real trader's intent

This means tighter spreads in liquid markets and transparent price discovery. In thin markets, spreads are wider because prices depend on actual resting orders.

Each outcome token has its own independent order book, identified by its `token_id` (from `clobTokenIds` in the market schema).

***

## The order book snapshot

`GET /book?token_id=<id>` returns an `OrderBookSummary`:

| Field              | Description                                           |
| ------------------ | ----------------------------------------------------- |
| `asset_id`         | The token ID this book belongs to                     |
| `market`           | The market/condition identifier                       |
| `bids`             | List of `{price, size}` buy orders, best price first  |
| `asks`             | List of `{price, size}` sell orders, best price first |
| `last_trade_price` | Price of the most recent fill                         |
| `tick_size`        | Minimum price increment for this market               |
| `min_order_size`   | Minimum order size in shares                          |
| `max_order_size`   | Maximum order size in shares                          |
| `neg_risk`         | Whether this market uses the negRisk capital model    |

Use `POST /books` to fetch order books for multiple tokens in a single request.

***

## Order types

When you place an order via `POST /order`, the `order_type` field controls how it behaves. Use the exact enum values shown below.

{% tabs %}
{% tab title="GTC — Good Till Canceled" %}
The order rests in the book until it is either fully filled or you explicitly cancel it. This is the most common order type for limit orders.

**Use when:** you have a target price and are willing to wait for it.
{% endtab %}

{% tab title="GTD — Good Till Date" %}
Like GTC, but the order automatically expires at a specified Unix timestamp (set in the `expiration` field). Useful when your price view is time-sensitive — for example, before a scheduled game starts.

**Use when:** your thesis is only valid up to a specific point in time.
{% endtab %}

{% tab title="FOK — Fill Or Kill" %}
The order must be filled **completely and immediately** or it is rejected in its entirety. No partial fills; no resting in the book.

**Use when:** you need a guaranteed full fill at your price or nothing at all.
{% endtab %}

{% tab title="FAK — Fill And Kill" %}
Fill as much as possible immediately at the specified price; cancel whatever cannot be filled right now. Partial fills are accepted.

**Use when:** you want immediate execution without risking an unfilled order sitting in the book.
{% endtab %}
{% endtabs %}

***

## Order fields

An order submitted to `POST /order` includes:

| Field        | Description                                             |
| ------------ | ------------------------------------------------------- |
| `tokenID`    | The outcome token you are trading (from `clobTokenIds`) |
| `side`       | `BUY` or `SELL`                                         |
| `price`      | Limit price in USDC (e.g., `"0.65"` for 65 cents)       |
| `size`       | Number of shares                                        |
| `orderType`  | `GTC` \| `GTD` \| `FOK` \| `FAK`                        |
| `expiration` | Unix timestamp (required for GTD; use `"0"` for GTC)    |
| `feeRateBps` | Fee rate locked in at submission                        |
| `maker`      | Your proxy wallet address                               |
| `signature`  | EIP-712 signature of the order                          |

***

## Order status lifecycle

Once submitted, an order transitions through the following statuses. These appear in the `status` field of `OpenOrder` (from `GET /orders`) and `SendOrderResponse`.

| Status                     | Meaning                                                          |
| -------------------------- | ---------------------------------------------------------------- |
| `LIVE`                     | Resting in the book, awaiting a match                            |
| `MATCHED`                  | Fully filled; awaiting on-chain confirmation                     |
| `CANCELED`                 | Manually canceled by the trader                                  |
| `CANCELED_MARKET_RESOLVED` | Auto-canceled because the market closed and resolved             |
| `SYSTEM_CLEARED`           | Removed by the system — typically due to insufficient balance    |
| `INVALID`                  | Rejected at submission (bad signature, price out of range, etc.) |

{% hint style="warning" %}
When a market reaches resolution, all `LIVE` orders are automatically canceled with status `CANCELED_MARKET_RESOLVED`. If you are running automated strategies, do not expect open orders to survive market closure.
{% endhint %}

***

## Spread and midpoint

The **bid-ask spread** is the gap between the best ask and the best bid:

```
spread = best_ask − best_bid
```

The **midpoint** is the average of the two:

```
midpoint = (best_ask + best_bid) / 2
```

Both are available directly from the CLOB API:

* `GET /spread?token_id=<id>` — returns the current spread
* `GET /midpoint?token_id=<id>` — returns the current midpoint

Use batch endpoints (`POST /spreads`, `GET /midpoints`) when working with multiple tokens simultaneously.

***

## Tick size

The **tick size** is the minimum price increment for a market — the smallest step between valid limit prices. Most markets use a tick size of `$0.01`.

```
GET /tick-size?token_id=<id>
```

Or via path parameter: `GET /tick-size/{tokenID}`. Orders submitted with prices that are not multiples of the tick size will be rejected.

***

## negRisk

On multi-outcome events where exactly one outcome can win, HermesTrade supports a **negRisk** capital model. When `neg_risk: true` appears in an `OrderBookSummary` (or `negRiskAugmented: true` on a `Market`, or `negRisk: true` on an `Event`), the market participates in a shared collateral mechanism.

The economic intuition: in a race with five competitors, the probabilities of all five winning must sum to 1. negRisk exploits this constraint to allow traders to post collateral more efficiently — rather than locking $1.00 per share per market, capital can be shared across correlated positions in the same event.

{% hint style="warning" %}
In negRisk markets, holding both YES and NO shares for the same outcome does not simply cancel out as it would in a standard market. The redemption mechanics are more complex. Unless you understand the negRisk collateral model in detail, avoid holding offsetting positions in negRisk markets.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hermestrade.xyz/core-concepts/order-book.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.