Stream API

The BetDEX Stream API provides methods for clients to subscribe to exchange events. Clients connect to the Stream API, authenticate their connection, and then subscribe to the updates they wish to receive.

Connection details

WebSocket host:

wss://sandbox.stream.btdx.io

wss://prod.stream.btdx.io

Message types

There are two types of messages that can be sent to the Stream API:

Authentication
Subscription

Authentication

To authenticate, clients must send an AuthenticationRequest after connecting. The accessToken is available from the REST API when creating a session.

AuthenticationRequest

{
  "action": "authenticate",
  "accessToken": "string"
}

Subscription

To subscribe to updates, clients must send a SubscriptionRequest describing the type of update and the IDs they are interested in.

The subscriptionType field defines the type for which subscription is made. Allowed values are:
- EventUpdate
- MarketUpdate
- MarketPriceUpdate- all price changes in a market, both direct and derived prices (cross matching liquidity)
- MarketDirectPriceUpdate - direct only price changes in a market (excluding derived prices/cross matching liquidity triggered updates)
- MarketStatusUpdate
- OrderUpdate
- WalletUpdate
The subscriptionIds field determines the entities to subscribe to. Allowed values are:
- For EventUpdate, it can be set to
- * - all events
- event-id - specific events
- ForMarketUpdate, MarketPriceUpdate, MarketDirectPriceUpdateand MarketStatusUpdate it can be set to:
- * - all markets
- market-id - specific markets

Please note for Market subscriptions:If you are subscribing to get a large set of markets, then you should subscribe using the wildcard * as otherwise you will hit subscription limits (max 500).COMING SOON: We will also be soon introducing ability to subscribe at a sport and league level too (ie. to subscribe to all Football or all NFL price updates in one subscription, rather than having to do the wildcard for all markets and then filtering down to what you need on your side)

For OrderUpdate it can be set to:
- *
- order-id — subscribe to updates for an order identified by its id.
- app-id:* — subscribe to all orders owned by app-id (only the connection’s app-id is allowed).
- app-id:wallet-id — subscribe to all orders owned by app-id and wallet-id (only the connection’s app-id is allowed, and the wallet must be owned by that app-id).
For WalletUpdate it can be set to
- * - all wallets owned by your app
- wallet-id - specific wallet owned by your app

Setting subscriptionId to * means the client will be subscribed to all updates of the given type.

SubscriptionRequest

{
  "action": "subscribe",
  "subscriptionType": "EventUpdate | MarketUpdate | MarketPriceUpdate | MarketDirectPriceUpdate | MarketStatusUpdate | OrderUpdate | WalletUpdate",
  "subscriptionIds": ["string"]
}

Subscription Limits

To keep the system performance strong for every client, we’re introducing the following limits:

10 active connections at any one time
500 active individual subscriptions at any one time - these can be spread across the number of active connections as needed.
500 subscriptions per minute.

Recommendation: for Stream API connections & subscriptions, if you are currently subscribing to markets by single market ids, then look at utilising the wildcard "*" instead.For example, if you are subscribing just for a few markets, then

  "subscriptionIds": ["400001, 400002, 400003, 400004, 400005, 400006, 400007, 400008, 400009, 400010"]

makes sense.However if you are subscribing to 501+ markets, you’ll need to use

  "subscriptionIds": ["*"]

UnsubscriptionRequest

{
  "action": "unsubscribe",
  "subscriptionType": "EventUpdate | MarketUpdate | MarketPriceUpdate | MarketStatusUpdate | OrderUpdate | WalletUpdate",
  "subscriptionIds": ["string"]
}

Update messages

After authentication and subscription, clients will receive update messages when markets, orders, or wallets are updated on the platform. The supported update message formats are listed below.

EventUpdateMessage

{
  "eventId": "string",
  "eventGroupId": "string",
  "eventGroupName": "string",
  "subcategoryId": "string",
  "subcategoryName": "string",
  "categoryId": "string",
  "categoryName": "string",
  "appId": "string",
  "name": "string",
  "code": "string",
  "active": "boolean",
  "expectedStartTime": "string (date-time)",
  "createdAt": "string (date-time)",
  "modifiedAt": "string (date-time)"
}

Example:

{"type":"EventUpdate","eventId":"28282","eventGroupId":"NHL","eventGroupName":"NHL","subcategoryId":"ICEHKY","subcategoryName":"Ice Hockey","categoryId":"SPORTS","categoryName":"Sports","appId":"APPID","name":"Washington Capitals v Pittsburgh Penguins","code":"NHL-washington-capitals-v-pittsburgh-penguins-1791415800","active":true,"expectedStartTime":"2026-10-07T23:30:00.000Z","createdAt":"2026-10-05T23:33:42.126Z","modifiedAt":"2026-10-07T12:22:19.351Z"}

MarketUpdateMessage

{
  "marketId": "string",
  "appId": "string",
  "eventId": "string",
  "eventGroupId": "string",
  "categoryId": "string",
  "subCategoryId": "string",
  "name": "string",
  "marketTypeId": "string",
  "marketValue": "string",
  "marketDiscriminator": "string | null",
  "escrowWalletId": "string",
  "currencyId": "string",
  "marketOutcomes": [
    {
      "outcomeId": "string",
      "title": "string",
      "ordering": 0,
      "winner": "string | null",
      "participantId": "string | null",
      "createdAt": "string (date-time)",
      "modifiedAt": "string (date-time)"
    }
  ],
  "crossMatchingEnabled": "boolean",
  "lockAt": "string (date-time)",
  "settledAt": "string (date-time) | null",
  "marketLockAction": "None | CancelUnmatchedLiquidity",
  "eventStartAction": "None | CancelUnmatchedLiquidity",
  "status": "Initializing | Open | Locked | Settling | Settled | Voiding | Voided | Closed",
  "published": "boolean",
  "suspended": "boolean",
  "inPlayStatus": "NotApplicable | PrePlay | InPlay",
  "inPlayDelay": 0,
  "createdAt": "string (date-time)",
  "modifiedAt": "string (date-time)"
}

MarketStatusUpdateMessage

{
  "marketId": "string",
  "eventId": "string",
  "eventGroupId": "string",
  "categoryId": "string",
  "subCategoryId": "string",
  "status": "Initializing | Open | Locked | Settling | Settled | Voiding | Voided | Closed",
  "published": "boolean",
  "suspended": "boolean",
  "inPlayStatus": "NotApplicable | PrePlay | InPlay"
}

Example:

{"type":"MarketStatusUpdate","marketId":"898792","eventId":"28282","eventGroupId":"NHL","categoryId":"SPORTS","subCategoryId":"ICEHKY","status":"Open","published":true,"suspended":false,"inPlayStatus":"PrePlay"}

MarketPriceUpdateMessage & MarketDirectPriceUpdateMessage

{
  "updateType": "Snapshot | Incremental",
  "marketId": "string",
  "eventId": "string",
  "eventGroupId": "string",
  "categoryId": "string",
  "subCategoryId": "string",
  "prices": [
    {
      "side": "For | Against",
      "outcomeId": "string",
      "price": "number",
      "liquidity": "number",
      "change": "number",
      "validAt": "string (date-time)"
    },
    {
      "side": "For | Against",
      "outcomeId": "string",
      "price": "number",
      "liquidity": "number",
      "change": "number",
      "validAt": "string (date-time)"
    }
  ]
}

Snapshot Example:

{"type":"MarketPriceUpdate","updateType":"Snapshot","marketId":"898792","eventId":"28282","eventGroupId":"NHL","categoryId":"SPORTS","subCategoryId":"ICEHKY","prices":[{"side":"Against","outcomeId":"2067060","price":1.97,"liquidity":40.61,"change":40.61,"validAt":"2026-10-07T12:26:25.468Z"},{"side":"Against","outcomeId":"2067060","price":2,"liquidity":50,"change":50,"validAt":"2026-10-07T12:26:25.446Z"},{"side":"Against","outcomeId":"2067060","price":2.06,"liquidity":38.76560013,"change":38.76560013,"validAt":"2026-10-07T12:26:25.543Z"},{"side":"Against","outcomeId":"2067060","price":2.08,"liquidity":47.6476002,"change":47.6476002,"validAt":"2026-10-07T12:26:25.520Z"},{"side":"Against","outcomeId":"2067061","price":1.8,"liquidity":44.44,"change":44.44,"validAt":"2026-10-07T12:26:25.576Z"},{"side":"Against","outcomeId":"2067061","price":1.81,"liquidity":43.96880002,"change":43.96880002,"validAt":"2026-10-07T12:26:25.442Z"},{"side":"Against","outcomeId":"2067061","price":1.83,"liquidity":54.64,"change":54.64,"validAt":"2026-10-07T12:26:25.546Z"},{"side":"Against","outcomeId":"2067061","price":1.86,"liquidity":53.70800015,"change":53.70800015,"validAt":"2026-10-07T12:26:25.425Z"},{"side":"For","outcomeId":"2067060","price":2.16,"liquidity":46.3,"change":46.3,"validAt":"2026-10-07T12:26:25.397Z"},{"side":"For","outcomeId":"2067060","price":2.22,"liquidity":81.39119994,"change":81.39119994,"validAt":"2026-10-07T12:26:25.422Z"},{"side":"For","outcomeId":"2067060","price":2.26,"liquidity":35.552,"change":35.552,"validAt":"2026-10-07T12:26:25.601Z"},{"side":"For","outcomeId":"2067061","price":1.91,"liquidity":52.36,"change":52.36,"validAt":"2026-10-07T12:26:25.497Z"},{"side":"For","outcomeId":"2067061","price":1.94,"liquidity":41.24,"change":41.24,"validAt":"2026-10-07T12:26:25.522Z"},{"side":"For","outcomeId":"2067061","price":2,"liquidity":50,"change":50,"validAt":"2026-10-07T12:26:25.465Z"},{"side":"For","outcomeId":"2067061","price":2.04,"liquidity":39.3916999,"change":39.3916999,"validAt":"2026-10-07T12:26:25.491Z"}]}

Incremental Example:

{"type": "MarketPriceUpdate","updateType": "Incremental","marketId": "867386","eventId": "412093","eventGroupId": "EPL","categoryId": "FOOTBALL","subCategoryId": "SOCCER",
"prices": [
    {"side":"For",     "outcomeId":"2001","price":2.5,"liquidity":6, "change":6, "validAt":"2026-10-01T10:15:00.061Z"},
    {"side":"For",     "outcomeId":"2001","price":3.0,"liquidity":5, "change":5, "validAt":"2026-10-01T10:15:00.061Z"},
    {"side":"Against", "outcomeId":"2002","price":1.6,"liquidity":12,"change":12,"validAt":"2026-10-01T10:15:00.062Z"}
  ]
}

OrderUpdateMessage

{
  "orderId": "string",
  "eventId": "string",
  "eventGroupId": "string",
  "categoryId": "string",
  "subCategoryId": "string",
  "marketId": "string",
  "walletId": "string",
  "status": "Cancelled | Matched | PartiallyMatched | Unmatched | Won | Lost | Voided",
  "side": "For | Against",
  "outcomeIndexId": "string",
  "price": 0.0,
  "priceAvg": 0.0,
  "totalExposure": 0.0,
  "stake": 0.0,
  "stakeUnmatched": 0.0,
  "stakeVoided": 0.0,
  "reference": "string",
  "createdAt": "string (date-time)",
  "modifiedAt": "string (date-time)",
  "trades": [
    {
      "tradeId": "string",
      "side": "For | Against",
      "price": 0.0,
      "stake": 0.0,
      "createdAt": "string (date-time)"
    }
  ],
  "cancellationReason": "string"
}

Order Created Example:

{"type":"OrderUpdate","orderId":"305137051","eventId":"56653","eventGroupId":"SULG","categoryId":"SPORTS","subCategoryId":"FOOTBALL","marketId":"1569503","walletId":"ANAPPID-User","status":"Unmatched","side":"For","outcomeIndexId":"3517754","price":14.0,"priceAvg":null,"totalExposure":0,"stake":7.0,"stakeUnmatched":7.0,"stakeVoided":0,"reference":"YourReference001","createdAt":"2026-09-11T07:22:38.552Z","modifiedAt":"2026-09-11T07:22:38.552Z","trades":[],"cancellationReason":null}

Order Cancelled Example:

{"type":"OrderUpdate","orderId":"305137051","eventId":"56653","eventGroupId":"SULG","categoryId":"SPORTS","subCategoryId":"FOOTBALL","marketId":"1569503","walletId":"ANAPPID-User","status":"Cancelled","side":"For","outcomeIndexId":"3517754","price":14.00,"priceAvg":null,"totalExposure":0,"stake":7.000000000000,"stakeUnmatched":0,"stakeVoided":7.000000000000,"reference":"YourReference002","createdAt":"2026-09-11T07:22:38.552Z","modifiedAt":" ,"trades":[],"cancellationReason":"Requested"}

WalletUpdateMessage

{
  "walletId": "string",
  "currencyId": "string",
  "balance": 0.0,
  "change": 0.0
}

Next steps

For session creation and access tokens, refer to the REST API (BetDEX) documentation.

Get started

BetDEX API (basic)

BetDEX API (premium)

Stream API

Connection details

Message types

Authentication

AuthenticationRequest

Subscription

SubscriptionRequest

Subscription Limits

UnsubscriptionRequest

Update messages

EventUpdateMessage

MarketUpdateMessage

MarketStatusUpdateMessage

MarketPriceUpdateMessage & MarketDirectPriceUpdateMessage

OrderUpdateMessage

WalletUpdateMessage

Next steps

​Connection details

​Message types

​Authentication

​AuthenticationRequest

​Subscription

​SubscriptionRequest

​Subscription Limits

​UnsubscriptionRequest

​Update messages

​EventUpdateMessage

​MarketUpdateMessage

​MarketStatusUpdateMessage

​MarketPriceUpdateMessage & MarketDirectPriceUpdateMessage

​OrderUpdateMessage

​WalletUpdateMessage

​Next steps

Connection details

Message types

Authentication

AuthenticationRequest

Subscription

SubscriptionRequest

Subscription Limits

UnsubscriptionRequest

Update messages

EventUpdateMessage

MarketUpdateMessage

MarketStatusUpdateMessage

MarketPriceUpdateMessage & MarketDirectPriceUpdateMessage

OrderUpdateMessage

WalletUpdateMessage

Next steps