# Order Flow

This page describes the full lifecycle of an order on Pitchcast, from the moment a user submits it to the moment it settles on-chain.

## Steps

### 1. User signs the order

The user specifies the parameters of their order in the Pitchcast interface: price (as an implied probability), size (in USDC), direction (buy YES or buy NO), and optionally an expiry timestamp after which the order is no longer valid.

The interface constructs the order as a structured message and requests a signature from the user's connected Solana wallet (Phantom, Backpack, or Solflare). The user signs with their private key. Their funds are not moved at this stage.

### 2. Signed order is submitted to the operator

The signed order is sent to the off-chain CLOB operator. The operator stores it in the order book alongside other open orders. The user's order is now visible in the market's order book.

### 3. Matching engine finds a counterparty

The operator's matching engine continuously scans the order book for matching orders. Two orders match when:

* They are on opposite sides (one is buying YES, one is buying NO, or one is buying and one is selling)
* Their prices are compatible (the buyer's limit price meets or exceeds the seller's limit price)

When a match is found, the operator prepares a settlement transaction.

### 4. Operator submits the matched pair on-chain

The operator submits the matched order pair to the Pitchcast settlement program on Solana. The transaction includes both signed orders and the proposed settlement path (NORMAL, MINT, or MERGE).

### 5. On-chain program verifies and settles

The settlement program verifies:

* Both order signatures are valid
* The orders have not already been filled or cancelled
* The proposed settlement path is correct for these orders
* All collateral constraints are satisfied

If all checks pass, the program executes settlement. Shares and USDC move between the relevant accounts in a single atomic transaction. If any check fails, the transaction is rejected and no state changes.

{% hint style="info" %}
Steps 3 through 5 happen automatically. Users do not need to take any action after placing an order. Once matched and settled, the position appears in the user's portfolio.
{% endhint %}

## Order states

| State                | Description                                                    |
| -------------------- | -------------------------------------------------------------- |
| **Open**             | Submitted to the operator, waiting to be matched               |
| **Partially filled** | A portion of the order has been matched and settled            |
| **Filled**           | The full order has been matched and settled                    |
| **Cancelled**        | Cancelled by the user before being matched                     |
| **Expired**          | The expiry timestamp passed before the order was fully matched |

## Order types

Pitchcast supports two order types:

* **Limit order**: executes only at the specified price or better. Placed in the order book and waits for a counterparty.
* **Market order**: executes immediately at the best available price in the order book. May fill across multiple price levels if the order size exceeds the best available depth.


---

# 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.pitchcast.xyz/trading/order-flow.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.