Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Trading Operations

WebSocket trading operations (place, replace, cancel orders)

All trading operations require authentication. See Connection Management for authentication details.

Error Responses

Any operation can return an error frame instead of its success response:

{
  "type": "error",
  "code": 4100,
  "message": "Insufficient margin: required 1000, available 500",
  "traderOrderId": 1705600000001,
  "orderId": 123456789,
  "instrument": "NVDA"
}

A 4107 rejection also carries safeLimitPrice: the worst limit price at which the reduce-only or stop-loss/take-profit order would still settle above maintenance margin. Resubmitting with that limit (or a better one) passes the check.

traderOrderId, orderId, and instrument echo back whatever the originating request carried, so a client with multiple in-flight requests can match an error to the request that caused it. Each field is present only when the request supplied it, and omitted entirely (never sent as null) otherwise:

Operation

traderOrderId

orderId

instrument

placeOrder

if supplied

— (not yet assigned)

yes

cancelOrder

if supplied

if supplied

yes

replaceOrder

if supplied

if supplied

yes

cancelAll

—

—

if scoped to one

auth / parse errors

—

—

—

These same correlation fields are also echoed on the success responses (orderPlaced, orderReplaced, orderCanceled, massCanceled), so you can correlate without relying on response ordering. Do not rely on response ordering: requests are pipelined per (wallet, instrument) lane and replies are emitted as each operation completes, so replies can arrive out of request order. Always correlate by traderOrderId/orderId.

placeOrder

Place a new order.

Authentication Required: Yes

Request

Note: The payload field contains the encoded Order struct (see Signatures - V2 Signature Format).

Stop-Loss & Take-Profit Orders:

SL/TP orders support two modes via the closePosition parameter:

Managed Orders (closePosition: true):

Unmanaged Orders (closePosition: false):

Signature Rules:

  • Managed (closePosition: true): Sign Order struct with size: "0", flags with managed bit set (see Order Flags)

  • Unmanaged (closePosition: false): Sign Order struct with actual signed quantity, flags without managed bit

  • Order struct must include deadline and flags fields (see Signatures - Orders)

See Order Types for managed vs unmanaged behavior, OCO, and auto-cancellation.

Request Fields

Field
Type
Required
Description

traderOrderId

u64

No

Optional client-supplied order identifier. Max 36 bits (≤ 68,719,476,735)

orderType

string

Yes

Limit, StopLimit, StopLoss, TakeProfit

side

string

Yes

Buy or Sell

instrument

string

Yes

Instrument symbol (e.g., NVDA)

quantity

string

Conditional

Order quantity (null for managed SL/TP, required otherwise)

closePosition

boolean

SL/TP: Yes

SL/TP only, required for SL/TP orders: true = managed (auto-sync qty), false = unmanaged (fixed qty)

reduceOnly

boolean

No

Order may only reduce an existing position. Must match the signed flag (bit 1) — the signed value is what is enforced. Requires an open position

instructions

string[]

No

["PostOnly"] for a post-only order

timeInForce

string

Yes

GTC, GTD, IOC, FOK, DAY

limitPrice

string

Yes

Required for every order type (all orders carry a price bound)

stopPrice

string

Conditional

Required for StopLimit, StopLoss, TakeProfit

expiryDate

i64

Conditional

Required for GTD (Unix timestamp in milliseconds)

marginMode

string

Yes

Cross or Isolated. Must match the signed order's margin flag (bit 0).

signature

Object

Yes

EIP-712 signed order payload

Order Type Requirements

Order Type

limitPrice

stopPrice

timeInForce

Limit

Required

-

GTC, GTD, IOC, FOK, DAY

StopLimit

Required

Required

GTC, GTD, IOC, FOK, DAY

StopLoss

Required

Required

IOC, FOK

TakeProfit

Required

Required

IOC, FOK

These are the only accepted order types — every order carries a price bound. For market-style immediate execution, place a crossing Limit IOC with your slippage tolerance as the limit price; for a stop-market, use StopLimit with an aggressive limit price.

Minimum order size: $5 notional.

For signature construction, see Signatures - Orders.

Post-Only Orders

A post-only order only adds liquidity. If it would match immediately, it is cancelled.

  • Supported on Limit and StopLimit with GTC, GTD or DAY.

  • Not part of the signature.

  • If it would match, you receive orderPlaced, then a Cancelled execution report.

  • That cancel carries cancelReason: "PostOnly".

  • replaceOrder keeps it.

  • Shown as instructions on execution reports, open orders and historic orders.

Success Response

traderOrderId is echoed back only when it was supplied on the request (see Error Responses for correlation details).

Common Errors

Code
Cause

4000

Invalid request (missing required fields, invalid order parameters)

4001

Signature verification failed

4002

Invalid nonce

4029

Rate limit exceeded

4030

Invalid order type

4031

Invalid time in force

4032

Invalid or missing price

4100

Insufficient margin

4101

Order too small (below $5 minimum notional)

4102

Max leverage exceeded

4103

OI cap exceeded

4107

Limit would fill below maintenance margin (see safeLimitPrice)

5000

Internal error

5001+

Exchange error (5001 + exchange code)

5002

Risk engine unavailable

replaceOrder

Atomically cancel existing order and place new one.

Authentication Required: Yes

Request

Note: The payload field contains the encoded Order struct with new order parameters.

Request Fields

Field
Type
Required
Description

orderId

u64

Conditional

Exchange order ID to replace (required if traderOrderId omitted)

traderOrderId

u64

Conditional

Client-supplied order ID of the order to replace (required if orderId omitted). Max 36 bits (≤ 68,719,476,735)

instrument

string

Yes

Instrument symbol

quantity

string

Yes

New order quantity

timeInForce

string

Yes

New time in force

limitPrice

string

Conditional

New limit price (if applicable)

stopPrice

string

Conditional

New stop price (if applicable)

expiryDate

i64

Conditional

New expiry date for GTD

marginMode

string

Yes

Cross or Isolated (must match the original order and the signed order's margin flag).

signature

Object

Yes

EIP-712 signed order payload (same format as placeOrder)

Notes:

  • At least one of orderId or traderOrderId must be provided to identify the order being replaced

  • Signature authorizes the new order parameters (same format as placeOrder)

  • Side and order type are inherited from the original order

  • Only resting orders can be replaced; immediate-execution orders (Limit IOC/FOK, StopLoss, TakeProfit legs in flight) cannot

For signature construction, see Signatures - Orders.

Success Response

traderOrderId is echoed back only when it was supplied on the request.

Replace Managed Stop-Loss:

Replace Unmanaged Stop-Loss:

Important:

  • Managed SL/TP: Use quantity: null and sign Order struct with size: "0" and managed flag set

  • Unmanaged SL/TP: Provide quantity and sign Order struct with actual signed quantity and managed flag unset

  • The closePosition mode cannot be changed on replace - you must use the same signing pattern (flags) as the original order

Common Errors

Code
Cause

4000

Invalid request (order not owned by wallet)

4041

Order not found

4001

Signature verification failed

4002

Invalid nonce

4029

Rate limit exceeded

4030

Invalid order type (unsupported type, or order cannot be replaced)

4031

Invalid time in force

4032

Invalid or missing price

4100

Insufficient margin

4102

Max leverage exceeded

4103

OI cap exceeded

5000

Internal error

5001+

Exchange error

5002

Risk engine unavailable

cancelOrder

Cancel an existing order.

Authentication Required: Yes

Request

Note: The payload field contains the encoded OrderCancel struct (type discriminator 0x01). See Signatures - Cancel Order for struct details.

Request Fields

Field
Type
Required
Description

orderId

u64

Conditional

Exchange order ID (required if traderOrderId not provided)

traderOrderId

u64

Conditional

Client order ID (optional if orderId provided). Max 36 bits (≤ 68,719,476,735)

instrument

string

Yes

Instrument symbol

signature

Object

Yes

EIP-712 signed cancel payload

Notes: At least one of orderId or traderOrderId must be provided. Order ownership is validated before cancellation. Please sign the same identifier sent in the cancel request.

For signature construction, see Signatures - Cancel Order.

Success Response

traderOrderId is echoed back only when it was supplied on the request.

Common Errors

Code
Cause

4000

Invalid request (order not owned by wallet, missing order ID)

4041

Order not found

4001

Signature verification failed

4002

Invalid nonce

4029

Rate limit exceeded

5000

Internal error

5001+

Exchange error

cancelAll

Cancel all orders, optionally filtered by instrument.

Authentication Required: Yes

Request

Cancel all orders across all instruments:

Cancel orders for specific instrument:

Note: The payload field contains the encoded SimpleSignaturePayload (type discriminator 0x02). See Signatures - Mass Cancel for struct details.

Request Fields

Field
Type
Required
Description

targetScope

string

Yes

All to cancel all orders, or Instrument to cancel only specified instrument

instrument

string

Conditional

Instrument symbol (REQUIRED if targetScope is Instrument)

signature

Object

Yes

EIP-191 signed auth payload (same format as authenticate)

Important: targetScope is required. Use "All" to cancel all orders across all instruments, or "Instrument" with an instrument to cancel orders for a specific instrument only.

For signature construction, see Signatures - Mass Cancel.

Success Response

instrument and targetScope are echoed from the request so a client with several in-flight cancelAlls can tell which one this answers. instrument is omitted for an all-instruments cancel (targetScope: "All").

Common Errors

Code
Cause

4000

Invalid request

4001

Signature verification failed

4002

Invalid nonce

4029

Rate limit exceeded

5000

Internal error

5001+

Exchange error

transferMargin

Move collateral between cross margin and a market's isolated margin, without leaving the WebSocket session. Identical semantics to POST /api/margin/transfer.

Request

Request Fields

Field
Type
Required
Description

amount

string

Yes

Transfer amount (human-readable)

instrument

string

Yes

Instrument symbol of the isolated market

direction

string

Yes

crossToIsolated or isolatedToCross

signature

Object

Yes

EIP-712 MarginTransfer signature, type 0x08 — flag bit 0 carries the source account's mode (see Signatures - Margin Transfers)

Success Response

The ack only means the transfer was submitted. The settlement result arrives asynchronously as a TransferMargin message on the Execution Reports stream.

Trader Order ID

traderOrderId is an optional client-supplied identifier for an order.

Requirements

  • Maximum width: 36 bits — any u64 up to 68,719,476,735 (2^36 − 1) is accepted. Values larger than this are rejected. Within that range, choose whatever encoding you prefer (monotonic counter, timestamp-derived, random, etc.).

  • Optional on placeOrder.

  • If supplied, the value must be unique per instrument across your own active and historical orders (you cannot reuse a traderOrderId you have previously submitted on the same instrument from the same wallet).

Using traderOrderId for subsequent operations

Once an order is placed with a traderOrderId, that value can be used in place of the exchange orderId when:

PreviousConnection Management
NextExecution Reports

Last updated