> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quanux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to Rithmic for futures market data

> Set up the QuanuX Rithmic extension to stream live futures tick data and route orders through Rithmic's high-performance network using native Go and Protobuf.

Rithmic is the high-performance futures data and order routing network used by many prop firms and futures brokerages. The QuanuX Rithmic extension is a pure Go implementation that speaks the Rithmic wire protocol directly — no C++ R/API+ libraries, no Python bridges. It connects to Rithmic's WebSocket servers using SSL, exchanges Protocol Buffer messages, and publishes live tick data to the QuanuX core over a ZeroMQ socket.

## Architecture

The extension runs as a QXP sidecar process. Market data flows from Rithmic's cloud into the Go extension, which then broadcasts ticks to the QuanuX core over a ZMQ PUB socket on port 5557. Order commands travel in the reverse direction.

```mermaid theme={null}
graph LR
    R[Rithmic Cloud] <-- WSS + Protobuf --> E[Go Extension]
    E -- ZeroMQ PUB port 5557 --> C[QuanuX Core]
    C -- QXP commands --> E
```

**Key components:**

* **Official Protobufs**: The extension uses the official Rithmic `.proto` schema (v0.87.0.0+), compiled to Go bindings in `extensions/rithmic/api/`. Do not edit these files manually.
* **Go runtime**: Pure Go for minimal latency and mostly garbage-free streaming.
* **ZeroMQ data pump**: All market data ticks are broadcast via a ZMQ PUB socket on port `5557`.

## The Rithmic wire protocol

Understanding the protocol helps you troubleshoot connection issues.

### Message framing

Every message — both sent and received — is prefixed with a **4-byte Big Endian integer** that indicates the payload length in bytes:

```
[LENGTH (4 bytes, Big Endian)] + [PROTOBUF PAYLOAD (N bytes)]
```

### Template IDs

Rithmic identifies message types using a `template_id` field present in every Protobuf message. The extension routes incoming messages by reading this field first.

| Template ID | Message name                | Description                            |
| ----------- | --------------------------- | -------------------------------------- |
| `10`        | `RequestLogin`              | Primary authentication request         |
| `11`        | `ResponseLogin`             | Auth result — check `rp_code` field    |
| `16`        | `RequestRithmicSystemInfo`  | Step 1 of the connection handshake     |
| `17`        | `ResponseRithmicSystemInfo` | Returns available Rithmic system names |
| `18`        | `RequestHeartbeat`          | Keepalive — send every 30 seconds      |
| `19`        | `ResponseHeartbeat`         | Server acknowledgement of heartbeat    |
| `100`       | `RequestMarketDataUpdate`   | Subscribe or unsubscribe from a symbol |
| `150`       | `LastTrade`                 | Live tick data for a subscribed symbol |

### Authentication handshake

Rithmic requires a two-step connection sequence before you can subscribe to market data.

**Step 1 — Discovery:**

1. Open a WebSocket connection to the Rithmic URL.
2. Send `RequestRithmicSystemInfo` (template ID `16`).
3. Receive `ResponseRithmicSystemInfo` (template ID `17`), which lists valid system names (for example, `"Rithmic Paper Trading"`).
4. Close this connection.

**Step 2 — Login:**

1. Open a new WebSocket connection.
2. Send `RequestLogin` (template ID `10`) with the `system_name` obtained in Step 1.
3. Receive `ResponseLogin` (template ID `11`).
4. If `rp_code == "0"`, you are authenticated and can subscribe to symbols.

**Heartbeat:**

After login, you must send `RequestHeartbeat` (template ID `18`) every **30 seconds**. The server will disconnect you if you miss a heartbeat interval. The exact interval may also be specified in the `heartbeat_interval` field of the login response.

<Warning>
  If the Rithmic server disconnects unexpectedly, check that your heartbeat loop is running and that no firewall or proxy is silently dropping idle WebSocket connections.
</Warning>

## Setup

<Steps>
  <Step title="Set your credentials">
    Store your Rithmic credentials in the OS keyring using `quanuxctl`:

    ```bash theme={null}
    quanuxctl secrets set QUANUX_RITHMIC_USER "your_rithmic_username"
    quanuxctl secrets set QUANUX_RITHMIC_PASS "your_rithmic_password"
    quanuxctl secrets set QUANUX_RITHMIC_SYSTEM "Rithmic Paper Trading"
    quanuxctl secrets set QUANUX_RITHMIC_URL "wss://rituz00100.rithmic.com:443"
    ```

    Replace `"Rithmic Paper Trading"` with the system name provided by your broker or prop firm (for example, `"Rithmic 01 Chicago"` for live trading). Replace the URL with the WebSocket endpoint your firm specifies.

    <Warning>
      Never commit Rithmic credentials to version control. The `quanuxctl secrets` commands store values in the OS keyring, not in any file on disk.
    </Warning>
  </Step>

  <Step title="Export environment variables">
    Before starting the extension, export your credentials into the shell environment:

    ```bash theme={null}
    export QUANUX_RITHMIC_USER=$(quanuxctl secrets get QUANUX_RITHMIC_USER)
    export QUANUX_RITHMIC_PASS=$(quanuxctl secrets get QUANUX_RITHMIC_PASS)
    export QUANUX_RITHMIC_SYSTEM=$(quanuxctl secrets get QUANUX_RITHMIC_SYSTEM)
    export QUANUX_RITHMIC_URL=$(quanuxctl secrets get QUANUX_RITHMIC_URL)
    export QUANUX_BRIDGE_KEY=$(quanuxctl secrets get QUANUX_RITHMIC_BRIDGE_KEY)
    ```
  </Step>

  <Step title="Generate a bridge key">
    If you have not already done so, generate a bridge key so the extension can authenticate to the QuanuX core:

    1. Open the QuanuX web interface.
    2. Go to **Settings → QuanuX Extensions**.
    3. Click **Generate Key** and copy the value.
    4. Store it: `quanuxctl secrets set QUANUX_RITHMIC_BRIDGE_KEY "your_key_here"`
  </Step>

  <Step title="Start the extension">
    Run the Rithmic extension from its directory:

    ```bash theme={null}
    cd extensions/rithmic
    go run main.go
    ```

    On startup, the extension performs the two-step handshake, then begins the heartbeat loop. Once connected, you can subscribe to symbols from the QuanuX core or via `quanuxctl`.
  </Step>
</Steps>

## Required environment variables

| Variable                | Description                           | Example                            |
| ----------------------- | ------------------------------------- | ---------------------------------- |
| `QUANUX_RITHMIC_USER`   | Your Rithmic username                 | `jsmith`                           |
| `QUANUX_RITHMIC_PASS`   | Your Rithmic password                 | —                                  |
| `QUANUX_RITHMIC_SYSTEM` | Rithmic system name from your broker  | `Rithmic Paper Trading`            |
| `QUANUX_RITHMIC_URL`    | Rithmic WebSocket server URL          | `wss://rituz00100.rithmic.com:443` |
| `QUANUX_BRIDGE_KEY`     | Local bridge key for QuanuX core auth | —                                  |

## Directory structure

```text theme={null}
extensions/rithmic/
├── proto/       # Official .proto files — source of truth
├── api/         # Generated Go bindings — do not edit manually
└── main.go      # Extension entry point
```

## Regenerating Protobuf bindings

If Rithmic releases a new schema version, regenerate the Go bindings from the updated `.proto` files:

```bash theme={null}
cd extensions/rithmic
go mod tidy
protoc \
  -I=proto \
  --go_out=api \
  --go_opt=paths=source_relative \
  --go-grpc_out=api \
  --go-grpc_opt=paths=source_relative \
  proto/*.proto
```

<Note>
  If the `.proto` files are missing a `go_package` option, a patch script in the extension directory injects it automatically before running `protoc`.
</Note>

## Subscribing to market data

Once the extension is running, send a `RequestMarketDataUpdate` (template ID `100`) with your exchange and ticker to begin receiving `LastTrade` (template ID `150`) ticks over the ZMQ PUB socket on port `5557`.

QuanuX strategies subscribed to the same ZMQ topic receive ticks in real time without any additional configuration.