Orders

This guide covers OBSDN order types, execution behavior, time-in-force policies, and order flags.

The JSON examples below show the wire fields used by POST /orders (PlaceOrderRequest). Required fields like mkt_id, nonce, and sig are omitted from each example for brevity — see Getting Started for the full payload.

Two wire-format rules apply throughout:

• Enums use the full proto name. Send ORDER_SIDE_BUY, not BUY; short forms are rejected.
• uint64/int64 fields are JSON strings. nonce, exp_ts, and sched_ts exceed JavaScript's safe integer range, so they're quoted on the wire.

Wire Field Reference

Defaults when fields are omitted

Order Types

LIMIT

A limit order rests on the order book at a specified price until filled or canceled.

{
  "ot": "ORDER_TYPE_LIMIT",
  "sd": "ORDER_SIDE_BUY",
  "px": 50000,
  "sz": 0.1,
  "tif": "TIME_IN_FORCE_GTC"
}

• Execution: only fills at the specified price or better
• Book: rests on the order book if not immediately filled
• Use case: when you want to control execution price

MARKET

A market order executes immediately at the best available price.

{
  "ot": "ORDER_TYPE_MARKET",
  "sd": "ORDER_SIDE_BUY",
  "px": 50000,
  "sz": 0.1,
  "tif": "TIME_IN_FORCE_IOC"
}

• Execution: fills immediately against resting orders
• Book: never rests on the order book
• px: required; acts as a slippage cap — a buy will not match makers priced above it, a sell will not match makers priced below it
• tif: must be TIME_IN_FORCE_FOK or TIME_IN_FORCE_IOC; GTC and GTT are not permitted
• po: not permitted
• Use case: when speed of execution matters more than price

STOP

A stop order activates when the trigger price is reached.

{
  "ot": "ORDER_TYPE_STOP",
  "sd": "ORDER_SIDE_SELL",
  "px": 49000,
  "sz": 0.1,
  "stop_px": 49500,
  "stop_t": "STOP_TYPE_STOP_LOSS",
  "stop_px_type": "STOP_PRICE_TYPE_MARK"
}

Stop Subtypes

Trigger Sources

When stop_px_type is omitted (or STOP_PRICE_TYPE_UNSPECIFIED), last price is used.

TWAP (Algorithmic)

TWAP time-slices a parent order across scheduled sub-orders. Submit TWAP batches via POST /orders/twap — mkt_id, sd, stp, and ro come from the batch envelope; each sub-order in sub_ords is individually signed and carries its own px, sz, nonce, sig, and sched_ts.

• Execution: splits execution over time instead of taking full size at once
• Use case: large orders where minimizing market impact matters more than immediate completion

{
  "mkt_id": "BTC-PERP",
  "sd": "ORDER_SIDE_BUY",
  "stp": "SELF_TRADE_PREVENTION_CANCEL_TAKER",
  "ro": false,
  "sub_ords": [
    {
      "px": 50000,
      "sz": 0.1,
      "nonce": "1700000000000000000",
      "sig": "0x...",
      "sched_ts": "1700000060000000000"
    },
    {
      "px": 50000,
      "sz": 0.1,
      "nonce": "1700000000000000001",
      "sig": "0x...",
      "sched_ts": "1700000120000000000"
    }
  ]
}

Batch validation rules (any violation returns 400):

• All sub-orders must share the same px and sz (uniform slicing).
• nonce values must be strictly increasing across the batch.
• sched_ts intervals between consecutive sub-orders must be positive, equal, and divisible by 60 seconds.
• The first sched_ts must be at least 10 seconds in the future.
• At most 100 sub-orders per batch.

Time-in-Force (TIF)

Time-in-force determines how long an order remains active.

GTC (Good Til Canceled)

Order remains active until fully filled or manually canceled.

{ "tif": "TIME_IN_FORCE_GTC" }

• Default behavior for most orders
• Order stays on the book indefinitely

IOC (Immediate or Cancel)

Fills as much as possible immediately, cancels the rest.

{ "tif": "TIME_IN_FORCE_IOC" }

• Partial fills allowed
• Unfilled portion is immediately canceled
• Use case: fill what you can now, don't leave orders on book

FOK (Fill or Kill)

Must fill entirely or not at all.

{ "tif": "TIME_IN_FORCE_FOK" }

• No partial fills
• Use case: all-or-nothing execution required

GTT (Good Til Time)

Order expires at a specified time.

{
  "tif": "TIME_IN_FORCE_GTT",
  "exp_ts": "1735689600000000000"
}

• exp_ts is Unix nanoseconds, sent as a JSON string
• Must be in the future and at most 30 days from now (otherwise the request is rejected)
• Order is canceled automatically at the expiration time

Timing Controls

• sched_ts: scheduled activation time in nanoseconds (TWAP sub-orders only). Ignored for other order types.
• exp_ts: expiration time in nanoseconds (GTT only)
• await: synchronous processing flag for MARKET/LIMIT submissions; the request waits for matching-engine processing before returning

Example (GTT limit order with synchronous submit):

{
  "ot": "ORDER_TYPE_LIMIT",
  "sd": "ORDER_SIDE_BUY",
  "px": 50000,
  "sz": 0.1,
  "tif": "TIME_IN_FORCE_GTT",
  "exp_ts": "1735689600000000000",
  "await": true
}

Special Flags

ro — reduce-only

Only reduces an existing position, never increases it.

{ "ro": true }

• Order rejected if it would open or increase a position
• Use case: closing positions without risk of accidental reversal

po — post-only

Order must rest on the book (be a maker), never take liquidity.

{ "po": true }

• Order rejected if it would immediately match
• Guarantees maker fee
• Use case: market making, fee optimization

stp — Self-Trade Prevention

Prevents your orders from matching against each other.

{ "stp": "SELF_TRADE_PREVENTION_CANCEL_TAKER" }

When stp is omitted or sent as SELF_TRADE_PREVENTION_UNSPECIFIED, the engine applies SELF_TRADE_PREVENTION_CANCEL_TAKER — STP cannot be disabled.

Use case: prevent self-matches when running multiple bots or accounts.

Order Status Lifecycle

LIMIT / MARKET

  PENDING -----------> OPEN -----------> DONE
  |                                    ^
  +------------------------------------+

STOP / TWAP

  UNTRIGGERED ------> OPEN -----------> DONE
  |                   |                ^
  |                   +----------------+
  +------------------------------------+

Partial fills are not a separate status — filled_sz updates while the order remains OPEN. The order moves to DONE when fully filled or canceled.

Bracket Orders

Create a parent entry order with linked take-profit and/or stop-loss children:

POST /orders/group

{
  "grp_t": "ORDER_GROUP_TYPE_BRACKET",
  "ords": [
    {
      "mkt_id": "BTC-PERP",
      "ot": "ORDER_TYPE_LIMIT",
      "sd": "ORDER_SIDE_BUY",
      "px": 50000,
      "sz": 0.1,
      "nonce": "1700000000000000000",
      "sig": "0x..."
    },
    {
      "mkt_id": "BTC-PERP",
      "ot": "ORDER_TYPE_STOP",
      "sd": "ORDER_SIDE_SELL",
      "stop_px": 52000,
      "stop_t": "STOP_TYPE_TAKE_PROFIT",
      "sz": 0.1,
      "ro": true,
      "tif": "TIME_IN_FORCE_IOC",
      "nonce": "1700000000000000001",
      "sig": "0x..."
    },
    {
      "mkt_id": "BTC-PERP",
      "ot": "ORDER_TYPE_STOP",
      "sd": "ORDER_SIDE_SELL",
      "stop_px": 48000,
      "stop_t": "STOP_TYPE_STOP_LOSS",
      "sz": 0.1,
      "ro": true,
      "tif": "TIME_IN_FORCE_IOC",
      "nonce": "1700000000000000002",
      "sig": "0x..."
    }
  ],
  "await": false
}

When the parent fills, the children transition from ORDER_STATUS_UNTRIGGERED to ORDER_STATUS_OPEN. When one child triggers and fills, the other is automatically canceled.

Set await: true to block the response until the parent has been processed by the matching engine (only effective when the parent is ORDER_TYPE_MARKET or ORDER_TYPE_LIMIT).

Bracket validation rules

The backend rejects the request if any of these are violated:

Order Sides

Examples

Limit Buy with Post-Only

{
  "ot": "ORDER_TYPE_LIMIT",
  "sd": "ORDER_SIDE_BUY",
  "px": 50000,
  "sz": 0.1,
  "tif": "TIME_IN_FORCE_GTC",
  "po": true
}

Stop-Loss to Close Long Position

{
  "ot": "ORDER_TYPE_STOP",
  "sd": "ORDER_SIDE_SELL",
  "px": 48000,
  "sz": 0.1,
  "stop_px": 48500,
  "stop_t": "STOP_TYPE_STOP_LOSS",
  "stop_px_type": "STOP_PRICE_TYPE_MARK",
  "ro": true
}

Market Order with IOC

{
  "ot": "ORDER_TYPE_MARKET",
  "sd": "ORDER_SIDE_BUY",
  "px": 50000,
  "sz": 0.1,
  "tif": "TIME_IN_FORCE_IOC"
}

Next Steps

• Place an order
• Create bracket orders
• View order history