Time in Force

time_in_force (TIF) controls how long an order is eligible to execute before it expires or is cancelled.

Public SDK / API strings are GTC, IOC, FOK, and GTD (protobuf TIME_IN_FORCE_GTD = 4).

Available Options

TIF	Description
`GTC`	Good Till Cancelled — rests in the book until filled or manually cancelled.
`IOC`	Immediate or Cancel — fills what it can immediately; cancels the unfilled remainder.
`FOK`	Fill or Kill — limit orders only; must fill completely and immediately or execute no fills.
`GTD`	Good Till Date/Time — rests until `expiry_time` (nanosecond epoch) and is then auto-cancelled.

GTC

{
  "symbol": "BTC-USDC-PERP",
  "side": "BUY",
  "order_type": "LIMIT",
  "quantity": "0.1",
  "price": "95000",
  "time_in_force": "GTC"
}

GTD

Requires expiry_time as a nanosecond epoch timestamp.

{
  "symbol": "BTC-USDC-PERP",
  "side": "BUY",
  "order_type": "LIMIT",
  "quantity": "0.1",
  "price": "95000",
  "time_in_force": "GTD",
  "expiry_time": 1839975000000000000
}

Expiry is enforced at matching time — an order will not fill after expiry_time even if a match was otherwise possible. Expired orders emit a cancelled event with cancel_reason: "EXPIRED" (trade ACK / catalog may also surface GTD_EXPIRED / code 2026 — see Orders Channel and Error Codes).

IOC

Required for MARKET; also supported by aggressive LIMIT orders.

{
  "symbol": "BTC-USDC-PERP",
  "side": "BUY",
  "order_type": "MARKET",
  "quantity": "0.1",
  "time_in_force": "IOC"
}

Unfilled remainder is auto-cancelled with cancel_reason: "IOC_REMAINDER".

FOK

Use on LIMIT when partial fills are unacceptable. MARKET, PEG, and stop orders do not accept FOK.

{
  "symbol": "BTC-USDC-PERP",
  "side": "BUY",
  "order_type": "LIMIT",
  "quantity": "0.1",
  "price": "95000",
  "time_in_force": "FOK"
}

If the full size cannot be filled immediately, the order is rejected (no fills occur) with reject_reason: "INSUFFICIENT_LIQUIDITY" (or ACK code FOK_NOT_FILLED / 2025).

PEG, STOP_MARKET, and STOP_LIMIT accept only GTC or GTD.

TIF vs Execution Attributes

time_in_force controls when an order is eligible. It is distinct from Execution Attributes, such as min_fill_size, post_only, and reduce_only.