# Order lifecycle

The SRC-20 order state machine on StampDEX, every state, every transition, and what each state means for the buyer and the seller.

> Source: bitcoinuniverseio/stampdex (private application source), orders module, OrderStatus enum, order expiry crons. Applicable release continuous deployment, verify with GET /api/version. Last verified 2026-09-01. Chain bitcoin/mainnet.

import OrderStateMachine from '../../../components/OrderStateMachine.astro';

An order is not a request that either succeeds or fails. It is a state machine, and
every state has a name the product shows you, a meaning, and a place where the money
is. This page draws the machine.

**Local candidate, 6 September 2026. NO-GO. Not deployed.** These source changes have no real-wallet, native-network or browser acceptance witness. Earlier captures do not verify this candidate.

<OrderStateMachine />

## Every state

| State | What happened | Who can act |
| --- | --- | --- |
| **Draft** | The listing is prepared but the seller has not signed it. Buyers never see it | The seller, by signing |
| **Open** | The listing is live on the book at its exact amount and price | Any buyer, or the seller by cancelling |
| **Pending** | A buyer locked the listing and is paying. Only an unpaid reservation may release; an associated payment stays in recovery | That one buyer |
| **Awaiting transfer** | The payment is broadcast. StampDEX waits for confirmation and an index check | Nobody. Bitcoin decides |
| **Settling** | The settlement worker is verifying the balance and broadcasting the token transfer | Nobody |
| **Awaiting confirmation** | The token transfer is broadcast and needs one confirmation | Nobody |
| **Filled** | The engine recorded finalization. Current completion also needs retained delivery and receipt evidence | Nobody. It is done |
| **Cancelled** | The seller cancelled before a sale | Nobody |
| **Expired** | The listing, or a buyer's lock, ran out of time | Nobody |
| **Failed** | The payment confirmed but the token balance could not be verified. Funds are held in escrow | An operator |

## The transitions that surprise people

**An unpaid reservation may return to Open.** A known payment or uncertain submission must first reconcile the same order and lock. A lost response does not prove that no payment occurred.

**Replacement keeps linked order IDs.** SRC-20 repricing, splitting and repair use the existing guarded replacement routes. A rejected replacement signature must leave the old listing intact. Refresh both linked versions after the action. See
[Change a listing price](/docs-stampdex/guides/change-a-listing-price/).

**Failed is not the end of the money.** It is the machine refusing to release funds
against a balance it could not verify. See [Recovery](/docs-stampdex/concepts/recovery/).

## Execution and recovery

The candidate adds executionSummary to the existing order read. It separates payment, token transfer and delivery, shows source freshness and chooses the next supported action. A transaction ID alone does not prove receipt. Old rows with missing identity or observations remain unresolved. Reopen the saved order after reload before starting another payment.

## Reading an order over the API

```bash
curl "https://stamp.api.bitcoinuniverse.io/api/v1/orders?tick=SEX&status=open"
```

Every order carries its `status`, and `priceSatsPerToken * amount` always equals
`totalPriceSats`. The API refuses to serve a listing whose stored numbers disagree, so
a listing you can read is a listing whose arithmetic holds. See
[Orders endpoints](/docs-stampdex/api/orders/).

## Related

- [Where your funds are](/docs-stampdex/concepts/custody/)
- [Settlement lifecycle](/docs-stampdex/concepts/settlement-lifecycle/)
- [Order states reference](/docs-stampdex/reference/order-states/)