Method Name
private/algo_order
private/algo_orderCreates a TWAP algo order. The order is stored in the database and
executed in slices by the AlgoOrderWorker.
NOTE:
- Not exposed in docs; users submit via private/order with algo_type field
- WS auto-routes private/order here when algo_type is present
- order_id and conn_id are injected by the WS handler
Required minimum session key permission level is admin
Parameters
| algo_duration_secintegerrequired Total execution window in seconds |
| algo_num_slicesintegerrequired Number of child executions to split the order into |
| algo_typestringrequired Algo order type: twap enum twap |
| amountstringrequired Order amount in units of the base |
| conn_idstringrequired Connection ID of websocket client |
| directionstringrequired Order direction enum buysell |
| instrument_namestringrequired Instrument name |
| limit_pricestringrequired 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_feestringrequired Max fee PER contract, denominated in USDC. For resting orders (maker orders), max_fee must be > 2 x max(taker_fee, maker_fee) x spot_price + extra_fee / amount.For crossing orders (taker order), max_fee must be > maker max_fee + base_fee / fill_amount. Note, in this calculation, regardless of the custom account taker / maker fees, the standard taker / maker fees are used. The max(limit_price, index_price) is used to calculate the notional volume. |
| nonceintegerrequired Unique nonce defined as (UTC_timestamp in ms)(random_number_up_to_3_digits) (e.g. 1695836058725001, where 001 is the random number). Note, using a random number beyond 3 digits will cause JSON serialization to fail. |
| order_idstringrequired Order Id provided by WS client |
| signaturestringrequired Ethereum signature of the order |
| signature_expiry_secintegerrequired 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. |
| signerstringrequired Owner wallet address or registered session key that signed order |
| subaccount_idintegerrequired Subaccount ID |
| clientstring Client that submitted the order |
| extra_feestring Extra fee in USDC added to the total final fee paid by user and directly sent to client / builder (must be between 0.000001 and 1000 USDC). The referral_code field must also be filled out. See Builder Fee page in docs for more info. |
| is_atomic_signingboolean Used by vaults to determine whether the signature is an EIP-1271 signature. |
| labelstring Optional user-defined label for the order |
| mmpboolean Whether the order is tagged for market maker protections (default false) |
| order_typestring 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 cancelledenum limitmarket |
| reduce_onlyboolean 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_codestring Optional referral code for the order |
| reject_post_onlyboolean If true (default), post-only orders that would cross the book are rejected. If false, the limit price is adjusted to be 1 tick away from the BBO instead of rejecting. |
| reject_timestampinteger 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_forcestring 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 cancelledNote that the order will still expire on the signature_expiry_sec timestamp.enum gtcpost_onlyfokioc |
| trigger_pricestring (Required for trigger orders) "index" or "mark" price to trigger order at |
| trigger_price_typestring (Required for trigger orders) Trigger with "mark" price as "index" price type not supported yet. enum markindex |
| trigger_typestring (Required for trigger orders) "stoploss" or "takeprofit" enum stoplosstakeprofit |
Response
| idstring or integerrequired |
| resultobjectrequired |
| result.orderobjectrequired |
| result.order.amountstringrequired Order amount in units of the base |
| result.order.average_pricestringrequired Average fill price |
| result.order.cancel_reasonstringrequired If cancelled, reason behind order cancellation enum user_requestmmp_triggerinsufficient_marginsigned_max_fee_too_lowcancel_on_disconnectioc_or_market_partial_fillsession_key_deregisteredsubaccount_withdrawncompliancetrigger_failedvalidation_failedalgo_completed |
| result.order.creation_timestampintegerrequired Creation timestamp (in ms since Unix epoch) |
| result.order.directionstringrequired Order direction enum buysell |
| result.order.filled_amountstringrequired Total filled amount for the order |
| result.order.instrument_namestringrequired Instrument name |
| result.order.is_transferbooleanrequired Whether the order was generated through private/transfer_position |
| result.order.labelstringrequired Optional user-defined label for the order |
| result.order.last_update_timestampintegerrequired Last update timestamp (in ms since Unix epoch) |
| result.order.limit_pricestringrequired Limit price in quote currency |
| result.order.max_feestringrequired Max fee PER contract, denominated in USDC.Max fee must be > 2 x max(taker_fee, maker_fee) x spot_price + extra_fee / amount.If the order crosses the book, it must be >= 2 x max(taker_fee, maker_fee) x spot_price + base_fee / fill_amount + extra_fee / amount.Note, in this calculation, regardless of the account taker / maker fees, the standard taker / maker fees are used. |
| result.order.mmpbooleanrequired Whether the order is tagged for market maker protections |
| result.order.nonceintegerrequired Unique nonce defined as (UTC_timestamp in ms)(random_number_up_to_3_digits) (e.g. 1695836058725001, where 001 is the random number) |
| result.order.order_feestringrequired Order fee paid so far |
| result.order.order_idstringrequired Order ID |
| result.order.order_statusstringrequired Order status enum openfilledcancelledexpireduntriggeredalgo_active |
| result.order.order_typestringrequired Order type enum limitmarket |
| result.order.quote_idstring or nullrequired Quote ID if the trade was executed via RFQ |
| result.order.signaturestringrequired Ethereum signature of the order |
| result.order.signature_expiry_secintegerrequired Signature expiry timestamp |
| result.order.signerstringrequired Owner wallet address or registered session key that signed order |
| result.order.subaccount_idintegerrequired Subaccount ID |
| result.order.time_in_forcestringrequired Time in force enum gtcpost_onlyfokioc |
| result.order.algo_duration_secinteger or null Total execution window in seconds |
| result.order.algo_num_slicesinteger or null Number of child executions |
| result.order.algo_slices_completedinteger or null Number of slices executed so far |
| result.order.algo_typestring or null Algo order type (twap or vwap) enum twap |
| result.order.extra_feestring or null (Optional) Extra fee in USDC added to the total final fee paid by user (must be between 0.000001 and 1,000 USDC). |
| result.order.replaced_order_idstring or null If replaced, ID of the order that was replaced |
| result.order.signed_limit_pricestring or null The original limit price that the user signed. Only set when the order was adjusted (i.e., for post-only orders with reject_post_only=false that would have crossed). Used for on-chain submission. |
| result.order.trigger_pricestring or null (Required for trigger orders) Index or Market price to trigger order at |
| result.order.trigger_price_typestring or null (Required for trigger orders) Trigger with Index or Mark Price enum markindex |
| result.order.trigger_reject_messagestring or null (Required for trigger orders) Error message if error occured during trigger |
| result.order.trigger_typestring or null (Required for trigger orders) Stop-loss or Take-profit. enum stoplosstakeprofit |
| result.tradesarray of objectsrequired |
| result.trades[].directionstringrequired Order direction enum buysell |
| result.trades[].expected_rebatestringrequired Expected rebate for this trade |
| result.trades[].extra_feestringrequired Extra fee in USDC added by the referring client (included in trade fee) |
| result.trades[].index_pricestringrequired Index price of the underlying at the time of the trade |
| result.trades[].instrument_namestringrequired Instrument name |
| result.trades[].is_transferbooleanrequired Whether the trade was generated through private/transfer_position |
| result.trades[].labelstringrequired Optional user-defined label for the order |
| result.trades[].liquidity_rolestringrequired Role of the user in the trade enum makertaker |
| result.trades[].mark_pricestringrequired Mark price of the instrument at the time of the trade |
| result.trades[].order_idstringrequired Order ID |
| result.trades[].quote_idstring or nullrequired Quote ID if the trade was executed via RFQ |
| result.trades[].realized_pnlstringrequired Realized PnL for this trade |
| result.trades[].realized_pnl_excl_feesstringrequired Realized PnL for this trade using cost accounting that excludes fees |
| result.trades[].rfq_idstring or nullrequired RFQ ID if the trade was executed via RFQ |
| result.trades[].subaccount_idintegerrequired Subaccount ID |
| result.trades[].timestampintegerrequired Trade timestamp (in ms since Unix epoch) |
| result.trades[].trade_amountstringrequired Amount filled in this trade |
| result.trades[].trade_feestringrequired Base_fee (only takers) + unit_fee (adjusted via rebates / discounts) + extra_fee (set by referrring client)) |
| result.trades[].trade_idstringrequired Trade ID |
| result.trades[].trade_pricestringrequired Price at which the trade was filled |
| result.trades[].transaction_idstringrequired The transaction id of the related settlement transaction |
| result.trades[].tx_hashstring or nullrequired Blockchain transaction hash |
| result.trades[].tx_statusstringrequired Blockchain transaction status enum requestedpendingsettledrevertedignoredtimed_out |
Example
{request_example_shell}{request_example_javascript}{request_example_python}The above command returns JSON structured like this:
{response_example_json}