Overview
The purpose of this document is to describe the capabilities of the Rival Websocket API, and demonstrate with examples how to receive market data, place orders and access risk-related information.
Typical workflow
The Rival Websocket API is meant to work in conjunction with Rival Servers that provide market data, execution capabilities and risk information. The idea is for the user to connect in using a secure websocket, establish their identity (using the mechanism described below) and start sending/receiving messages as desired. User entitlements, which is baked into the API key will determine what kind of information is available to them.
General Info
General API information
Simulation endpoint :
sim-api.rivalsystems.cloud:50443Production endpoint :
prod-api.rivalsystems.cloud:60443If the server does not receive a message on the wire for more than 5 minutes, you will be disconnected. Heartbeating (message type 26) should be utilized to avoid this.
All timestamps are in UTC epochs, unless noted otherwise.
All field names and values are case-sensitive, unless noted otherwise.
API conventions
General
All the price and quantity fields in the messages are floating point numbers- please use the appropriate parsing logic for them.
Using integer/long parsing logic will cause exceptions to get thrown.
The server defines the following full qualifying names when dealing with the CME's sub-exchanges:
Globex => CME
Nymex => CME-NYMEX
Comex => CME-COMEX
Cbot => CME-CBOT
MGE => CME-MGE
Note that these sub exchanges do not apply to the ICE. For example, ICE LIFFE and ICE US are both termed ICE.
User setup
When constructing your user settings, you will need to pay attention to the following main concepts that deal with how you are setup from a trading perspective. The server defines two important characteristics of a user that determine how orders are routed, and who can see your orders. They are:
GroupName: An abstract 'bucket' that defines your trading group, which can be considered a single entity belonging to a broader firm.TraderName: The name of the individual trader. There can be multiple traders defined inside of a trading group.
When placing orders, the server uses these two values to determine where your order needs to get routed to, as well as who can see your orders.
All traders belonging to the same trading group can see each other's orders.
WARNING For security reasons, Rival will be the one assigning you a GroupName value. You CANNOT change this value. Unauthorized or unilateral changes to this group from a user will result in the termination of the client and force a review.
Common errors
When logging into the API, you might encounter the following error in response to a login message:
API user not registered with the system | Grp=[SOMETHING.JSMITH], User=[jsmith]This means there might be something going on with your login credentials, most likely with the group name you are passing.
Contact Info
For any questions related to the API, please contact
rivalapisupport@rivalsystems.com
Pairing request and response types
In general, the request and the corresponding response types are one-to-one in nature, meaning you will get a single response when you place a request. Sometimes, there might be a series of responses to a request message because the responses can be of different data types. The following table can be used as reference guide when trying to match up a request with its corresponding response(s).
When I send this request of type | I should expect to receive responses of types |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|