Trading Lifecycle

Time Seventeen trading is defined over Outcomes, not over Markets directly, and keeps four lifecycles distinct: command acknowledgement, order state, execution/fill state, and settlement state. Collapsing these into a single “success” state is a documentation defect.

Economic intent

• BUY increases exposure to the named Outcome at or below the limit price.
• SELL reduces or shorts exposure only where account/market rules permit, at or above the limit price.
• Side is always paired with an explicit outcome_id; clients never infer YES/NO from bid/ask field position.
• A market order is represented as a protected marketable limit order with FOK or FAK and an explicit worst acceptable price. Time Seventeen does not define an unbounded market-order primitive.

Time in force

post_only=true is valid only with resting-capable GTC/GTD. If it would cross the book, the order is rejected with no fill — this is the maker-order guarantee.

Maker/taker, self-trade prevention, and idempotency

• Each Fill records a maker/taker role for fee attribution.
• Self-trade prevention (STP) prevents an account’s own resting and aggressing orders from matching each other, with account-configured modes cancel_taker, cancel_maker, and cancel_both. Fills that occurred before STP triggers remain valid fills and are not rolled back.
• Every mutating command requires a client idempotency key; an identical retry returns the original result, while a reused key with a different body is rejected.

Four distinct lifecycles

received
  ├── rejected
  └── validated
       ├── open ── partially_filled ── filled
       │    ├── cancel_pending ── canceled
       │    ├── expired
       │    └── suspended ── open/canceled
       ├── filled                 (immediate full execution)
       ├── partially_filled ── canceled  (FAK remainder)
       └── canceled               (unfilled FAK/FOK)

1. Command acknowledgement — the API confirms it received and validated (or rejected) the request. This is not execution.
2. Order state — the order’s position in the lifecycle above (open, partially_filled, canceled, expired, suspended, and so on).
3. Execution/fill state — immutable Fill records produced as the order matches. Fills are never rewritten; corrections create explicit adjustment records.
4. Settlement state — the on-chain/custodial finalization of Fills into redeemable value, with its own independent state machine (pending, submitted, confirmed, failed, reversed, redeemable, redeemed).

A FOK failure produces zero fills. A FAK order can produce one or more fills plus a canceled remainder. A cancellation acknowledgement records the matching-engine cutoff; fills with an earlier engine sequence may still validly arrive during a cancel race, which is a documented outcome rather than a bug.

Positions and balances

Positions aggregate settled and unsettled quantities separately, so an account can distinguish exposure that has cleared from exposure still awaiting settlement. Balances distinguish available, reserved, pending settlement, and total.

Where to go next

• API Reference → Orders for the full validation pipeline, rejection matrix, and batch/amend/cancel contract.
• API Reference → Fills, Positions, and Settlement for the downstream resources.
• Getting Started → Trading workflow for a worked, non-executable walkthrough.