Order and RFQ Placement
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.
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 beLIMIT
orMARKET
.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 toIOC
(Immediate Or Cancel) and theprice
andrecv_window
fields must not be present.For
GTC
(Good-Til-Cancelled) orders, therecv_window
needs to be specified (number of 10 minutes exchange cycles to keep the order alive for).If
IOC
(Immediate Or Cancel) is specified forLIMIT
orders, anyrecv_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
andsymbol
fields must not be present.
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 tonone
To send a firm (normal) order the
market_id
must be set to0
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.
New Order Message
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"
}
}
New Bulk Order
This message allows the client to issue multiple orders in a single message for convenience and performance purposes.
Internally each order is processed as an individual order, so each order entry in the orders array follows the same rules as for a single order.
There will as many order_accepted
or order_rejected
messages received by the client as there are orders in the bulk order request.
New Bulk Order Message
Name | Type | Comments |
---|---|---|
orders | Order[] | see Order Object below |
user_tag | string | Client defined tag used to identify the request |
Order
Object
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 |
{
"new_bulk_order": {
"orders": [
{
"tradeable_entity_id": "7",
"market_id": "0",
"side": "sell",
"type": "LIMIT",
"time_in_force": "GTC",
"quantity": "0.0001",
"price": "55000.00",
"client_order_id": "unique_client_order_id",
"recv_window": "3",
"timestamp": "123456789"
},
{
"market_id": "none",
"side": "sell",
"type": "LIMIT",
"time_in_force": "GTC",
"quantity": "0.0001",
"minimum_quantity": "0.0",
"price": "55000.00",
"client_order_id": "unique_client_order_id",
"recv_window": "2",
"timestamp": "777686789",
"legs": [
{ "tradeable_entity_id": "499", "ratio": "1" },
{ "tradeable_entity_id": "952", "ratio": "3" }
]
}
],
"user_tag": "unique_request_id"
}
}
Order Accepted
This is a message received when a client's order has been accepted by the exchange.
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
This is a message received when a client’s order has been rejected.
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
This is an unsolicited message received when a client’s order has been executed.
Order Executed Message
Name | Abbreviated | Type | Comments |
---|---|---|---|
server_utc_timestamp | st | integer | Time at which the message was generated by the API |
utc_timestamp | mt | integer | Order Timestamp |
tradeable_entity_id | tid | integer | Tradeable Entity Id |
symbol | sym | string | Instrument name e.g BTC-USD |
trade_id | t_id | string | |
order_id | o_id | integer | Exchange order id |
client_order_id | co_id | string | Unique Order Id generated by the client |
executed_price | ep | float | |
executed_quantity | eq | float | |
liquidity_flag | l | string | |
price | p | float | |
side | s | string | buy / sell |
order_state | os | string |
Example
{
"execution": {
"server_utc_timestamp": "1670225941415074",
"utc_timestamp": "1670225941381601",
"tradeable_entity_id": "13",
"symbol": "BTC-USD-PERPETUAL",
"trade_id": "server_generated_trade_id",
"order_id": "server_generated_order_id",
"client_order_id": "unique_client_order_id",
"executed_price": "16470.1",
"executed_quantity": "1.0",
"liquidity_flag": "taken",
"price": "10000",
"side": "sell",
"order_state": "filled"
}
}