# Trading on a venue

Source: https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-trading
How a resting order on a Trading Venue becomes a fill: order types, escrow locks, amends and cancels, auctions, price bands and halts.

A [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue) is a tenant's own exchange for tokenised assets. This page explains how a resting order on it becomes a fill. What happens to the trade after the fill is in [Settlement: a fill is not delivery](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue#settlement-a-fill-is-not-delivery).

## Trading: how a resting order becomes a fill [#trading-how-a-resting-order-becomes-a-fill]

Every order is an EIP-712-signed intent, a typed structured message signed for the maker's wallet: by the custody provider after the investor's wallet verification for a custodial wallet, or by the investor's own wallet. The venue contract checks that signature, so it cannot place or change an order the maker's wallet did not sign. An order carries a type and a time in force, independently of each other.

| Order type | What it does |
| --- | --- |
| Limit | Rests at a stated price until it fills, expires, or is cancelled |
| Market | Matches immediately at the best available price |

| Time in force | What it does |
| --- | --- |
| Good-til-cancelled (GTC) | Stays resting until filled or cancelled. Unfilled auction remainders carry to the book by default. |
| Good-til-date (GTD) | Expires once the chain's latest block passes its signed expiry. New GTD orders past expiry are rejected, and a background pass expires resting GTD orders within seconds of the block passing expiry. |
| Day (DAY) | Rests until filled, cancelled or session close (automatically following early closes and holidays). Requires a trading calendar. |
| Immediate-or-cancel (IOC) | Fills immediately available quantity and cancels the remainder. |
| Fill-or-kill (FOK) | Fills its entire quantity immediately during continuous trading or cancels without trading (rejected during auctions). |

### Stop orders and market eligibility [#stop-orders-and-market-eligibility]

A stop order is a limit order with a server-enforced trigger price (not part of the signed digest). The venue reserves the full limit amount on entry while the order stays armed off-book until any trade print (including an auction uncross) trades at or through the trigger (at or below for a sell stop, at or above for a buy stop), at which point it enters the book as a limit order.

Intake refuses market stops, IOC/FOK stops, and stops triggered on the wrong side of the last trade. Armed stops survive halts, cancel on instrument suspension or delisting, and can be cancelled or expire normally. Public instruments support all order types and times in force, whereas private instruments accept limit orders only (GTC, plus GTD and DAY on continuous books).

If a stop fires while its trader or named recipient is suspended, closed or terminated in the venue's organisation, it never joins the book: the venue cancels it and releases its reservation. A suspension of the same account in another organisation leaves the stop alone.

### Amending resting orders [#amending-resting-orders]

Resting orders amend in two ways:

- **Reduce quantity at the same price:** Updates in place, preserving order ID, signature and time priority while releasing unspent escrow when the order closes.
- **Change price or increase quantity:** Requires a newly signed replacement order. The venue cancels the original (waiting for any unsettled partial fill if needed) and places the replacement at the back of the price-time queue using the unlocked free balance plus any shortfall.

If the replacement fails after cancelling the original, the venue returns HTTP 409 `ORDER_AMENDMENT_INCOMPLETE` ([DALP-12375](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference)) indicating whether the remainder is already free or still awaiting fill settlement. Retrying the identical signed replacement once unlocked places it cleanly (different terms return `TRADING_VENUE_ORDER_NOT_FOUND`). Both amend types log as replacements for drop copy.

### Escrow commitments, releases and parked fills [#escrow-commitments-releases-and-parked-fills]

Orders join the book only after their on-chain escrow commitment confirms (reverted or timed-out commitments reject the order permanently). Matching runs strictly by price, then arrival time. Each instrument controls whether participants see resting quantities and order counts beside each price level (venue operators see all attributes).

Cancellations, expiries, prunes and undone settlements unlock remainders to free escrow balance for withdrawal from **Balances**. Buy limit orders lock quote principal plus maximum signed fee (including on-chain VAT when enabled), unlocking any price-improvement surplus when the order closes.

When the chain refuses a fill (for example, due to compliance), the venue parks the fill and keeps the order locked until a venue operator retries or busts it.

For expiring orders (GTD, IOC, FOK), once `reclaimableFrom` passes, the owner can reclaim the lock to free balance from **Balances** or via the venue balances API (`503` if the escrow index lags, `ESCROW_LOCK_NOT_FOUND` if no commit exists). Reclaiming marks the parked fill closed (`lock-returned`), leaves the order `settlement-failed` and blocks retries while still allowing operator busts. GTC and DAY orders never expire, so they have no owner reclaim exit.

### Auctions, closing auctions and Trade-At-Last [#auctions-closing-auctions-and-trade-at-last]

Instruments run auctions at open (after a preopen with a randomised uncross window `uncrossWindowMs`), at the end of auction-only collection windows, or as a closing auction on public continuous instruments. Auction clearing follows the instrument's "Pre-open price rule":

- **Tie average (default):** Picks the price level maximising matched volume, then minimising unmatched volume, then averaging tied levels (subject to "Auction price rounding": "Block between price steps" default, "Nearest step, half up" or "Nearest step, half down").
- **Previous close reference:** Ranks by matched volume and smallest buy/sell imbalance, breaking ties by proximity to the previous official close (or listing reference price) without averaging.

Unfilled auction orders follow "Auction remainder" ("Carry to the book" or "Cancel remainders"), and fills execute in price-time priority at the clearing price.

Public continuous instruments can also end with a **Trade at last** post-session matching limit orders only at the last price (ignoring the price band, rejecting market/IOC/FOK orders and leaving the official close anchored to pre-session trades).

### Price bands, volatility interruptions and participant limits [#price-bands-volatility-interruptions-and-participant-limits]

Static or dynamic price bands keep limit orders, continuous fills and auction uncrosses within range (see [Change the price bands](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument#change-the-price-bands)). By default (`outOfBandCarryOver: close`), a band change closes out-of-band resting orders. Setting `suspend` moves them to `suspended` (keeping escrow locks and time priority) and reinstates them automatically if the band widens back over them.

An optional volatility interruption halts continuous matching when a fill would print past a basis-point threshold from the last trade or previous close, collects orders for the configured duration, and resumes via a single-price auction (reported on the instrument stream, drop copy and audit trail).

Order size and value limits apply at venue and instrument levels, with optional stricter overrides for retail, institutional and proprietary classes mapped from [Verification topics](https://docs.settlemint.com/docs/console/compliance/verification-topics) (or the wallet's "Client classification"), always enforcing the strictest applicable bound.

### Instrument lifecycle, halts and resume cut-off [#instrument-lifecycle-halts-and-resume-cut-off]

An instrument starts Pending until go-live checks complete, moves to Live, cycles between Live, Halted and Suspended under operator control, and ends permanently if Delisted (from any state).

Halts defer scheduled auctions and continuous opens until resume (or skip them if the session ends while halted). Instruments can configure a resume cut-off in minutes before session close: attempting to resume inside that window returns HTTP 409 `MARKET_RESUME_INSIDE_CUTOFF` ([DALP-174401](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference)).

[Figure] An instrument's own status, from creation to an optional permanent delisting. An instrument is created pending. It goes live once every listing precondition completes. From live, an operator can halt it, and from halted the operator can resume it back to live. Those two states cycle under operator control. From either live or halted, an operator can delist the instrument, and delisting is permanent: there is no path back from it. Labels: Pending; Live; operator; halts; operator; resumes; Halted; operator delists, permanent; Delisted.

An instrument's status: pending until every precondition completes, then live, with operator halt and resume and permanent delisting from either state.

