Place Order

POST /orders submits an encrypted order. Auth: Authorization: Bearer <access_token>.

REST wire body

Plaintext order JSON is rejected. Official SDKs HPKE-encrypt the logical input and send:

{
  "header": {
    "symbol_id": 1,
    "request_type": "place",
    "nonce": 1,
    "body_length": 256,
    "correlation_id": "340282366920938463463374607431768211"
  },
  "encrypted_body": "<base64 ciphertext>",
  "encapped_key": "<base64 32-byte HPKE key>",
  "request_id": 42
}

request_id must be a non-zero u64; correlation_id, when supplied, is a decimal u128.

Logical SDK input

Field	Required	Description
`symbol_id`	Yes	Numeric instrument id
`side`	Yes	`BUY` or `SELL`
`order_type`	Yes	`MARKET`, `LIMIT`, `PEG`, `STOP_MARKET`, `STOP_LIMIT`
`quantity` / `quote_notional`	Exactly one	Base quantity or quote notional; both must not be supplied
`price`	Conditional	Required for `LIMIT` and `STOP_LIMIT`; not valid for `PEG`
`time_in_force`	Yes	`GTC`, `IOC`, `FOK`, `GTD`; `MARKET` is `IOC` only
`expiry_time`	`GTD` only	Nanosecond epoch; invalid on other TIFs
`peg_offset_bps`	`PEG` only	Signed offset from the sequencer Pyth mark; there is no `peg_reference`
`trigger_price`	Stop only	Required for `STOP_MARKET` and `STOP_LIMIT`
`take_profit_price`, `stop_loss_price`	No	Attached TP/SL mark triggers
`slippage_bps`	No	Maximum walk versus mark for `MARKET`/`STOP_MARKET`; default is 5%
`post_only`	No	Must rest; invalid for market, peg, stop-market, IOC, or FOK
`reduce_only`	No	May only reduce an existing opposite-side position
`stp_mode`	No	Self-trade prevention mode
`min_fill_size`	No	Minimum fill clip
`correlation_id`	Yes	Client order/demultiplexing id

{
  "symbol_id": 1,
  "side": "BUY",
  "order_type": "LIMIT",
  "price": "95000",
  "quantity": "0.1",
  "time_in_force": "GTC",
  "post_only": true,
  "reduce_only": false,
  "stp_mode": "CANCEL_TAKER",
  "correlation_id": "340282366920938463463374607431768211"
}

Official SDKs accept numeric place inputs in language-native types and encode price / quantity (and related trigger / TP/SL / quote-notional fields) as instrument-scaled decimal strings on the sealed protobuf wire.

REST response

The HTTP API wraps the encrypted ACK in the standard envelope:

{
  "code": 0,
  "data": {
    "encrypted": true,
    "message_type": "ACK",
    "encrypted_body": "<base64 ciphertext>",
    "nonce": 1,
    "fencing_epoch": 7,
    "correlation_id": "340282366920938463463374607431768211",
    "request_id": 42
  },
  "timestamp": "2026-04-20T10:30:00.123Z",
  "request_id": "req_..."
}

The SDK decrypts the ACK locally. Acceptance is not a fill; consume encrypted Order Updates. A client-order mapping may be registered after a successful place, but the protocol makes no 24-hour retention or reuse guarantee.

Timeout and retry safety

A timeout means the client did not receive a definitive result; it does not prove that the venue rejected the request. Do not immediately submit an identical place as a new order. Reconnect, subscribe to the private orders channel, obtain a fresh open-orders snapshot, and reconcile by venue order id / correlation id before deciding whether to retry.

correlation_id identifies a request attempt. It is not a durable public idempotency key. client_order_id mappings are useful for lookup/cancel where supported, but the current protocol does not publish a retention or safe-reuse window.

Precision

Read tick_size, lot_size, price_decimals, quantity_decimals, and max_order_size from Get Instruments. Normalize price and quantity before placing. Do not rely on binary floating-point rounding to produce a valid tick or lot; reject or explicitly round according to your strategy and log the normalized values.