# Order states and records

Every route reports one `state`, from nine values. Branch on `state`; `rawStatus` is for support. Then match what happened against your own books.

| `state` | Meaning | Who acts | Final |
| --- | --- | --- | --- |
| `pending` | Placed; no solver has committed | solver | no |
| `awaiting_deposit` | Selling: payout locked, user sends BTC | user | no |
| `in_progress` | The solver is filling | solver | no |
| `completed` | Buying: BTC sent. Selling: payout released | nobody | yes |
| `refundable` | Buying: no solver filled in time | user | no |
| `refunded` | The coins went back | nobody | yes |
| `cancelled` | Cancelled before anything moved | nobody | yes |
| `expired` | Selling and Solana: window closed | nobody | yes |
| `failed` | Selling, Solana and coin to coin: see `rawStatus` | Maxy support | yes |

An order is done for the user when their funds arrive. A buy, EVM or Solana, reads `completed` the moment `btcTxId` is set. A settlement is Maxy getting its own money back: nothing waits for it, and if it fails the swap still reads `completed`. Before the payment confirms, the solver may speed it up: same amount and address, a new `btcTxId`. Show the latest.

To cancel while `pending`: `POST /orders/{id}/cancel?chainId=8453` answers the call for the wallet to send. After a solver commits, it answers `409 order_state`.

## Reconcile

`GET /orders` lists the orders placed with your key, newest first. `format=csv` gives a spreadsheet.

```sh
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders?from=2026-11-01&to=2026-12-01"
```

```ts
const res = await fetch(`${BASE}/orders?from=2026-11-01&to=2026-12-01`, { headers: { 'x-maxy-key': KEY } });
const { orders, nextCursor } = await res.json();
```

```python
r = requests.get(f"{BASE}/orders", params={"from": "2026-11-01", "to": "2026-12-01"}, headers={"x-maxy-key": KEY})
orders, next_cursor = r.json()["orders"], r.json()["nextCursor"]
```

- Up to 100 a page, or 1,000 in a CSV. Follow `nextCursor` with `cursor=`.
- Filter by `state`, `wallet`, `externalId` or `externalCustomerId`.
- Send your own ids on `POST /orders`. Maxy stores them as given.
- An order stays listed for 30 days after it ends, so export monthly.

A month as a statement, in JSON, CSV or PDF: `GET /statements?month=2026-11`.

At month-end, export the month and join on `orderId`:

1. `completed`: `btcTxId` is the payment. Match the amount you showed.
2. `refunded`, `refundable`, `failed`: no BTC was paid.
3. In your books but not the export: look it up with `GET /status?txHash=`. That finds any Maxy order. If it answers `404`, Maxy has no such order.

To add an order placed another way: `POST /orders/watch`.

---
Source: https://maxy.co/docs/order-states-and-records (Maxy Docs › Orders › Follow an order)
