> ## 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 QuanuX to TopstepX prop firm

> Set up the TopstepX REST extension and SignalR bridge to trade, manage accounts, and receive real-time market data from the TopstepX prop trading platform.

The TopstepX integration gives QuanuX full access to the TopstepX platform: account management, order execution, position tracking, and real-time market data. It is split into two decoupled components that run alongside the QuanuX core. The **TopstepX extension** handles REST API calls — authentication, orders, account queries, and trade history. The **SignalR bridge** maintains a persistent WebSocket connection to TopstepX's real-time hubs, streaming market data and user events into the QuanuX message bus.

## Architecture

```mermaid theme={null}
graph TD
    User[QuanuX Core / Agent] -->|commands| TSX[TopstepX Extension]
    User -->|market data| SRB[SignalR Bridge]
    TSX -->|REST API| API[api.topstepx.com]
    SRB -->|WebSocket| Hubs[rtc.topstepx.com]
```

The two components are independent. You can run the REST extension without the SignalR bridge if you only need account management and order placement, or run just the bridge if you only need real-time data.

## Prerequisites

You need three pieces of information from TopstepX before you can connect:

* **Username**: your TopstepX account username
* **Password**: your TopstepX account password
* **API key**: your TopstepX API key, available from the TopstepX dashboard

## Setup

<Steps>
  <Step title="Store your credentials">
    Use `quanuxctl` to save your TopstepX credentials to the OS keyring. These are never written to a file on disk.

    ```bash theme={null}
    quanuxctl topstepx user "your_topstepx_username"
    quanuxctl topstepx password "your_topstepx_password"
    quanuxctl topstepx apikey "your_topstepx_api_key"
    ```

    <Warning>
      Never store TopstepX credentials in environment files or commit them to version control. Use `quanuxctl` exclusively.
    </Warning>
  </Step>

  <Step title="Verify your environment">
    Confirm that all credentials are accessible:

    ```bash theme={null}
    quanuxctl topstepx env
    ```

    This command reads each credential from the keyring and prints its status without revealing the values.
  </Step>

  <Step title="Install Python dependencies">
    The TopstepX REST extension is Python-based. Install its dependencies:

    ```bash theme={null}
    quanuxctl topstepx install
    ```

    This installs the packages required by `extensions/python/topstepx`.
  </Step>

  <Step title="Generate a bridge key">
    Generate a key so both extensions can authenticate to the QuanuX core:

    1. Open the QuanuX web interface.
    2. Go to **Settings → QuanuX Extensions**.
    3. Click **Generate Key** and store the value:

    ```bash theme={null}
    quanuxctl secrets set QUANUX_TOPSTEP_BRIDGE_KEY "your_key_here"
    ```
  </Step>

  <Step title="Start the SignalR bridge">
    Check the bridge status, then start it:

    ```bash theme={null}
    quanuxctl bridge status
    quanuxctl bridge run
    ```

    The bridge connects to both the user hub and the market hub on startup. Once running, real-time events flow into the QuanuX message bus automatically.
  </Step>
</Steps>

## Credentials reference

All credentials are managed through `quanuxctl` and stored in the OS keyring under the following keys:

| Keyring key                | `quanuxctl` command           | Description               |
| -------------------------- | ----------------------------- | ------------------------- |
| `QUANUX_TOPSTEP__USERNAME` | `quanuxctl topstepx user`     | TopstepX account username |
| `QUANUX_TOPSTEP__PASSWORD` | `quanuxctl topstepx password` | TopstepX account password |
| `QUANUX_TOPSTEP__API_KEY`  | `quanuxctl topstepx apikey`   | TopstepX API key          |

## Endpoint configuration

The extensions connect to TopstepX's production endpoints by default. You can override any endpoint — for example, to point at a simulation environment.

| Variable                       | Default                                | Description               |
| ------------------------------ | -------------------------------------- | ------------------------- |
| `QUANUX_TOPSTEP__BASE_API_URL` | `https://api.topstepx.com`             | REST API base URL         |
| `QUANUX_SIGNALR_USER_HUB`      | `https://rtc.topstepx.com/hubs/user`   | Real-time user events hub |
| `QUANUX_SIGNALR_MARKET_HUB`    | `https://rtc.topstepx.com/hubs/market` | Real-time market data hub |

To override an endpoint for a simulation environment:

```bash theme={null}
quanuxctl topstepx user-hub "https://sim-rtc.topstepx.com/hubs/user"
quanuxctl topstepx market-hub "https://sim-rtc.topstepx.com/hubs/market"
```

## Managing the SignalR bridge

The bridge runs as a separate process managed by QuanuX. It maintains a persistent WebSocket connection to both TopstepX real-time hubs.

<CodeGroup>
  ```bash Check bridge status theme={null}
  quanuxctl bridge status
  ```

  ```bash Start bridge manually theme={null}
  quanuxctl bridge run
  ```
</CodeGroup>

<Note>
  The SignalR bridge uses a Node.js worker by default to handle TopstepX's proprietary SignalR protocol. A Flask fallback is also available if Node.js is not present.
</Note>

## REST extension modules

The TopstepX Python extension lives in `extensions/python/topstepx/src`. Its modules correspond directly to the TopstepX API surface:

| Module         | Purpose                                       |
| -------------- | --------------------------------------------- |
| `auth.py`      | Authentication and token lifecycle management |
| `orders.py`    | Order placement and management                |
| `positions.py` | Position tracking                             |
| `history.py`   | Historical bar retrieval                      |

## REST API endpoints

The QuanuX server exposes the following routes for the TopstepX integration. These are used internally by the QuanuX core and can also be called directly for debugging.

<Tabs>
  <Tab title="Authentication">
    **POST `/topstep/login`**

    Authenticates with TopstepX and returns a session token.

    ```json theme={null}
    {
      "username": "your_username",
      "password": "your_password",
      "apikey": "your_api_key"
    }
    ```
  </Tab>

  <Tab title="Accounts">
    **GET `/topstep/accounts`**

    Returns all accounts associated with the authenticated session.

    Pass the token returned by `/topstep/login` as the `token` query parameter.
  </Tab>

  <Tab title="SignalR connect">
    **POST `/topstep/connect`**

    Connects the SignalR bridge to a hub URL.

    ```json theme={null}
    {
      "hub_url": "https://rtc.topstepx.com/hubs/market",
      "access_token": "your_token",
      "skip_negotiation": false
    }
    ```
  </Tab>

  <Tab title="SignalR subscribe">
    **POST `/topstep/subscribe`**

    Subscribes to a SignalR method on the connected hub.

    ```json theme={null}
    {
      "method": "GatewayQuoteReceived",
      "args": ["ES"]
    }
    ```
  </Tab>
</Tabs>