Real-time Orders API

The Real-time Orders API streams updates about a client's order statuses. It complements the GET /v1/trading/order/{id}/ endpoint, which is used for retrieving the current state of an order on demand.

Usage

Establish a Connection

Establish a secure websocket connection with one of the following URLs according to the Getting Started connection setup instructions:

• wss://live.moment-api.com/v1/trading/order-stream/ for the live environment
• wss://paper.moment-api.com/v1/trading/order-stream/ for the paper environment

An Authorization header must be provided to authenticate the connection. See Authentication for details.

Once an authenticated connection is established, the client will receive the welcome message:

{"msg_type": "success", "msg": "connected"} 

The client is now ready to receive trading updates.

Message Types

There are three types of messages that can be received on the orders websocket.

Message Playback

Every message includes a msg_number field, which is a string representing a 64-bit unsigned integer. The message number is a unique, increasing index assigned to each message. Message numbers have the format YYYYMMDDxxxxxxxxxx, where the date is the UTC date and the xs are an incrementing index starting at 0000000000. On connection, an optional starting message number can be specified via the start query parameter, which will cause the websocket to play/replay all messages whose msg_number is at least start.

• wss://moment-api.com/v1/trading/order-stream/?start=202308310000000123 plays all messages whose message numbers are at least 202308310000000123
• wss://moment-api.com/v1/trading/order-stream/ plays all messages which occur after the connection begins

Message playback going back 48 hours is supported. Older messages are not guaranteed to be available. Message numbers are dense; that is, numbers are not skipped except between day.

Filtering by Introducing Broker

Moment's API allows both introducing brokers and clearers to track orders. By default, the real-time orders API shows event updates for all organizations managed by the authenticated organization. For example, an introducing broker sees only their orders, whereas a clearer sees all orders from their associated introducing brokers.

The real-time order updates stream can further be filtered by introducing broker by specifying the ib_id query parameter. For example, wss://moment-api.com/v1/trading/order-stream/?ib_id=introducing-broker-12345 will filter for orders placed by introducing-broker-12345.

Order Updates

Order update messages share a common format (note: whitespace is provided for legibility and is stripped in API outputs):

{
  "msg_type": "order_update",
  "msg_number": "202308310000000123",
  "event": EVENT_OBJECT,
  "order": ORDER_OBJECT,
  "event_id": "01JADC9ARQ3A2NW9D3Y5VBA3S1"
}

In these responses, event contains information about how an order changed, and order contains the summary of the new order state following that change. The ORDER_OBJECT schema is the same object as the response from GET /v1/trading/order/{order_id}/, although it will NOT include the allocation_info field as conditionally returned from the REST endpoint. The EVENT_OBJECT schema is described in the Order Event Schemas section below. The event_id field is a unique identifier per event.

Order Event Types

Events can occur that change the status of an order as well as the order's filled_quantity and filled_avg_price. The following table summarizes the different types of events and their impact on an order's status. For more details about order statuses, see Order States and Statuses.

Order Event Schemas

Request

The request event acknowledges that Moment has received an order and it is now pending approval by the pre-trade checks engine.

{
  "event_type": "request",
  "time": "2022-10-04 14:12:00",
  "order_id": "ed480117-ea24-4566-ae02-c045cd595350",
  "client_order_id": "client-order-12345abcde",
  "risk_group_id": "risk-group-foobar",
  "isin": "US594918AD66",
  "cusip": "594918AD6",
  "side": "buy",
  "amount": { "value": 10000, "type": "par" },
  "limit_price": 90,
  "account_id": "client-managed-account-id",
  "type": "limit",
  "extended_hours": false,
  "annotation": "arbitrary-client-metadata"
}

Approve

The approve event occurs when an order is approved by Moment's pre-trade checks. Once an order is approved, it will automatically be routed to the trading venue(s) for execution.

{
  "event_type": "approve",
  "time": "2022-10-04 14:13:00",
  "order_id": "ed480117-ea24-4566-ae02-c045cd595350",
  "client_order_id": "client-order-12345abcde",
}

Reject

The reject event occurs when an order is rejected by Moment's pre-trade checks. This is most likely because the order violates risk constraints set by the executing broker-dealer.

{
  "event_type": "reject",
  "time": "2022-10-04 14:13:00",
  "order_id": "ed480117-ea24-4566-ae02-c045cd595350",
  "client_order_id": "client-order-12345abcde",
  "reject_reason": "order size violates max order size",
  "reject_code": 600
}

The reject code will be one of the following:

Cancel

The cancel event occurs when an order is canceled by an API request, Moment's system, or a venue. The cancel code specifies the reason for the cancellation.

{
  "event_type": "cancel",
  "time": "2022-10-04 14:14:00",
  "order_id": "ed480117-ea24-4566-ae02-c045cd595350",
  "client_order_id": "client-order-12345abcde",
  "cancel_reason": "cancel requested by organization: introducing-broker.net",
  "cancel_code": 702
}

The cancel code will be one of the following:

Execution

The execution event occurs when Moment executes a trade in response to an order. Note that one order can have multiple executions. Accrued interest is specified in the issuing currency: this amount is paid buy the buyer in addition to the transaction value

{
  "event_type": "execution",
  "time": "2022-10-04 14:14:00",
  "order_id": "ed480117-ea24-4566-ae02-c045cd595350",
  "client_order_id": "client-order-12345abcde",
  "venue": "ice_bondpoint",
  "venue_execution_id": "exec-id-12345",
  "counterparty": "MADV",
  "counterparty_clearing_firm": "0443",
  "amount": { "value": 30000, "type": "par" },
  "price": 87,
  "ytw": 3.425,
  "ytm": 3.425,
  "accrued_interest": 75.00
}

Allocation Updates

Allocation update messages share a common format (note: whitespace is provided for legibility and is stripped in API outputs):

{
  "msg_type": "allocation_update",
  "msg_number": "202408310000000123",
  "event": EVENT_OBJECT,
  "summary": SUMMARY_OBJECT,
  "event_id": "01JCR9YJYRMN3VBB8EBZ14T23Z"
}

In these responses, event contains information about how an allocation changed, and summary contains the summary of the new allocation state following that change. The SUMMARY_OBJECT schema is the same object as the allocation_info field in the response from GET /v1/trading/order/{order_id}/. The EVENT_OBJECT schema is described in the Allocation Event Schemas section below. The event_id field is a unique identifier per event.

Allocation Event Types

Events can occur that change the status of an allocation. The following table summarizes the different types of events and their impact on an allocation's status.

Allocation Event Schemas

Create

The create event occurs when the allocation request has been created in Moment systems and is pending approval.

{
  "event_type": "allocation_create",
  "time": "2024-11-21T19:46:24.949629688Z",
  "allocation_id": "01JD845WD3J6F1DK1678N6CGHM",
  "client_allocation_id": "alloc-id-1234",
  "order_id": "01JD845WD24F71027GWPTBC9M1",
  "client_order_id": "018-20c8a6f8",
  "risk_group_id": "01H6C7SHFKRXK303NTKH0GKA1J",
  "custodian_id": "01H6C79MTABWNQZCB20V9NFV0E",
  "ib_id": "01H6C79MTABWNQZCB20V9NFV0E",
  "allocation_strategy": "fifo_without_averaging"
}

Reject

The reject event occurs when Moment has rejected the allocation block.

{
  "event_type": "allocation_reject",
  "time": "2024-11-20T15:14:22.96510245Z",
  "allocation_id": "01JD5271Z3TRCQSPR27FHHV2RG",
  "client_allocation_id": "alloc-id-1234",
  "reason": "Allocation quantity is not a multiple of par value. Par value: 5000, Allocated quantity: 100",
  "code": 1103
}

The allocation reject code will be one of the following:

Approve

The allocation request has been approved by Moment and is pending calculation.

{
  "event_type": "allocation_approve",
  "time": "2024-11-21T19:46:24.949640433Z",
  "allocation_id": "01JD845WD3J6F1DK1678N6CGHM",
  "client_allocation_id": "alloc-id-1234"
}

Cancel

The allocation request was canceled, this may be due to explicit request or cancelation of the order the allocation was associated with.

{
  "event_type": "allocation_cancel",
  "time": "2024-11-21T19:11:08.382286412Z",
  "allocation_id": "01JD82597CGXYC216P7H7Q02GC",
  "client_allocation_id": "alloc-id-1234",
  "reason": "The order itself is rejected",
  "code": 1203
}

The allocation cancel code will be one of the following:

Calculate

The allocation amounts and prices have been calculated based on order execution and allocation strategy.

{
  "event_type": "allocation_calculate",
  "time": "2024-11-21T19:46:26.17314985Z",
  "allocation_id": "01JD845WD3J6F1DK1678N6CGHM",
  "client_allocation_id": "alloc-id-112",
  "order_id": "01JD845WD24F71027GWPTBC9M1",
  "client_order_id": "018-20c8a6f8",
  "risk_group_id": "01H6C7SHFKRXK303NTKH0GKA1J",
  "custodian_id": "01H6C79MTABWNQZCB20V9NFV0E",
  "ib_id": "01H6C79MTABWNQZCB20V9NFV0E",
  "allocation_strategy": "fifo_without_averaging",
  "account_allocations": [
    {
      "account_id": "alloc-acct1",
      "requested_amount": {
        "type": "par",
        "value": 1000
      },
      "actual_amount": {
        "type": "par",
        "value": 1000
      },
      "fill_price": 97.42446,
      "venue_mpid": "VABD",
      "venue_execution_id": "01123274-IBP"
    }
  ],
  "trades": [
    {
      "amount": {
        "type": "par",
        "value": 1000
      },
      "price": 97.42446,
      "venue_mpid": "VABD",
      "venue_execution_id": "01123274-IBP"
    }
  ]
}

Submit

The calculated allocation amounts and prices have been submitted to the custodian for booking.

{
  "event_type": "allocation_submit",
  "time": "2024-11-22T15:57:30.787832476Z",
  "allocation_id": "01JDA9F7149XXMACRE9JC4V1F5",
  "client_allocation_id": "alloc-id-1234",
  "custodian_id": "01JD7ZKC0TWQYGW3SJXS48KSM8"
}

Fail

Submission of the allocation to the custodian failed.

{
  "event_type": "allocation_fail",
  "time": "2024-11-22T15:46:24.649929381Z",
  "allocation_id": "01JDA8V0KX54EDBGC8JXKEG7NX",
  "client_allocation_id": "alloc-id-1234",
  "reason": "The payload does not conform to the Schwab format",
  "code": 1000
}

The allocation fail code will be one of the following:

System Updates

System update messages simply contain an event payload (note: whitespace is provided for legibility and is stripped in API outputs):

{
  "msg_type": "system_update",
  "msg_number": 202411150000000028,
  "event": EVENT_OBJECT,
  "event_id": "01JCR9PRHEKC8DHZB2FXD1TB5K"
}

System Event Schemas

Cancel Request

The cancel request event acknowledges that a user has requested to cancel the order and the cancelation is currently pending.

{
  "event_type": "cancel_request",
  "cancel_request_id": "01880230-7cab-1ed9-e036-7a8bc14357e8",
  "time": "2022-10-04 14:14:00",
  "order_id": "ed480117-ea24-4566-ae02-c045cd595350",
  "source": "api call by customer example.com"
}

Cancel Reject

The cancel reject event occurs if a cancel request is invalid. This can occur because an order is closed or nonexistent, or because a cancel request is already pending.

{
  "event_type": "cancel_reject",
  "cancel_request_id": "01880230-7cab-1ed9-e036-7a8bc14357e8",
  "time": "2022-10-04 14:16:00",
  "cancel_reject_code": 801,
  "cancel_reject_reason": "the order was already closed"
}

The cancel reject code will be one of the following:

Allocation Cancel Request

The allocation request event acknowledges that a user has requested to cancel an allocation and the cancelation is currently pending.

{
  "event_type": "cancel_allocation_request",
  "time": "2024-11-22T18:20:12.22667744Z",
  "cancel_request_id": "01JDAHMR22XESFJHEQ48CVKQA6",
  "allocation_id": "01JCPHP9WS37DJ1N1W1ECWS2QK",
  "source": "api call by organization test.withmoment.com"
}

Allocation Cancel Reject

The allocation cancel reject event occurs if an allocation cancel request is invalid. Among other reasons, this may occur because an allocation has already been canceled or submitted or because an allocation is nonexistent.

{
  "event_type": "cancel_allocation_reject",
  "time": "2024-11-22T18:27:00.171574322Z",
  "cancel_request_id": "01JDAJ169S3MH4A1GFCZ3222G8",
  "allocation_id": "01JDAJ06MKPS7X3Q056ZCP6G90",
  "cancel_reject_code": 900,
  "cancel_reject_reason": "invalid allocation state transition from STATUS_CANCELED to STATUS_CANCELED"
}

The allocation cancel reject code will be one of the following: