# Overview

# 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


1. **Connect** to the WebSocket endpoint with a bearer token in the connection header
2. **Authenticate** by sending an Authorize request (Type 45)
3. **Configure** your user and trade settings (if needed)
4. **Subscribe** to market data or place orders as needed
5. **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)`<br>`User settings (13)`<br>`Trade settings (14)`<br>`Accounts (15)`<br>`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)`<br>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)`<br>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


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

### Placing and Managing Orders


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

### Calculating Margin


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