API Reference

Replace

Method Name

private/replace

Cancel an existing order with nonce or order_id and create new order with different order_id in a single RPC call.

If the cancel fails, the new order will not be created.
If the cancel succeeds but the new order fails, the old order will still be cancelled.
Required minimum session key permission level is admin

Parameters

amount string required
Order amount in units of the base
direction string required
Order direction
enum buy sell
instrument_name string required
Instrument name
limit_price string required
Limit price in quote currency.
This field is still required for market orders because it is a component of the signature. However, market orders will not leave a resting order in the book in case of a partial fill.
max_fee string required
Max fee per unit of volume, denominated in units of the quote currency (usually USDC).Order will be rejected if the supplied max fee is below the estimated fee for this order.
nonce integer required
Unique nonce defined as (e.g. 1695836058725001, where 001 is the random number).Note, using a random number beyond 3 digits will cause JSON serialization to fail.
signature string required
Ethereum signature of the order
signature_expiry_sec integer required
Unix timestamp in seconds. Order signature becomes invalid after this time, and the system will cancel the order.Expiry MUST be at least 5 min from now.
signer string required
Owner wallet address or registered session key that signed order
subaccount_id integer required
Subaccount ID
expected_filled_amount string
Optional check to only create new order if old order filled_amount is equal to this value.
label string
Optional user-defined label for the order
mmp boolean
Whether the order is tagged for market maker protections (default false)
nonce_to_cancel integer
Cancel order by nonce (choose either order_id or nonce).
order_id_to_cancel string
Cancel order by order_id (choose either order_id or nonce).
order_type string
Order type:
- limit: limit order (default)
- market: market order, note that limit_price is still required for market orders, but unfilled order portion will be marked as cancelled
enum limit market
reduce_only boolean
If true, the order will not be able to increase position's size (default false). If the order amount exceeds available position size, the order will be filled up to the position size and the remainder will be cancelled. This flag is only supported for market orders or non-resting limit orders (IOC or FOK)
referral_code string
Optional referral code for the order
reject_timestamp integer
UTC timestamp in ms, if provided the matching engine will reject the order with an error if reject_timestamp < server_time. Note that the timestamp must be consistent with the server time: use public/get_time method to obtain current server time.
time_in_force string
Time in force behaviour:
- gtc: good til cancelled (default)
- post_only: a limit order that will be rejected if it crosses any order in the book, i.e. acts as a taker order
- fok: fill or kill, will be rejected if it is not fully filled
- ioc: immediate or cancel, fill at best bid/ask (market) or at limit price (limit), the unfilled portion is cancelled
Note that the order will still expire on the signature_expiry_sec timestamp.
enum gtc post_only fok ioc
trigger_price string
(Required for trigger orders) Index or Market price to trigger order at
trigger_price_type string
(Required for trigger orders) Trigger with Mark Price. Index price type no supported yet.
enum mark index
trigger_type string
(Required for trigger orders) Stop-loss or Take-profit
enum stoploss takeprofit

Response

id string or integer required
result object required
result.cancelled_order object required
Order that was cancelled
result.cancelled_order.amount string required
Order amount in units of the base
result.cancelled_order.average_price string required
Average fill price
result.cancelled_order.cancel_reason string required
If cancelled, reason behind order cancellation
enum user_request mmp_trigger insufficient_margin signed_max_fee_too_low cancel_on_disconnect ioc_or_market_partial_fill session_key_deregistered subaccount_withdrawn compliance trigger_failed
result.cancelled_order.creation_timestamp integer required
Creation timestamp (in ms since Unix epoch)
result.cancelled_order.direction string required
Order direction
enum buy sell
result.cancelled_order.filled_amount string required
Total filled amount for the order
result.cancelled_order.instrument_name string required
Instrument name
result.cancelled_order.is_transfer boolean required
Whether the order was generated through private/transfer_position
result.cancelled_order.label string required
Optional user-defined label for the order
result.cancelled_order.last_update_timestamp integer required
Last update timestamp (in ms since Unix epoch)
result.cancelled_order.limit_price string required
Limit price in quote currency
result.cancelled_order.max_fee string required
Max fee in units of the quote currency
result.cancelled_order.mmp boolean required
Whether the order is tagged for market maker protections
result.cancelled_order.nonce integer required
Unique nonce defined as (e.g. 1695836058725001, where 001 is the random number)
result.cancelled_order.order_fee string required
Total order fee paid so far
result.cancelled_order.order_id string required
Order ID
result.cancelled_order.order_status string required
Order status
enum open filled cancelled expired untriggered
result.cancelled_order.order_type string required
Order type
enum limit market
result.cancelled_order.quote_id string or null required
Quote ID if the trade was executed via RFQ
result.cancelled_order.signature string required
Ethereum signature of the order
result.cancelled_order.signature_expiry_sec integer required
Signature expiry timestamp
result.cancelled_order.signer string required
Owner wallet address or registered session key that signed order
result.cancelled_order.subaccount_id integer required
Subaccount ID
result.cancelled_order.time_in_force string required
Time in force
enum gtc post_only fok ioc
result.cancelled_order.replaced_order_id string or null
If replaced, ID of the order that was replaced
result.cancelled_order.trigger_price string or null
(Required for trigger orders) Index or Market price to trigger order at
result.cancelled_order.trigger_price_type string or null
(Required for trigger orders) Trigger with Index or Mark Price
enum mark index
result.cancelled_order.trigger_reject_message string or null
(Required for trigger orders) Error message if error occured during trigger
result.cancelled_order.trigger_type string or null
(Required for trigger orders) Stop-loss or Take-profit.
enum stoploss takeprofit
result.create_order_error object or null
Optional. Returns error during new order creation
result.create_order_error.code integer required
result.create_order_error.message string required
result.create_order_error.data string or null
result.order object or null
New order that was created
result.order.amount string required
Order amount in units of the base
result.order.average_price string required
Average fill price
result.order.cancel_reason string required
If cancelled, reason behind order cancellation
enum user_request mmp_trigger insufficient_margin signed_max_fee_too_low cancel_on_disconnect ioc_or_market_partial_fill session_key_deregistered subaccount_withdrawn compliance trigger_failed
result.order.creation_timestamp integer required
Creation timestamp (in ms since Unix epoch)
result.order.direction string required
Order direction
enum buy sell
result.order.filled_amount string required
Total filled amount for the order
result.order.instrument_name string required
Instrument name
result.order.is_transfer boolean required
Whether the order was generated through private/transfer_position
result.order.label string required
Optional user-defined label for the order
result.order.last_update_timestamp integer required
Last update timestamp (in ms since Unix epoch)
result.order.limit_price string required
Limit price in quote currency
result.order.max_fee string required
Max fee in units of the quote currency
result.order.mmp boolean required
Whether the order is tagged for market maker protections
result.order.nonce integer required
Unique nonce defined as (e.g. 1695836058725001, where 001 is the random number)
result.order.order_fee string required
Total order fee paid so far
result.order.order_id string required
Order ID
result.order.order_status string required
Order status
enum open filled cancelled expired untriggered
result.order.order_type string required
Order type
enum limit market
result.order.quote_id string or null required
Quote ID if the trade was executed via RFQ
result.order.signature string required
Ethereum signature of the order
result.order.signature_expiry_sec integer required
Signature expiry timestamp
result.order.signer string required
Owner wallet address or registered session key that signed order
result.order.subaccount_id integer required
Subaccount ID
result.order.time_in_force string required
Time in force
enum gtc post_only fok ioc
result.order.replaced_order_id string or null
If replaced, ID of the order that was replaced
result.order.trigger_price string or null
(Required for trigger orders) Index or Market price to trigger order at
result.order.trigger_price_type string or null
(Required for trigger orders) Trigger with Index or Mark Price
enum mark index
result.order.trigger_reject_message string or null
(Required for trigger orders) Error message if error occured during trigger
result.order.trigger_type string or null
(Required for trigger orders) Stop-loss or Take-profit.
enum stoploss takeprofit
result.trades array of objects or null
List of trades executed by the created order
result.trades[].direction string required
Order direction
enum buy sell
result.trades[].index_price string required
Index price of the underlying at the time of the trade
result.trades[].instrument_name string required
Instrument name
result.trades[].is_transfer boolean required
Whether the trade was generated through private/transfer_position
result.trades[].label string required
Optional user-defined label for the order
result.trades[].liquidity_role string required
Role of the user in the trade
enum maker taker
result.trades[].mark_price string required
Mark price of the instrument at the time of the trade
result.trades[].order_id string required
Order ID
result.trades[].quote_id string or null required
Quote ID if the trade was executed via RFQ
result.trades[].realized_pnl string required
Realized PnL for this trade
result.trades[].realized_pnl_excl_fees string required
Realized PnL for this trade using cost accounting that excludes fees
result.trades[].subaccount_id integer required
Subaccount ID
result.trades[].timestamp integer required
Trade timestamp (in ms since Unix epoch)
result.trades[].trade_amount string required
Amount filled in this trade
result.trades[].trade_fee string required
Fee for this trade
result.trades[].trade_id string required
Trade ID
result.trades[].trade_price string required
Price at which the trade was filled
result.trades[].transaction_id string required
The transaction id of the related settlement transaction
result.trades[].tx_hash string or null required
Blockchain transaction hash
result.trades[].tx_status string required
Blockchain transaction status
enum requested pending settled reverted ignored timed_out

Example

{request_example_shell}
{request_example_javascript}
{request_example_python}

The above command returns JSON structured like this:

{response_example_json}