How to Subscribe to Real-Time Market Data via Ironbeam WebSockets

A WebSocket market data subscription on the Ironbeam API is a persistent, push-based connection that streams live quotes, market depth, trades, and bar data directly to your application. Instead of polling a REST endpoint, we send updates the moment they happen, which is what automated futures trading systems need to react to price changes without added latency.

We built this streaming layer as part of our REST API specifically because polling doesn’t scale for algorithmic strategies. If your system’s signal depends on current order book state, every millisecond of polling delay is a millisecond of stale information. Below, we walk through the exact technical sequence for connecting to and subscribing on an Ironbeam WebSocket stream, straight from our API documentation.

How do you authenticate before streaming?

You authenticate by sending a POST request to the /auth endpoint with your username, password, and API key. The response returns a bearer token, which you then use to authorize every subsequent REST call and, later, the WebSocket connection itself.

Authentication happens over standard HTTPS, not the WebSocket protocol. A typical auth call looks like this against our demo environment:

POST https://demo.ironbeamapi.com/v2/auth
Content-Type: application/json

{
  “username”: “your_username”,
  “password”: “your_password”,
  “apiKey”: “your_api_key”
}

The response includes a token field. That token is required for every account, order, and streaming call that follows, and it’s passed in the Authorization: Bearer {token} header for REST calls.

How do you create a WebSocket stream?

Before you can open a WebSocket connection, you must call the /stream/create endpoint using your bearer token. This returns a streamId, which is the session identifier the stream endpoint uses to track your subscriptions.

GET https://demo.ironbeamapi.com/v2/stream/create
Authorization: Bearer {token}

The response contains a UUID-formatted streamId, for example 123e4567-e89b-12d3-a456-426614174000. This single stream session carries every subscription type you activate on it, including quotes, depth, trades, trade bars, tick bars, time bars, and volume bars, all multiplexed over the same connection.

How do you connect to the WebSocket endpoint?

Once you have a streamId, you open a WSS connection to the stream endpoint and pass your bearer token as a query parameter rather than a header, since not all WebSocket clients support custom headers during the handshake. The connection URL follows this pattern:

wss://demo.ironbeamapi.com/v2/stream/{streamId}?token={token}

Here is the full sequence in Python, matching the pattern in our documentation:

import requests
import websocket

auth_response = requests.post(
    “https://demo.ironbeamapi.com/v2/auth”,
    json={“username”: “your_username”, “password”: “your_password”, “apiKey”: “your_api_key”}
)
token = auth_response.json()[“token”]

stream_response = requests.get(
    “https://demo.ironbeamapi.com/v2/stream/create”,
    headers={“Authorization”: f”Bearer {token}”}
)
stream_id = stream_response.json()[“streamId”]

ws_url = f”wss://demo.ironbeamapi.com/v2/stream/{stream_id}?token={token}”
ws = websocket.WebSocketApp(ws_url)
ws.run_forever()

Once the socket is open, you activate individual subscriptions against that same streamId through separate REST calls, and data begins flowing over the open connection.

How do you subscribe to quotes, depth, or trades?

You subscribe by calling dedicated REST endpoints scoped to your streamId, passing a comma-separated list of symbols as a query parameter. Each subscription type, quotes, depth, and trades, has its own endpoint, and each must be called at least once before you’ll see corresponding data on the socket.

• Quotes: symbols query parameter on the quote subscription endpoint under /stream/{streamId} (up to 10 instruments), returns data in the q field
• Depth: same pattern, returns Level 2 order book data in the d field
• Trades: same pattern, returns executed trade prints in the tr field
• Trade bars, tick bars, time bars, volume bars: separate subscription endpoints returning bar data in the tb, tc, ti, and vb fields respectively

A typical subscription call looks like:

POST https://demo.ironbeamapi.com/v2/stream/{streamId}/subscribe/quote?symbols=XCME:ES.U16,XCME:6E.U16,XCME:NQ.U16
Authorization: Bearer {token}

If you want to change which instruments you’re watching, you call the same endpoint again with a new symbol list rather than unsubscribing first.

What do the field tags in the stream payload mean?

Every message pushed over the socket is a JSON object where the top-level key identifies the data type. We use short field tags to keep payloads compact for high-frequency data, since every byte matters when you’re streaming quote updates at exchange speed.

This is why we say Ironbeam delivers a professional futures broker experience with a cloud-based futures trading platform underneath it: the same socket carries market data and account state side by side, so your automated system never has to reconcile two separate feeds.

How many instruments can you subscribe to per stream?

Our documentation caps quote, depth, and trade subscriptions at a maximum of 10 instruments per subscription type, per stream. If your strategy needs to watch more than 10 symbols for any one data type, you need to open an additional stream with its own streamId.

• Quotes: 10 instruments maximum per stream
• Depth: 10 instruments maximum per stream
• Trades: 10 instruments maximum per stream
• Symbol format follows the EXCHANGE:SYMBOL pattern, for example XCME:ES.U16

To change your watch list on an existing subscription, call the same subscribe endpoint again with the updated symbol list. This replaces the prior list rather than adding to it, so include every symbol you still want.

What happens when the connection disconnects?

A streamId is not reusable once its WebSocket connection closes, whether the disconnect was intentional or caused by a network drop. You must call /stream/create again to generate a fresh streamId before reconnecting, and then re-run your subscription calls against the new stream.

Build your reconnect logic to treat every disconnect as a full restart of the streaming session:

1. Detect the closed connection in your on_close handler
2. Call /stream/create with your existing bearer token to get a new streamId
3. Open a new WSS connection using that streamId and token
4. Re-issue subscription calls for every symbol and data type you were previously watching

Your bearer token itself does not need to be reissued on every reconnect, only the streamId, unless the token has separately expired.

Why does this matter for automated trading systems?

Push-based streaming removes the latency and bandwidth overhead of polling a REST endpoint on a timer, which matters most for strategies that depend on order book state or need to react to price moves in milliseconds. Ironbeam includes full Level 2 market depth in this same stream at no extra cost to non-professional traders, which most brokers treat as a paid add-on.

Because account updates (orders, fills, balances, positions, risk) ride the same socket as market data, a single connection gives your system a complete, synchronized view of both the market and your own book. That’s a meaningful simplification if you’re building a trading system that has to make decisions and manage risk in the same loop.

Frequently Asked Questions

Do I need a separate token for the WebSocket connection?

No. You use the same bearer token obtained from the /auth endpoint, passed as a token query parameter on the WSS URL rather than as an HTTP header.

Can I subscribe to multiple data types on one stream?

Yes. A single streamId can carry quotes, depth, trades, trade bars, tick bars, time bars, and volume bars simultaneously, each arriving in its own tagged field in the JSON payload.

What is the maximum number of symbols I can watch on one stream?

Quote, depth, and trade subscriptions are each capped at 10 instruments per stream. Watching more than 10 symbols for a given data type requires an additional stream.

Does my streamId stay valid after a disconnect?

No. Every time the WebSocket connection closes, the streamId becomes invalid and you must call /stream/create again to get a new one before reconnecting.

How do I know the connection is still alive?

The stream sends a ping message in the p field every 5 seconds. Your client should treat the absence of pings as a signal to check the connection and reconnect if needed.

Get Streaming

The fastest way to see this in action is to pull your API key and walk through the auth-to-subscribe sequence against our demo environment. Full endpoint specs, request schemas, and response samples are in our API documentation.