# Matcher WebSocket API

Matcher supports WebSocket communications protocol (opens new window) and provides WebSocket API. The protocol enables interaction between a web browser (or other client application) and a web server, facilitating real-time data transfer from and to the Server. Most browsers including Google Chrome, Microsoft Edge, Internet Explorer, Firefox, Safari and Opera support the protocol.

Messages received from the Matcher are represented as JSON objects that can contain letters or letter combinations, for example "t", "Q". These fields are intended to be processed by the Client; JSON objects can also contain symbols, such as "%" or "_". Such symbols are not recommended to be used in the Client, as they are used for internal purposes an may be changed at any time. The type of message can be reviewed in the "T" field.

# Base URLs

MainNet: wss://matcher.waves.exchange/ws

TestNet: wss://matcher-testnet.waves.exchange/ws

# Terminology

snapshot - the current state that is sent only once immediately after connecting via WebSocket.

updates - the updated state of the object after any activities of the matcher. updates and snapshot have similar format of the fields, except for updates contains only the updated fields. The Client should apply the changes to the object from updates to get the latest state. The changes must be applied in the same order as they are received.

domain message - a message that belongs to the entities representing the domain part, such as order books, addresses etc.

system message - a message that belongs to Matcher and require specific actions from the Client. For example, Ping request requires the reply Pong, while both are system messages.

# Ping/Pong

Ping/pong is a stream of system messages allowing to find out whether the connection in up. The stream also keeps the connection alive.

Operation algorithm:

Once every N seconds the Matcher sends Ping with some payload via the WebSocket connection;
The Client must reply with Pong with the same payload;
If the Pong with the same payload does not return to the Matcher in M seconds - the Matcher disconnects;
Matcher always expects Pong message with the payload similar to the latest Ping and ignores Pong messages with wrong payload;

N and M values are set by the Matcher.

Ping and Pong have similar format. The format can change, however the message type cannot change. So basically, when a Client receives Ping it must reply with the same message to the Matcher.

Ping/Pong is implemented in the same manner for all the streams.

Example:

{
  "T": "pp",
  "_": 1585148910776
}

In this example:

pp is the message type that stands for Pong/Pong.

1585148910776 is Unix timestamp of update in milliseconds. This field is only for debugging.

# FAQ

Q: Why Ping/Pong frames described in RFC are not used?

A: Unfortunately, WebSocket for browsers has no access to Control frames (opens new window).

Q: Why Ping is sent from Matcher, but not from the Client?

A: We follow recommendation of the spec document (opens new window)

User agents must not use pings or unsolicited pongs to aid the server; it is assumed that servers will solicit pongs whenever appropriate for the server's needs.