API Reference

Order Creation & Cancellations

The system is now fully async. The HTTP responses from POST /trade/orders and PUT /trade/orders/cancel are only meant to be an ACK (doing basic schema validation), and the actual confirmation for an order being open, rejected, successfully canceled or failed will come via WebSocket.

Order Creation

When an order is created successfully, an ActiveOrderUpdate event is received with one of the following possible order statuses: OPEN, PARTIALLY_FILLED_OPEN, PARTIALLY_FILLED_CANCELLED, FILLED

On the other hand, when an order is rejected (say there was an invalid price field passed in), an OrderCancellationUpdate event is received.

The screenshots below showcase examples of order creation (with the HTTP response on the right-side terminal and the socket message on the left-side terminal).

  • Successful Order Creation Scenario

    The POST /orders endpoint returns an ACK with the order hash, but we receive an ActiveOrderUpdate for the open order via the WS.

  • Failed Order Creation Scenario

    We pass in an incorrect price (0) and expect this order to fail. The POST /orders endpoint again returns an ACK with the order hash (since it does purely schema validation), but we receive an OrderCancellationUpdate via the WS with the specified failure reason.

Order Cancellation

Again, the PUT /trade/orders/cancel endpoint ACKs a request and informs on the success or failure of the cancellation asynchronously via the OrderCancellationUpdate event.

Note that it’s possible to receive this OrderCancellationUpdate for all the following reasons:

  • The system auto cancelled an open order
  • The user initiated a successful cancel
  • The user initiated a failed cancel

In first two scenarios, the event contains a cancellationReason.

If the cancellation fails, i.e., in the third case, the cancellationReason is null and a failureToCancelReason is specified. Example reasons for failure include: ORDER_NOT_FOUND, MARKET_NOT_FOUND, ACCOUNT_NOT_FOUND, NO_OPEN_ORDERS_ON_MARKET, NO_FAILURE and UNSPECIFIED (this last one is used for internal debugging).

Special Cases

  • For IOC orders, if the quantity cannot be fully filled, the remaining part of the order is cancelled. In this case, we DO NOT send a dedicated cancel event, but we send an ActiveOrderUpdate message with the order status being PartiallyFilledCancelled.
  • For a bulk cancel, like in the case of all orders being cancelled for a market, the OrderCancellationUpdate message is sent to the user with the cancellation reason UserCancelledAllOnMarket. If a user gets an order cancellation with this reason, this means that all the open orders on that market have been cancelled.