This page will help you get started with Moment's real-time APIs.
Real-time APIs complement RESTful APIs by enabling low-latency messaging and status updates. Currently Moment offers two real-time APIs:
- Real-time Orders API – provides real-time updates about your order statuses
- Real-time Prices API – provides real-time prices and yields for instruments
Details
Protocol
Moment's real-time APIs are based on websockets.
The websocket creation URLs are in the format: wss://moment-api.com/v{X}/..., where wss indicates that these are secure websocket connections and v{X} specifies the Moment protocol version for the API.
Message format
The real-time APIs deliver messages in the JSON format. Every message sent to or received from the server will have the structure:
{"msg_type": "{message_type}", "{key1}": "{value1}", ...}There are two classes of messages which may be received via the real-time APIs:
- Control messages provide information about the websocket connection itself. These messages will have a
msg_typeoferror,success,subscription, orheartbeat. - Data messages deliver information through the websocket connection. These messages will have API-specific
msg_typevalues and data.
Encoding and compression
Messages over the websocket are encoded as clear text. To reduce size, the JSON messages will have their whitespace stripped down. However, the documentation may include whitespace to improve readability.
In the future, Moment plans to reduce bandwidth requirements by implementing websocket as per RFC 7692. If bandwidth reduction is a concern, choose a websocket client which supports RFC 7692.
Keepalive
Long-lived websockets make use of ping and pong control frames to keep the connection active. Pings and pongs are described in RFC 6455.
Moment's websockets send ping frames every 10–15 seconds, depending on the stream. Upon receiving a ping message, clients should respond to Moment with a pong within several seconds.
Most websocket client libraries are RFC 6455-compliant and will handle this communication automatically.
Heartbeats
Protocol-level ping and pong frames are not observable from all environments — browsers in particular do not expose them. In addition to protocol pings, the trading streams (such as the Real-time Orders API) may periodically send an application-level heartbeat message:
{"msg_type": "heartbeat"}Heartbeat messages give clients an inbound message to detect a dead connection during otherwise idle periods: if no message of any kind arrives for an extended period, the connection is likely stale and should be re-established. Heartbeat messages carry no data and may otherwise be safely ignored. Clients must tolerate receiving them on any stream.