Glossary

Order Status

The status indicates the outcome of adding an order to the trading system. It can have the following values:

• full_fill: All size was filled, and nothing remains on the book.
• partial_fill_and_rest: Partial fill, with the residual remaining open on the limit order book. This is possible only with limit and market_limit order types. The remaining_size field specifies the residual size on the book.
• partial_fill_and_cancel: Partial fill, with the residual size canceled due to insufficient depth at the desired price. This occurs only with the immediate-or-cancel time in force.
• added_liquidity_only: The order did not cross with any other orders and remains open on the limit order book.
• canceled: Order is canceled entirely.

Cancel Reason

The cancel_reason indicates the cancellation reason if the the status is partial_fill_and_cancel or canceled. It's also used for the order history if the event_type is canceled. The cancel_reason field will be not be included in other cases:

• cancel_order: Canceled explicitly by request.
• cancel_for_modify: Canceled as part of cancel+add style modify.
• mass_cancel: Canceled as part of a mass cancel request.
• cancel_on_disconnect: Canceled due to WebSocket connection disconnect.
• size_not_available: This occurs in two scenarios:
  1. A fill-or-kill order was at a marketable price, but there was not enough liquidity to fill the entire order, so it was canceled.
  2. Any kind of market or market_limit order against an empty market.
• off_market_price: An immediate-or-cancel or fill-or-kill limit order was not at a marketable price, so the entire size was canceled.
• order_would_cross: The execution_type was post_only, but given the price and current market conditions, it would've crossed to the opposite site, so the order was canceled.
• account_out_of_margin: The order was at a marketable price, but the client had insufficient margin to trade any of the size. Note: if some size was traded before exhausting the margin allowance, the client receives one of the partial_fill_ codes above.
• self_trade: The order was canceled because it would've crossed with the client's own account.
• order_expired: The execution_type was gte and has passed the expiration time.

Event Type

The event_type indicates the type of event a particular object is referring to. If the event_type is canceled, the cancel_reason will indicate the reason for the cancel:

• new: Order was created.
• fill: Order was filled at-least partially.
• cancel: Any remaining size for the order is canceled.

The Header Object

The header object appears as the first element in an array for all WebSocket messages to the client:

msg_type

• Generally, a response will have a msg_type with the suffix _response appended. For example, the response to a cancel_order request is called cancel_order_response.
• If the request is malformed, a response with msg_type: request_error will be received instead.
• For notifications, msg_type indicates the data feed the notification is related to.

id

• This is the id of the associated request. Responses to the request will include the same id so that you can map WebSocket messages to the associated requests.
• For a notification, id is a sequence number that uniquely identifies an item in the feed.

version

• This indicates the version of the protocol being used by the endpoint.

Generic WebSocket Error Response

Response with msg_type: request_error.

Most requests have a single response type, named using the pattern <request_name>_response, e.g., cancel_order has a response type of cancel_order_response. In cases where the response schema does not make sense because the request fails, or for WebSocket clients, if the msg_type cannot be parsed correctly, a common "request error" is delivered. This response includes an ID in the header that matches the originating request.

Response Fields

All rejection message types contain the following field:

• description: A human-readable description of the error, often detailing the issue with the matching engine or the specific protocol misuse.

Nonce

The nonce is used along with other order parameters to create a unique order hash for validation by contracts.

Requirements

1. Epoch Timestamp: The first 32 bits of the nonce must be an epoch timestamp within the last 15 seconds.
2. Unique Value: The entire 64-bit nonce must be unique.

Example Implementation

Here is example code in Python to generate a nonce:

class NonceGenerator:
    counter = 0 
    
    def __init__(self):
        self.counter = 0 
    
    def generate_nonce(self):
        import time
        epoch_seconds = int(time.time())
        nonce = (epoch_seconds << 32) + self.counter
        self.counter += 1 
        if self.counter == (1 << 32):
            self.counter = 0
        return nonce

# Example Usage
generator = NonceGenerator()
unique_nonce = generator.generate_nonce()
print(unique_nonce)

In this example, we use a counter for the last 32 bits, but a random number can also be used provided the full 64-bit nonce is unique.