> For the complete documentation index, see [llms.txt](https://docs.anchored.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.anchored.finance/trading-api/reference/status-model.md).

# Status Model

This page explains how to interpret order and cash operation states.

## Order State Model

```mermaid
flowchart TB
    A[Build calldata or send] --> B[Tx submitted]
    B --> C[Tx mapping]
    C --> D[Order ID backfilled]
    D --> E{Order type}
    E -->|Market| F[placing]
    E -->|Limit| G[placing or open]
    F --> H[Execution result]
    G --> I{Fill or cancel}
    I -->|fill| H
    I -->|cancel| J[canceling]
    H --> K[historyOrder]
    J --> K
```

## API Objects

| Object         | Meaning                                               | Integration use                            |
| -------------- | ----------------------------------------------------- | ------------------------------------------ |
| `mapping`      | API key to tx/order linkage                           | Transaction accepted / waiting for indexer |
| `openOrder`    | On-chain order still active or canceling              | Open order or cancel in progress           |
| `historyOrder` | Settled, canceled, rejected, expired, or failed order | Final result                               |

## Order Statuses

| Status           | Meaning                             | Suggested handling |
| ---------------- | ----------------------------------- | ------------------ |
| `Init`           | Mapping or order initialized        | Pending            |
| `Pending`        | Processing                          | Pending            |
| `New`            | Order recognized                    | Open               |
| `Partial filled` | Some quantity filled                | Partially filled   |
| `Filled`         | Fully filled                        | Filled             |
| `Canceled`       | Canceled                            | Canceled           |
| `Expired`        | Expired by TIF/execution rules      | Expired            |
| `Rejected`       | Rejected by execution or validation | Failed / rejected  |
| `Failed`         | Processing failed                   | Failed             |

On-chain transient statuses:

| Status      | Meaning                   | Suggested handling |
| ----------- | ------------------------- | ------------------ |
| `placing`   | Order placement is active | Placing            |
| `canceling` | Cancel request is active  | Canceling          |

## Market Order Expectations

Market orders are intended for immediate execution, but settlement is still async.

```mermaid
flowchart LR
    A[Market order placed] --> B[Execution result]
    B --> C{Fill size}
    C -->|full| D[Filled]
    C -->|partial| E[Partial filled plus refund]
    C -->|zero| F[No fill plus refund]
```

Integration guidance:

* Do not show market order as final at tx mining time.
* Treat `placing` as pending until settlement appears.
* Refresh portfolio after final status.

## Limit Order Expectations

Limit orders can remain open.

```mermaid
flowchart TB
    A[Limit order placed] --> B[Open]
    B --> C{Execution event}
    C -->|fill| D[Filled or partial]
    C -->|cancel request| E[Canceling]
    C -->|expiry| F[Expired]
    E --> G[Canceled or partial cancel settlement]
```

Integration guidance:

* Show open limit orders separately from final history.
* Allow cancel only for open limit orders that are not already canceling.
* Current production contracts accept only `DAY` limit orders; treat expiry/fill/cancel transitions as asynchronous backend and settlement behavior after the order is placed.

## Cash Operation State Model

Cash operations use Cashier buffers for instant settlement when possible. If the relevant buffer cannot cover the operation safely, the operation follows the queued settlement path. See [../cash/buffer-mechanism.md](/trading-api/cash-operations/buffer-mechanism.md).

```mermaid
flowchart TB
    A[Cash request tx] --> B[Mapping]
    B --> C[Operation created]
    C --> D{Instant buffer}
    D -->|available| E[settled]
    D -->|not available| F[processing]
    F --> G[Final cash settlement]
    G --> E
    E --> H[Portfolio updated]
```

## Cash Statuses

| `operationStatus` | Meaning                         | Suggested handling |
| ----------------- | ------------------------------- | ------------------ |
| `requested`       | Operation created               | Requested          |
| `processing`      | Waiting on settlement path      | Processing         |
| `settled`         | `mUSD` applied or cash paid out | Complete           |
| `closed`          | Closed lifecycle                | Closed             |

`mappingStatus` reuses the order mapping status enum. Use it to explain whether the tx was recorded and recognized.

## Portfolio Refresh Rules

Refresh portfolio after:

* Deposit operation reaches `settled`.
* Withdrawal operation reaches `settled` or `closed`.
* Order moves from `openOrder` to `historyOrder`.
* Cancel settlement completes.

Treat the status endpoint as authoritative for lifecycle and the portfolio endpoint as authoritative for balances.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.anchored.finance/trading-api/reference/status-model.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.