Cloud9Trader API > WebSocket API
Message Structure
Messages both ways are JSON string representations of arrays with each item of the array mapping to an argument. For purposes of this documentation please assume that all parameters should be placed into an array an stringified for send and parsed as JSON on receipt.
For example, to send first parameter "request" and second parameter "orders":
socket.send(JSON.stringify(["request", "orders"]);The first argument in messages you send is an instruction to the servers. This can be one of "request", "subscribe", "unsubscribe" or "submit".
In messages received, the first argument is the channel. This may be a data topic or a requestId for correlation.
Request
These are typically used to request snapshots of existing data from the servers.
Send
- message array [instruction, topic, requestId?]
- instruction string = "request"
- Specify that message is a request for data.
- topic string
- The topic specifies which data you are requesting.
- requestId string
- (Optional) These can optionally be used to correlate the response to this request.
Receive
If no requestId was sent, the servers will respond with topic as the first argument.
- message array [topic, data]
- topic string
- The topic will match the one requested.
- data any
- The data payload.
If there are any errors handling the request, they will be send on the "error" topic channel.
Receive (correlated)
Where a requestId is used, the response takes a different form, with the requestId as the first argument. Any errors are including in the response message as the second argument so they can be used with error first callbacks.
- message array [requestId, error?, data?]
- requestId string
- The client specified request identifier.
- error string
- (Optional) Any error handling the request.
- data any
- (Optional) The data payload.
Subscribe
Subscription messages are an instruction to the servers to begin streaming data updates on their topic channel.
Send
- message array [instruction, topic]
- instruction string = "subscribe"
- Specify that message is an instruction to begin streaming data.
- topic string
- The topic specifies which data you are subscribing to.
Receive
Update messages will begin arriving in the form:
- message array [topic, data]
- topic string
- The topic will match the one requested.
- data any
- The data payload.
Unsubscribe
An instruction to the servers to stop streaming.
Send
- message array [instruction, topic]
- instruction string = "unsubscribe"
- Specify that message is an instruction to stop streaming data.
- topic string
- The topic specifies which data you are unsubscribing from.
Submit
Used to submit an order.
Send
- message array [instruction, topic, requestId?]
- instruction string = "submit"
- Specify that message is an order submit.
- topic string = "order"
- The topic specifies that this is an order.
- order order
- The order fields. See [orders]() TODO.
- requestId string
- (Optional) These can optionally be used to correlate the response to this request.
The response behaves in the same way as responses to request messages, above. If no requestId is specified the order will update on the "orders" channel and you should listen on the "error" channel for issues. Where you provide a requestId the response will arrive on the requestId channel and include any error or the submitted order parameters.
Was this page useful? If you find any errors or have any questions please get in touch at support@cloud9trader.com.