Overview

This document describes the capabilities of the Rival Websocket API and demonstrates how to receive market data, place orders, and access risk-related information.

Quick Start

Connect to the WebSocket endpoint with a bearer token in the connection header
Authenticate by sending an Authorize request (Type 45)
Configure your user and trade settings (if needed)
Subscribe to market data or place orders as needed
Maintain connection with periodic Ping messages (Type 26)

Typical Workflow

The Rival Websocket API works in conjunction with Rival Servers that provide market data, execution capabilities, and risk information. Connect using a secure websocket, establish your identity, and start sending/receiving messages. User entitlements (baked into the API key) determine what information is available.

Connection Flow

1. Connect → WebSocket with Bearer Token
2. Authenticate → Authorize (45) → Receive: Authorize (9), Settings (13, 14), Accounts (15), Routes (38)
3. Configure → Update User Settings (14) / Trade Settings (13) [if needed]
4. Subscribe → Market Data (0) or other subscriptions
5. Trade → Send Orders (2), Monitor Status (8)
6. Maintain → Ping (26) every < 5 minutes

General Information

Endpoints

Simulation: sim-api.rivalsystems.cloud:50443
Production: prod-api.rivalsystems.cloud:60443

Connection Requirements

Heartbeat: Send a Ping (26) message at least every 5 minutes to avoid disconnection
Timestamps: All timestamps are UTC epochs, unless noted otherwise
Case Sensitivity: All field names and values are case-sensitive, unless noted otherwise

API Conventions

Data Types

All price and quantity fields are floating point numbers. Use appropriate floating-point parsing logic.
Using integer/long parsing will cause exceptions.

Exchange Naming

The server uses the following full qualifying names for CME sub-exchanges:

Sub-Exchange	Full Name
Globex	`CME`
Nymex	`CME-NYMEX`
Comex	`CME-COMEX`
Cbot	`CME-CBOT`
MGE	`CME-MGE`

Note: These sub-exchanges do not apply to ICE. For example, ICE LIFFE and ICE US are both termed ICE.

User Setup

When constructing user settings, pay attention to these key concepts that determine order routing and visibility:

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. Multiple traders can be defined within a trading group.

The server uses these values to determine:

Where orders are routed
Who can see your orders (all traders in the same group can see each other's orders)

WARNING: For security reasons, Rival assigns the GroupName value. You CANNOT change this value. Unauthorized or unilateral changes will result in client termination and a review.

Common Errors

When logging into the API, you might encounter this error in response to a login message:

API user not registered with the system | Grp=[SOMETHING.JSMITH], User=[jsmith]

This typically indicates an issue with your login credentials, most likely with the group name you're passing.

Contact Information

For questions related to the API, contact: rivalapisupport@rivalsystems.com

Message Type Reference

By Functional Area

Authentication & Connection

Request	Response	Notes
`Authorize (45)`	`Authorize (9)` `User settings (13)` `Trade settings (14)` `Accounts (15)` `Broker routes (38)`	Multiple responses sent automatically on successful auth
`Ping (26)`	`Pong (26)`	Use for heartbeat

Market Data

Request	Response	Notes
`Market data (0)`	Success: `Instrument definition (1)`, `Book (2)`, `Top-of-book (35)`, `Trade (5)`, `Volume at level (31)`, `Statistics (6)` Error:`Error (3, 21, 23)`	Subscribes to all market data types
`Term-Market data for options (40)`	Market data messages	Subscribe/unsubscribe to options series
`Market data for strategies (42)`	Market data messages	Subscribe/unsubscribe to option strategies
`Depth data (58)`	`Participant market data (61)`	Equities only

Order Management

Request	Response	Notes
`Send order (2)`	`Order Status (8)`
`Revise order (4)`	`Order Status (8)`	Cancel-replace
`Cancel order (3)`	`Order Status (8)`	Cancel by order ID(s)
`Cancel buy orders (6)`	`Order Status (8)`	Cancel all buys for symbol
`Cancel sell orders (7)`	`Order Status (8)`	Cancel all sells for symbol
`Cancel all orders (5)`	`Order Status (8)`	Cancel all (optionally by symbol)
`Get all orders (8)`	`List of Order Status (8)`	Fetches all orders

Options & Strategies

Request	Response	Notes
`Get Options description (34)`	`Option descriptions (34)`	Search option terms
`Get options strategies (41)`	`Option strategies (43)`, Market data messages	Paginated results
`Get spread combinations (37)`	`Spread classification (40)`	Find possible spreads
`Send RFQ/Create Spread (38)`	`Spreads (44)` or `RFQ Failed (42)`	Create new spread
`Get theos and greeks (53)`	`Theo & Greeks (39)`	Requires entitlements

Settings & Configuration

Request	Response	Notes
`Update Trade settings (13)`	`Trade settings (14)`
`Delete Trade settings (21)`	`Trade settings (14)`
`Update User settings (14)`	`User settings (13)`

Risk & Positions

Request	Response	Notes
`Get positions (22)`	`Position summary (20)`	Subscribe to real-time positions
`Get margin (43)`	`Margin (46)` or `Margin error (45)`	Calculate risk margin
`Get variable tick size (39)`	`Tick size (41)`	For options/strategies

Search & Discovery

Request	Response	Notes
`Instrument search (33)`	`Search results (33)`	Find instruments by partial symbol
`Enter/Edit/Delete Manual Trade (49)`	Success: `Trade (37)` Error:`Error (13)`	Manual trade entry

Quick Reference by Message Type

Type	Name	Direction	Category
0	Market data	Request/Response	Market Data
1	Instrument definition	Response	Market Data
2	Book / Send order	Request/Response	Market Data / Orders
3	Error / Cancel order	Request/Response	Errors / Orders
4	Revise order	Request	Orders
5	Trade / Cancel all orders	Request/Response	Market Data / Orders
6	Cancel buy orders	Request	Orders
7	Cancel sell orders	Request	Orders
8	Get all orders / Order Status	Request/Response	Orders
9	Authorize	Response	Authentication
13	Update Trade settings / User settings	Request/Response	Settings
14	Trade settings / Update User settings	Request/Response	Settings
15	Accounts	Response	Authentication
20	Position summary	Response	Risk
21	Not entitled error / Delete Trade settings	Request/Response	Errors / Settings
22	Get positions	Request	Risk
23	Security not found error	Response	Errors
26	Ping / Pong	Request/Response	Connection
31	Volume at level	Response	Market Data
33	Instrument search	Request/Response	Search
34	Get Options description	Request/Response	Options
35	Top-of-book	Response	Market Data
37	Trade / Get spread combinations	Request/Response	Market Data / Options
38	Broker routes / Send RFQ	Request/Response	Authentication / Options
39	Get theos and greeks / Variable tick size	Request/Response	Options
40	Term-Market data / Spread classification	Request/Response	Options
41	Get options strategies / Tick size	Request/Response	Options
42	Market data for strategies / RFQ failed	Request/Response	Options
43	Get margin / Available strategies	Request/Response	Risk / Options
44	Spreads	Response	Options
45	Authorize / Margin error	Request/Response	Authentication / Risk
46	Margin	Response	Risk
49	Enter/Edit/Delete Manual Trade	Request	Trades
53	Get theos and greeks	Request	Options
58	Depth data	Request	Market Data
61	Participant market data	Response	Market Data

Common Patterns

Subscribing to Options Market Data

Search for symbols Instrument search (33)
Send Market data (0) with IncludeOptions: true
Send Term-Market data for options (40) for specific option series
Receive market data messages (2, 35, 5, 31, 6) for subscribed options

Placing and Managing Orders

Ensure trade settings are configured (Type 13)
Send Send order (2) with order details
Monitor Order Status (8) messages for updates
Use Revise order (4) or Cancel order (3) to modify/cancel

Calculating Margin

Prepare position data as CSV records
Send Get margin (43) with positions and margin type flags
Receive Margin (46) for successful calculations
Check Margin error (45) for any position errors