Order and RFQ Placement

POST /v1/api/order

This endpoint can be used to submit a new order to the exchange

New Order

Message sent to submit a new order to the exchange.

A new order request is identified by a symbol name or a tradeable_entity_id which can be found in the Entities and Rules API.

tip

Don't forget that all fields are sent as string, including prices, quantities, ratios and other non text values

Order Types and Time To Live

Order type is set with the type value and can be LIMIT or MARKET.
Time To Live for the order is set with the recv_window value. recv_window represents the number of 10 minutes exchange cycles to keep the order alive for.
For MARKET orders, the time in force must be set to IOC (Immediate Or Cancel) and the price and recv_window fields must not be present.
For GTC (Good-Til-Cancelled) orders, the recv_window needs to be specified (number of 10 minutes exchange cycles to keep the order alive for).
If IOC (Immediate Or Cancel) is specified for LIMIT orders, any recv_window value is ignored.

Example and exchange cycle explanation:

"recv_window": "6" corresponds to:

time left in the current cycle + 5 × 10 minutes cycles

= 50 minutes + up to 10 minutes

= in between 50 minutes and an hour depending on where we are in the cycle when the order request is sent.

Multiple legs

The same API is used to submit single and multi leg orders.
To create a multi leg order a legs object must be present in the message that defines the individual legs in terms of Tradeable Entity Id or Symbol and ratios.
For multi leg orders the legs object must contain in between 2 and 10 legs.
If a legs object with only 1 leg is entered it will be treated as a single order. This allows the same message construction to be used for single and multi leg orders.
For a multi leg object the individual top level tradeable_entity_id and symbol fields must not be present.

caution

When constructing the legs:

The entries must be in ascending tradeable_entity_id order
Each tradeable entity must not appear more than once
The greatest common divisor of the absolute values of the leg ratios is one
The ratio of the first leg must always be positive

This allows the exchange to uniquely identify multi leg orders.

RFQs and Firm orders

To send a RFQ for a single or multi leg order, the market_id must be set to none
To send a firm (normal) order the market_id must be set to 0

An indicative multi leg order will time out after a system defined time, typically 30 minutes. To prevent this, the client must periodically submit a refresh_interest message within the timeout period for as long as they require the indicative order to remain active.

Headers

Header Field	Type	Comments
credentials_secret	JWT	Created by user for validation

Request Body

Name	Type	Comments
symbol	string	Instrument name e.g `BTC-USD`
tradeable_entity_id	integer	Tradeable Entity Id
market_id	string	`"0"` for firm order / `"none"` for RFQ
side	string	`buy` / `sell`
type	string	`LIMIT` / `MARKET`
time_in_force	string	`GTC` / `IOC`
quantity	float	`"0.1"` / `"0.000123"` / `"0.0"` / `"1.3456"`
minimum_quantity	float	`"0.0"` / `"1.0"` (Only for multi leg orders)
price	float	`"12.0"` / `"1.1245"` / `"0.000100"`
client_order_id	string	Unique Order Id generated by the client
recv_window	integer	Integer in between `1` and `65534`
legs	Leg[]	Optional, 1 and up to 10 legs defining a multi leg order
user_tag	string	Client defined tag used to identify the request

`Leg` Object

Name	Type	Comments
tradeable_entity_id	number	Tradeable Entity Id (omit if `symbol` is present)
symbol	string	Symbol (omit if `tradeable_entity_id` is present)
ratio	integer

Examples

Single Leg Spot Firm Order

{
  "new_order": {
    "market_id": "0",
    "side": "buy",
    "quantity": "1",
    "type": "LIMIT",
    "time_in_force": "GTC",
    "client_order_id": "unique_client_order_id",
    "price": "10000",
    "recv_window": "1",
    "symbol": "BTC-USD",
    "user_tag": "unique_request_id"
  }
}

Single Leg Option RFQ

{
  "new_order": {
    "market_id": "none",
    "side": "buy",
    "quantity": "5",
    "type": "LIMIT",
    "time_in_force": "GTC",
    "client_order_id": "unique_client_order_id",
    "recv_window": "1",
    "symbol": "ETH-20221223-2400C",
    "user_tag": "unique_request_id"
  }
}

Firm Multi Leg Order

{
  "new_order": {
    "market_id": "0",
    "side": "buy",
    "quantity": "1",
    "type": "LIMIT",
    "time_in_force": "GTC",
    "client_order_id": "unique_client_order_id",
    "price": "10000",
    "recv_window": "1",
    "legs": [
      { "ratio": "1", "sym": "ETH-20221223-1600P" },
      { "ratio": "-1", "sym": "ETH-20221223-1800C" },
      { "ratio": "-1", "sym": "ETH-20221223-1800P" }
    ],
    "user_tag": "unique_request_id"
  }
}

Multi Leg RFQ

{
  "new_order": {
    "market_id": "none",
    "side": "buy",
    "quantity": "25",
    "type": "LIMIT",
    "time_in_force": "GTC",
    "client_order_id": "unique_client_order_id",
    "recv_window": "1",
    "legs": [
      { "ratio": "1", "sym": "ETH-20221223-1350P" },
      { "ratio": "-5", "sym": "ETH-20221223-1600P" },
      { "ratio": "2", "sym": "ETH-20221223-2000C" }
    ],
    "user_tag": "unique_request_id"
  }
}

Order Accepted

If the order is accepted, the following message is sent back.

Order Accepted Message

Name	Type	Comments
utc_timestamp	integer	server UTC time in μs
market_id	string	`"0"` for firm order / `"none"` for RFQ
tradeable_entity_id	integer	Tradeable Entity Id
symbol	string	Instrument name e.g `BTC-USD`
order_id	integer	Exchange order id
type	string	`LIMIT` / `MARKET`
client_order_id	string	Unique Order Id generated by the client
quantity	float
price	float
legs	Leg array	cf below

Leg

Name	Type	Comments
tradeable_entity_id	number	Tradeable Entity Id
symbol	string	Instrument name e.g `BTC-USD`
ratio	integer

Example

Single Leg Order Accepted

{
  "order_accepted": {
    "utc_timestamp": "1670156592236702",
    "market_id": "0",
    "tradeable_entity_id": "13",
    "symbol": "BTC-USD-PERPETUAL",
    "type": "LIMIT",
    "order_id": "9512137",
    "client_order_id": "unique_client_order_id",
    "quantity": "1.0",
    "price": "10000.0"
  }
}

Multi Leg RFQ Accepted

{
  "order_accepted": {
    "utc_timestamp": "1670156351624071",
    "market_id": "none",
    "tradeable_entity_id": "",
    "symbol": "ETH-20221223-1600P@1/ETH-20221223-1800P@-10/ETH-20221223-2200C@4",
    "type": "LIMIT",
    "client_order_id": "unique_client_order_id",
    "quantity": "10.0",
    "minimum_quantity": "0.0",
    "ioi_cache_timeout": "1800",
    "legs": [
      {
        "tradeable_entity_id": "4816",
        "symbol": "ETH-20221223-1600P",
        "ratio": "1"
      },
      {
        "tradeable_entity_id": "4818",
        "symbol": "ETH-20221223-1800P",
        "ratio": "-10"
      },
      {
        "tradeable_entity_id": "4821",
        "symbol": "ETH-20221223-2200C",
        "ratio": "4"
      }
    ]
  }
}

Order Rejected

If the order is rejected, the following message is sent back.

Order Rejected Message

Name	Type	Comments
utc_timestamp	integer	server UTC time in μs
market_id	string	`"0"` for firm order / `"none"` for RFQ
tradeable_entity_id	integer	Tradeable Entity Id
symbol	string	Instrument name e.g `BTC-USD`
type	string	`LIMIT` / `MARKET`
client_order_id	string	Unique Order Id generated by the client
quantity	float
price	float
legs	Leg array	cf below

Leg

Name	Type	Comments
tradeable_entity_id	number	Tradeable Entity Id
symbol	string	Instrument name e.g `BTC-USD`
ratio	integer

Example

Single Future Leg Order with invalid price

{
  "order_rejected": {
    "utc_timestamp": "1670225940556544",
    "market_id": "0",
    "tradeable_entity_id": "4826",
    "symbol": "ETH-20221216",
    "type": "LIMIT",
    "client_order_id": "unique_client_order_id",
    "quantity": "0.99",
    "price": "0.0",
    "reason": "price_less_than_minimum_price"
  }
}

Multi Leg Order with invalid legs

{
  "order_rejected": {
    "utc_timestamp": "1670225002636914",
    "market_id": "0",
    "type": "LIMIT",
    "client_order_id": "unique_client_order_id",
    "quantity": "1.0",
    "minimum_quantity": "0.0",
    "price": "10000.0",
    "reason": "invalid_legs",
    "legs": [
      {
        "tradeable_entity_id": "4807",
        "symbol": "ETH-20221223-1300C",
        "ratio": "-1"
      },
      {
        "tradeable_entity_id": "4810",
        "symbol": "ETH-20221223-1350P",
        "ratio": "1"
      }
    ]
  }
}

Order Executed

Execution messages are only sent through the WebSocket connection

Order and RFQ Placement

New Order​

Order Types and Time To Live​

Multiple legs​

RFQs and Firm orders​

Headers​

Request Body​

Leg Object​

Examples​

Order Accepted​

Order Accepted Message​

Leg​

Example​

Order Rejected​

Order Rejected Message​

Leg​

Example​

Order Executed​

New Order

Order Types and Time To Live

Multiple legs

RFQs and Firm orders

Headers

Request Body

`Leg` Object

Examples

Order Accepted

Order Accepted Message

Leg

Example

Order Rejected

Order Rejected Message

Leg

Example

Order Executed