WebSocket API #

General Information #

Most points in the HTTP API’s general information section apply to the WebSocket API as well. Nevertheless, there are a few additions:

• A request should be sent to <your base url>/api/ws (e.g., wss://localhost:7070/api/ws) to open a WebSocket connection.
• To open a connection, a user has to be authenticated as shown here. The scoped permissions apply to WebSocket events as well.
• A single WebSocket connection should be used for all events.
• All events should be expected in the following format:

{
	"topic": "[email protected]",
	"payload": {
		// <event payload>
	}
}

• Topics are placed at the top of each event’s section.
• Each topic should have and be expected to have a descriptor (i.e., a prefix ending with a ~) that describes the purpose of the event. The possible descriptors are as follows:
  • pub - used by the server when a new event is published.
  • drop - used by the server when a client’s subscription is dropped.
  • sub - used by a client when sending a subcription request.
  • unsub - used by a client when sending an unsubcription request.

Event Subscriptions #

To receive events of a certain topic, a subscription WebSocket request with a request ID of unsigned int type should be sent:

{
	"topic": "[email protected]",
	"id": 1
}

Likewise, to unsubscribe from a certain topic, an unsubscription WebSocket request should be sent:

{
	"topic": "[email protected]",
	"id": 1
}

On successful subscription or unsubscription, a response with the same request ID is given:

{
	"success": true,
	"id": 1
}

Duplicate subscriptions and unsubscriptions targeting nonexistent subscriptions are permitted.

A subscription may be dropped if events cannot be published (e.g., the symbol provided in the exchange ticker topic is invalid). In these situations a notification event is sent:

{
	"topic": "[email protected]",
	"reason": "invalid symbol"
}

Version Information Ping #

ping@version

Sends the engine’s version information every 5th second of each minute.

Permissions: none

Payload:

{
	"version": "1.0.0"
}

• version - string
  The version of the engine’s executable.