Skip to main content

Create a New Order

POST 
/api/v1/order

Placing Orders​

This endpoint is used for placing orders. See individual fields below for more details on their use.

Order Types​

All orders require a symbol. All other fields are optional except when otherwise specified.

These are the valid ordTypes:

  • Limit: The default order type. Specify an orderQty and price.
  • Market: A traditional Market order. A Market order will execute until filled or your bankruptcy price is reached, at which point it will cancel.
  • Stop: A Stop Market order. Specify an orderQty and stopPx. When the stopPx is reached, the order will be entered into the book.
    • On sell orders, the order will trigger if the triggering price is lower than the stopPx. On buys, higher.
    • Note: Stop orders do not consume margin until triggered. Be sure that the required margin is available in your account so that it may trigger fully.
    • Close Stops don't require an orderQty. See Execution Instructions below.
  • StopLimit: Like a Stop Market, but enters a Limit order instead of a Market order. Specify an orderQty, stopPx, and price.
  • MarketIfTouched: Similar to a Stop, but triggers are done in the opposite direction. Useful for Take Profit orders.
  • LimitIfTouched: As above; use for Take Profit Limit orders.
  • Pegged: Pegged orders allow users to submit a limit price relative to the current market price. Specify a pegPriceType, and pegOffsetValue.
    • Pegged orders must have an execInst of Fixed. This means the limit price is set at the time the order is accepted and does not change as the reference price changes.
    • PrimaryPeg: Price is set relative to near touch price.
    • MarketPeg: Price is set relative to far touch price.
    • A pegPriceType submitted with no ordType is treated as a Pegged order.

Execution Instructions​

The following execInsts are supported. If using multiple, separate with a comma (e.g. LastPrice,Close).

  • ParticipateDoNotInitiate: Also known as a Post-Only order. If this order would have executed on placement, it will cancel instead. This is intended to protect you from the far touch moving towards you while the order is in transit. It is not intended for speculating on the far touch moving away after submission - we consider such behaviour abusive and monitor for it.
  • MarkPrice, LastPrice, IndexPrice: Used by stop and if-touched orders to determine the triggering price. Use only one. By default, MarkPrice is used. Also used for Pegged orders to define the value of LastPeg. IndexPrice is not applicable to spot trading symbols.
  • ReduceOnly: A ReduceOnly order can only reduce your position, not increase it. If you have a ReduceOnly limit order that rests in the order book while the position is reduced by other orders, then its order quantity will be amended down or canceled. If there are multiple ReduceOnly orders the least aggressive will be amended first. Not applicable to spot trading symbols.
  • Close: Close implies ReduceOnly. A Close order will cancel other active limit orders with the same side and symbol if the open quantity exceeds the current position. This is useful for stops: by canceling these orders, a Close Stop is ensured to have the margin required to execute, and can only execute up to the full size of your position. If orderQty is not specified, a Close order has an orderQty equal to your current position's size. Not applicable to spot trading symbols.
    • Note that a Close order without an orderQty requires a side, so that BitMEX knows if it should trigger above or below the stopPx.
  • LastWithinMark: Used by stop orders with LastPrice to allow stop triggers only when:
    • For Sell Stop Market / Stop Limit Order
      • Last Price &lt= Stop Price
      • Last Price &gt= Mark Price × (1 - 5%)
    • For Buy Stop Market / Stop Limit Order:
      • Last Price &gt= Stop Price
      • Last Price &lt= Mark Price × (1 + 5%)
    • Not applicable to spot trading symbols.
  • Fixed: Pegged orders must have an execInst of Fixed. This means the limit price is set at the time the order is accepted and does not change as the reference price changes.

Pegged Orders​

Pegged orders allow users to submit a limit price relative to the current market price. The limit price is set once when the order is submitted and does not change with the reference price. This order type is not intended for speculating on the far touch moving away after submission - we consider such behaviour abusive and monitor for it.

Pegged orders have an ordType of Pegged, and an execInst of Fixed.

A pegPriceType and pegOffsetValue must also be submitted:

  • PrimaryPeg - price is set relative to the near touch price
  • MarketPeg - price is set relative to the far touch price

Trailing Stop Pegged Orders​

Use pegPriceType of TrailingStopPeg to create Trailing Stops.

The price is set at submission and updates once per second if the underlying price (last/mark/index) has moved by more than 0.1%. stopPx then moves as the market moves away from the peg, and freezes as the market moves toward it.

Use pegOffsetValue to set the stopPx of your order. The peg is set to the triggering price specified in the execInst (default MarkPrice). Use a negative offset for stop-sell and buy-if-touched orders.

Requires ordType: Stop, StopLimit, MarketIfTouched, LimitIfTouched.

Linked Orders​

Linked Orders are an advanced capability. It is very powerful, but its use requires careful coding and testing. Please follow this document carefully and use the Testnet Exchange while developing.

BitMEX offers four advanced Linked Order types:

  • OCO: One Cancels the Other. A very flexible version of the standard Stop / Take Profit technique. Multiple orders may be linked together using a single clOrdLinkID. Send a contingencyType of OneCancelsTheOther on the orders. The first order that fully or partially executes (or activates for Stop orders) will cancel all other orders with the same clOrdLinkID.
  • OTO: One Triggers the Other. Send a contingencyType of 'OneTriggersTheOther' on the primary order and then subsequent orders with the same clOrdLinkID will be not be triggered until the primary order fully executes.

Trailing Stops​

You may use pegPriceType of 'TrailingStopPeg' to create Trailing Stops. The pegged stopPx will move as the market moves away from the peg, and freeze as the market moves toward it.

To use, combine with pegOffsetValue to set the stopPx of your order. The peg is set to the triggering price specified in the execInst (default 'MarkPrice'). Use a negative offset for stop-sell and buy-if-touched orders.

Requires ordType: 'Stop', 'StopLimit', 'MarketIfTouched', 'LimitIfTouched'.

Rate Limits​

You can improve your reactivity to market movements while staying under your rate limit by using the Amend endpoint (PUT /order). This allows you to stay in the market and avoids the cancel/replace cycle.

Tracking Your Orders​

If you want to keep track of order IDs yourself, set a unique clOrdID per order. This clOrdID will come back as a property on the order and any related executions (including on the WebSocket), and can be used to get or cancel the order. Max length is 36 characters.

You can also change the clOrdID by amending an order, supplying an origClOrdID, and your desired new ID as the clOrdID param, like so:

# Amends an order's leavesQty, and updates its clOrdID to "def-456"
PUT /api/v1/order {"origClOrdID": "abc-123", "clOrdID": "def-456", "leavesQty": 1000}

Request​

Responses​