Cancelling & Managing Orders¶

Objective¶

Master the STATUS, ORDERS, and CANCEL commands for understanding gateway state, inspecting resting orders, and managing the order lifecycle.

Background reading

Prerequisites¶

Chapters 01–07 completed.
At least one connected trader gateway with resting orders to manage.

Exercise 1: Cancel a Resting Order¶

Place an order and then cancel it:

[TRADER01]> NEW|SYM=TSLA|SIDE=BUY|TYPE=LIMIT|QTY=100|PRICE=248.00|TIF=DAY|TAG=CXL-ORDER-001

Note the order_id, then:

[TRADER01]> CANCEL|ID=<order_id>|RTAG=CXL-REST-001

Expected: cancellation confirmed.

RTAG identifies this cancel request. The engine echoes it on the CANCELLED response or rejected ACK, which makes retries and concurrent cancel tests easier to audit. The original order TAG is echoed separately, so a client can tell which order was acted on and which cancel request completed.

Checkpoint: order cancelled; ORDERS no longer lists it as resting.

Exercise 2: Cancel a Partially Filled Order¶

Place a large limit buy at an aggressive price (to get a partial fill from the MM):
```
[TRADER01]> NEW|SYM=AAPL|SIDE=BUY|TYPE=LIMIT|QTY=1000|PRICE=150.10|TIF=DAY
```

After partial fill, cancel the remainder:

 [TRADER01]> CANCEL|ID=<order_id>|RTAG=CXL-PARTIAL-001

Expected: the unfilled portion is cancelled; the filled portion remains executed.

Checkpoint: cancel succeeds; filled qty preserved.

Exercise 3: Compare STATUS and ORDERS¶

Place a fresh resting order so the gateway has something to inspect:

[TRADER01]> NEW|SYM=MSFT|SIDE=BUY|TYPE=LIMIT|QTY=25|PRICE=419.00|TIF=DAY

First run STATUS:

[TRADER01]> STATUS

STATUS gives a quick gateway/session summary: gateway ID, known symbols, cached order counts by lifecycle state, cached quote legs, and position symbols. It is useful for a fast health check, but it is not the detailed order table.

Now inspect the actual orders:

[TRADER01]> ORDERS

ORDERS is the gateway command for detailed order inspection. It displays order ID, symbol, side, type, TIF, price, quantity, remaining quantity, and status for orders belonging to your gateway.

Use STATUS when you need a quick health pulse. Use ORDERS when you are debugging one specific order lifecycle.

Checkpoint: STATUS shows summary counts; ORDERS shows the full order row and ID.

Exercise 4: Inspect Resting Order Details¶

[TRADER01]> ORDERS

Find your order in the table. The response includes:

symbol, side, type, price, qty
remaining quantity
status (NEW, PARTIAL, FILLED, CANCELLED, REJECTED, EXPIRED)
tif, last update time

Checkpoint: ORDERS returns full details for each resting order.

Exercise 5: Cancel a Non-Existent Order¶

[TRADER01]> CANCEL|ID=DOES_NOT_EXIST|RTAG=CXL-MISSING-001

Expected: rejection, shown in the console as REJECTED DOES_NOT_EXIST code=ORDER_NOT_FOUND rtag=CXL-MISSING-001 Order not found (REJECT_CODE is the field's name on the wire).

Checkpoint: error message returned cleanly.

Exercise 6: Cancel Another Gateway's Order¶

Try cancelling an order belonging to TRADER02:

[TRADER01]> CANCEL|ID=<trader02_order_id>|RTAG=CXL-NOTOWNER-001

Expected: rejection — you can only cancel your own orders: code=NOT_OWNER Cannot cancel an order owned by another gateway.

Checkpoint: cross-gateway cancel rejected.

Exercise 7: Admin Kill Switch¶

From the admin gateway, cancel all orders for a specific gateway:

[GW_ADMIN|ADMIN]> KILL|GW=TRADER01

All of TRADER01's resting orders are cancelled.

Or cancel all orders for a specific symbol across all gateways:

[GW_ADMIN|ADMIN]> CANCEL_SYM|SYM=TSLA

Checkpoint: admin commands successfully cancel orders.

Exercise 8: Inspect SYMBOLS Metadata from Gateway¶

Request the symbol catalog:

[TRADER01]> SYMBOLS

The table shows each symbol's tick size and its market-maker obligation settings (enforced or not, maximum spread in ticks, minimum quoted quantity) — the parts of the configuration a trader needs while trading.

Checkpoint: you can explain how SYMBOLS complements config-file inspection during operations.

Order Lifecycle Summary¶

stateDiagram-v2
    [*] --> REJECTED : refused on entry
    [*] --> NEW : accepted
    NEW --> PARTIAL : partial fill
    NEW --> FILLED : full fill
    NEW --> CANCELLED : cancel, kill switch
    NEW --> EXPIRED : end of its time in force
    PARTIAL --> FILLED : remaining filled
    PARTIAL --> CANCELLED : cancel remainder
    PARTIAL --> EXPIRED : remainder expires

EXPIRED is the engine ending an order because its time in force ran out — a DAY order at the close, an ATO/ATC order after its auction — as opposed to CANCELLED, which is someone's decision.

Reflection¶

Why does the operator's KILL|GW=<gateway_id> cancel every order for an entire gateway rather than requiring one CANCEL per order? In what operational scenario (think: a runaway bot or a disconnected trader) does that bulk-kill behavior matter most?