# Sister Song Streaming API

Sister Song publishes **AI commentary and bets** from each strategy (an AI persona), with its live results, and **match data**: status and scores, events, text commentary, pressure and live odds. [Staying up to date](#staying-up-to-date) explains how we announce changes, and the [glossary](#glossary) explains the terms.

## How it works

1. **Find a match.** `GET /fixtures/live` lists the matches being streamed. A fixture's `id` is the `match_id` you stream.
2. **Open a stream.** Over SSE, one HTTP request per match and language. Over a WebSocket, one connection for any number of matches.
3. **Get the replay, then live messages.** Every stream starts with a replay of everything already published for the match, then sends each new message as it's published.

## Quick start

The examples use FC Barcelona vs Real Madrid (`match_id` 19732648, 25 October 2026), shortened in places.

1. **Get your token and strategy IDs.** Sign in at [song.brainanalytics.co](https://song.brainanalytics.co/docs). Once Brain Analytics has linked your account to your client, this step shows your token and the IDs of the strategies you can stream. Settings shows the token too. Strategy IDs are short text IDs, such as `sister-song-v1`.

2. **Find a match.** Call `GET /fixtures/live`, or `GET /fixtures/upcoming` before kick-off. A fixture's `id` is the `match_id` you stream.

   ```bash
   curl -H "X-Token: YOUR_TOKEN" https://publisher.prod.song.brainanalytics.co/fixtures/live
   ```

   ```js
   const response = await fetch("https://publisher.prod.song.brainanalytics.co/fixtures/live", {
     headers: { "X-Token": "YOUR_TOKEN" },
   });
   const { fixtures } = await response.json();
   ```

   ```python
   import httpx

   response = httpx.get(
       "https://publisher.prod.song.brainanalytics.co/fixtures/live",
       headers={"X-Token": "YOUR_TOKEN"},
   )
   fixtures = response.json()["fixtures"]
   ```

3. **Open a stream.** SSE is the simplest option: one HTTP request per match.

   ```bash
   curl -N -H "X-Token: YOUR_TOKEN" "https://publisher.prod.song.brainanalytics.co/sse?match_id=19732648&topics=ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_status&language=en"
   ```

   ```js
   const url = new URL("https://publisher.prod.song.brainanalytics.co/sse");
   url.searchParams.set("match_id", "19732648");
   url.searchParams.set("topics", "ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_status");
   url.searchParams.set("language", "en");
   url.searchParams.set("token", "YOUR_TOKEN"); // a browser's EventSource can't send headers

   const seen = new Set();

   function handle(msg) {
     if (msg.seq) {
       // The end of a replay can repeat the first live messages.
       const key = `${msg.match_id}|${msg.topic}|${msg.language}|${msg.seq}`;
       if (seen.has(key)) return;
       seen.add(key);
     }
     show(msg.publish_type, msg.data);
   }

   let delay = 1000;

   function connect() {
     const source = new EventSource(url);
     source.onmessage = (event) => {
       delay = 1000;
       const frame = JSON.parse(event.data);
       if (frame.publish_type !== "snapshot") return handle(frame);
       if (frame.chunk === 1) {
         seen.clear();
         clearMatch(); // a new replay is starting
       }
       frame.messages.forEach(handle);
     };
     source.onerror = () => {
       // EventSource reconnects by itself, except after an HTTP error such as a 502 during a deploy.
       if (source.readyState !== EventSource.CLOSED) return;
       setTimeout(connect, delay);
       delay = Math.min(delay * 2, 30000);
     };
   }

   connect();
   ```

   ```python
   import json

   import httpx

   params = {
       "match_id": 19732648,
       "topics": "ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_status",
       "language": "en",
   }
   seen = set()


   def handle(msg):
       if msg.get("seq"):
           # The end of a replay can repeat the first live messages.
           key = (msg["match_id"], msg["topic"], msg["language"], msg["seq"])
           if key in seen:
               return
           seen.add(key)
       print(msg["publish_type"], msg["data"])


   # The server sends ": ping" after 15 quiet seconds, so a minute of silence means the connection is gone.
   with httpx.stream(
       "GET",
       "https://publisher.prod.song.brainanalytics.co/sse",
       params=params,
       headers={"X-Token": "YOUR_TOKEN"},
       timeout=httpx.Timeout(10, read=60),
   ) as response:
       response.raise_for_status()
       for line in response.iter_lines():
           if not line.startswith("data: "):
               continue  # ": ok", ": ping" and the blank lines between frames
           frame = json.loads(line[len("data: "):])
           if frame["publish_type"] != "snapshot":
               handle(frame)
               continue
           if frame["chunk"] == 1:
               seen.clear()  # a new replay is starting
           for msg in frame["messages"]:
               handle(msg)
   ```

   > [!TIP]
   > Want to see the stream before writing any code? [Try it live](https://song.brainanalytics.co/docs/try?match_id=19732648) replays this match in your browser, with your token.

4. **Read the replay, then live messages.** The stream starts with `snapshot` frames that replay everything already published for the match. After that, you get each new message as it's published. The samples drop the duplicates where the two meet, and start over when a new replay begins (`chunk: 1`). `show` and `clearMatch` stand for your own rendering code.

## Before you go live

Check that your client:

- **Drops duplicates** on `(match_id, topic, language, seq)`. The end of a replay can repeat the first live messages. See [Duplicates and gaps](#duplicates-and-gaps).
- **Starts over on `chunk: 1`.** Every connection, and every WebSocket `subscribe`, begins with a fresh replay. See [Replay frames](#replay-frames).
- **Reconnects.** Over SSE, reconnect yourself with a backoff after an HTTP error, such as a `502` during a deploy. Over a WebSocket, send `{"command": "ping"}` at least every 30 seconds. See [Reconnecting](#reconnecting) and [Keeping the connection alive](#keeping-the-connection-alive).
- **Orders each stream by `seq`, not by minute.** AI minutes hold still through half-time and can step back at full time. See [Ordering](#ordering).
- **Doesn't assume clocks only go up.** The period clocks in `match_status` can jump ahead or back. See [Periods](#periods).
- **Copes without pressure.** Some competitions, currently including the UEFA Champions League, have no `pressure` messages. See [`pressure`](#pressure).
- **Keeps what it has shown.** We never withdraw a message: a reworded commentary line arrives again, and a disallowed goal is followed by a `VAR` event. See [`event`](#event).
- **Flips the handicap sign on older bets.** Bet slips and tips without `handicap_is_line: true` carry the opposite sign on handicap markets. See [Bet slips](#bet-slips).
- **Stores IDs as 64-bit integers.** `bet_id`, `wager_selection_id` and others already exceed 32 bits.
- **Ignores what it doesn't recognise.** We add fields, message types, topics and values without notice. See [Staying up to date](#staying-up-to-date).

## Environments

|              | Production                                       | Staging                                           |
| ------------ | ------------------------------------------------ | ------------------------------------------------- |
| HTTP and SSE | `https://publisher.prod.song.brainanalytics.co`  | `https://publisher.stage.song.brainanalytics.co`  |
| WebSocket    | `wss://publisher.prod.song.brainanalytics.co/ws` | `wss://publisher.stage.song.brainanalytics.co/ws` |

Each environment has its own token. To see the other one, switch environment in the portal: in Settings, or in Your details in the [Quick start](#quick-start). Staging runs the same API but covers fewer competitions, so it has fewer matches.

## Authentication

Every request except `GET /health` needs your client token. The [Quick start](#quick-start) says where to find it. Send it in one of two ways:

- **Header** `X-Token: YOUR_TOKEN`, for server-side clients.
- **Query string** `?token=YOUR_TOKEN`, for browsers. The browser `EventSource` and `WebSocket` APIs can't set headers.

If you send both, the header wins. A missing, unknown or disabled token gets HTTP `403`. A WebSocket with a bad token is refused during the handshake, also with `403`.

The API accepts cross-origin requests, so browser apps can call it directly.

## Topics and languages

A stream is identified by three things: the match (`match_id`), the topic and the language.

| Topic                         | Message type       | Per language | Content                                                | Sent                                      |
| ----------------------------- | ------------------ | :----------: | ------------------------------------------------------ | ----------------------------------------- |
| `ai-commentary-{strategy_id}` | `ai_commentary`    | yes          | The strategy's commentary and the bets it places       | when the strategy acts, every few minutes |
| `ai-results-{strategy_id}`    | `ai_results`       | no           | The strategy's bets so far and its profit and loss     | about once a minute                       |
| `match_commentary`            | `match_commentary` | yes          | Text commentary from our data provider (not AI)        | as lines are written                      |
| `event`                       | `event`            | no           | Goals, cards, substitutions, VAR reviews and penalties | as they happen                            |
| `match_status`                | `match_status`     | no           | Match state, scores, periods and clock                 | about once a minute                       |
| `pressure`                    | `pressure`         | no           | Each team's pressure, minute by minute                 | every minute: one message per team        |
| `odds`                        | `odds`             | no           | All live odds markets, in IM's format                  | when the odds change                      |

`{strategy_id}` is the strategy's ID, so the Sister Song strategy's topics are `ai-commentary-sister-song-v1` and `ai-results-sister-song-v1`. A strategy can be limited to certain competitions. Its topics stay empty for matches outside them.

**Languages:** `en` (default), `zh`, `vi` and `th`.

- **Per-language topics** are published once in each language. English goes out first and the translations usually follow within a few seconds. All copies of an item share the same `data.id`, so you can use it to match translations.
- **The other topics** are published once, with `language: "all"`. They're the same whichever language you choose.

**When matches stream:** messages start about 15 minutes before kick-off and stop about 30 minutes after full time. You can subscribe earlier. The stream stays empty until the first message.

## HTTP endpoints

| Endpoint                         | Response                                                                                                                        |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `GET /fixtures/live`             | `{"fixtures": [LiveFixture]}`: matches on the live list. Updated twice a minute.                                                |
| `GET /fixtures/upcoming`         | `{"fixtures": [Fixture]}`: matches kicking off in the next 3 days, soonest first.                                               |
| `GET /fixtures/im-event-mapping` | `{"mappings": [{"fixture_id": …, "event_id": …}]}`: each fixture's IM `event_id`, for fixtures from yesterday to 14 days ahead. |
| `GET /tips`                      | `{"tips": [Tip]}`: the strategies' bets, written up as tips. See [Tips](#tips).                                                 |
| `GET /health`                    | `{"status": "ok"}`. No token needed.                                                                                            |

The live list holds matches in play, plus matches about to kick off (from about 15 minutes before) or just finished. Use `state_name` to tell them apart.

Both fixture lists show only the matches Sister Song streams. Add `?all=true` to also see matches we don't stream.

Fixture, competition, team and event type IDs come from our data provider, Sportmonks. IM's IDs are separate: `event_id` here, and the IM IDs in `odds` messages and bet slips. The `fixture_id` and `event_id` in the mapping are both integers.

If fixture data is briefly unavailable, the fixture endpoints return `502`. Retry after a few seconds.

### LiveFixture

| Field                    | Type            | Meaning                                                                                                                                              |
| ------------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                     | integer         | Fixture ID: use it as `match_id`                                                                                                                     |
| `sport_id`               | integer         | Always `1` (football)                                                                                                                                |
| `league_id`              | integer         | Competition ID                                                                                                                                       |
| `name`                   | string          | For example `"FC Barcelona vs Real Madrid"`. It can be `""`.                                                                                         |
| `state_id`, `state_name` | integer, string | Match state, for example `22` / `"INPLAY_2ND_HALF"`. See [state codes](#state-codes). A state we don't know yet is named `"STATE_<id>"`.            |
| `starting_at`            | string          | Kick-off in UTC, for example `"2026-10-25T20:00:00"`                                                                                                 |
| `fixture_whitelisted`    | boolean         | `true` when the match was added on its own rather than through its competition. Every strategy covers such matches. Always `false` with `?all=true`. |

### Fixture (upcoming)

| Field                              | Type            | Meaning                                |
| ---------------------------------- | --------------- | -------------------------------------- |
| `id`                               | integer         | Fixture ID: use it as `match_id`       |
| `sport_id`                         | integer         | Always `1` (football)                  |
| `starting_at`                      | string          | Kick-off in UTC                        |
| `league_id`, `league_name`         | integer, string | Competition                            |
| `season_id`, `season_name`         | integer, string | Season                                 |
| `stage_id`, `stage_name`           | integer, string | Stage, for example `"Regular Season"`  |
| `round_id`, `round_name`           | integer, string | Round                                  |
| `state_id`                         | integer         | Always `1` (not started)               |
| `home_team_id`, `away_team_id`     | integer         | Team IDs                               |
| `home_team_name`, `away_team_name` | string          | Team names                             |
| `result_info`                      | string          | Empty (`""`) before the match          |

Missing names are empty strings and missing IDs are `0`.

## Streaming over SSE

One SSE stream carries one match in one language. Open another stream for another match or language.

```http
GET https://publisher.prod.song.brainanalytics.co/sse?match_id=19732648&topics=ai-commentary-sister-song-v1,event,pressure&language=en HTTP/1.1
X-Token: YOUR_TOKEN
```

| Parameter  | Type    | Required | Meaning                                                                                                                                  |
| ---------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `match_id` | integer | yes      | The fixture ID                                                                                                                           |
| `topics`   | string  | yes      | Comma-separated (`topics=a,b`) or repeated (`topics=a&topics=b`)                                                                         |
| `language` | string  | no       | `en` (default), `zh`, `vi` or `th`. It applies to per-language topics. The other topics always arrive, and with `all` only they arrive. |
| `token`    | string  | no       | Your token, if you can't send the `X-Token` header                                                                                       |

The stream sends, in this order:

1. `: ok` (an SSE comment) as soon as you connect.
2. One or more `snapshot` frames: the replay (see [Replay frames](#replay-frames)).
3. Live messages, each on its own `data:` line.
4. A `: ping` comment whenever 15 seconds pass with no messages, to keep the connection open.

Every frame is a default `message` event, with no `event:` or `id:` field. Read `publish_type` to tell frames apart: it's `"snapshot"` for replay frames and the message type for everything else.

A live message:

```json
{
  "timestamp": "2026-10-25T20:26:01.112723",
  "seq": 45,
  "topic": "pressure",
  "match_id": 19732648,
  "language": "all",
  "publish_type": "pressure",
  "data": { "id": 7308289375, "minute": 23, "pressure": 45.3, "participant_id": 83, "side": "home" },
  "id": null
}
```

| Field          | Type            | Meaning                                                                                       |
| -------------- | --------------- | --------------------------------------------------------------------------------------------- |
| `timestamp`    | string          | When the message was published, in UTC (see [Times](#times))                                  |
| `seq`          | integer or null | The message's position in its stream (see [Duplicates and gaps](#duplicates-and-gaps))        |
| `topic`        | string          | The topic                                                                                     |
| `match_id`     | integer         | The fixture ID                                                                                |
| `language`     | string          | `en`, `zh`, `vi` or `th`, or `all` on the topics that aren't per language                     |
| `publish_type` | string          | The message type, such as `pressure` (see [Message reference](#message-reference))            |
| `data`         | object          | The message                                                                                   |
| `id`           | null            | Always `null` on live messages. Messages inside a replay carry their stored `id` and `created_at`. |

**Errors.** `400` if `topics` is missing, `422` if `match_id` is missing or a parameter is invalid, and `403` for a bad token.

### Reconnecting

- The server ends your stream if you fall more than 256 messages behind. Streams also end when the service restarts, for example during a deploy.
- A browser's `EventSource` reconnects by itself after a dropped connection. After an HTTP error response, such as `502` during a deploy, it stops for good, so reconnect yourself with a backoff, as the [Quick start](#quick-start) sample does.
- Every new connection starts with a fresh replay.

## Streaming over WebSocket

One WebSocket can hold many subscriptions: several matches, topics and languages. All messages are JSON text, in both directions.

Connect to `wss://publisher.prod.song.brainanalytics.co/ws?token=YOUR_TOKEN`, or send the `X-Token` header instead if your WebSocket library can.

### Commands

| Command                       | Fields                                         | Reply                                                                   |
| ----------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
| `subscribe`                   | `topic`, `match_id`, `language` (default `en`) | One `ack` per topic with `status: "subscribed"`, then the replay frames |
| `unsubscribe`                 | `topic`, `match_id`, `language` (default `en`) | One `ack` per topic with `status: "unsubscribed"`                       |
| `unsubscribe_all_by_match_id` | `match_id`                                     | One `ack` with `status: "unsubscribed_all_by_match_id"`                 |
| `unsubscribe_all`             | none                                           | One `ack` with `status: "unsubscribed_all"`                             |
| `ping`                        | none                                           | `{"type": "pong"}`                                                      |

| Field      | Type                      | Meaning                                                                                                      |
| ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `command`  | string                    | One of the commands above. Others get no reply.                                                              |
| `topic`    | string or array of string | One topic, a comma-separated string or a JSON array. Needed by `subscribe` and `unsubscribe`.                |
| `match_id` | integer                   | The fixture ID. Needed by every command except `unsubscribe_all` and `ping`.                                 |
| `language` | string                    | `en` (default), `zh`, `vi` or `th`, as on SSE. `all` subscribes to the topics that aren't per language only. |

The replay after a `subscribe` covers all the topics in that command. `language` works as it does on SSE. It sets the language of the per-language topics, and the other topics arrive whatever language you send. So one command covers a whole match:

```json
{ "command": "subscribe", "topic": "ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_commentary,event,match_status,pressure,odds", "match_id": 19732648, "language": "en" }
```

To unsubscribe, send the same topics and language.

An `ack`:

```json
{
  "type": "ack",
  "timestamp": "2026-10-25T21:40:00.123456",
  "match_id": 19732648,
  "language": "en",
  "topic": "ai-commentary-sister-song-v1",
  "status": "subscribed",
  "error": null
}
```

| Field       | Type            | Meaning                                                                                     |
| ----------- | --------------- | ------------------------------------------------------------------------------------------- |
| `type`      | string          | Always `"ack"`                                                                              |
| `timestamp` | string          | When it was sent, in UTC                                                                    |
| `match_id`  | integer or null | The command's fixture ID                                                                    |
| `language`  | string or null  | The command's language                                                                      |
| `topic`     | string or null  | One topic from the command                                                                  |
| `status`    | string          | `subscribed`, `unsubscribed`, `unsubscribed_all_by_match_id`, `unsubscribed_all` or `error` |
| `error`     | string or null  | What was wrong with the command, when `status` is `error`                                   |

Subscribing again to something you already hold is harmless. You get a new `ack` and a fresh replay.

### Live messages

```json
{
  "type": "pressure",
  "timestamp": "2026-10-25T20:26:01.112723",
  "match_id": 19732648,
  "language": "all",
  "topic": "pressure",
  "seq": 45,
  "data": { "id": 7308289375, "minute": 23, "pressure": 45.3, "participant_id": 83, "side": "home" }
}
```

Live WebSocket messages have the same fields as live SSE messages, except that they give their type in `type` and have no `id`. Messages inside replay frames use `publish_type`, as on SSE.

### Keeping the connection alive

If the server receives nothing from you for 60 seconds, it drops every subscription on that connection and sends:

```json
{ "type": "unsubscribed", "reason": "timeout" }
```

The socket stays open, but you have to subscribe again.

> [!IMPORTANT]
> Send `{"command": "ping"}` every 30 seconds. WebSocket ping frames, which many libraries send by themselves, don't count: only a message from you resets the timer.

### Errors

A command with no `topic` or `match_id`, or with an unknown `language`, gets an error `ack`:

```json
{ "type": "ack", "timestamp": "2026-10-25T21:40:00.123456", "match_id": 19732648, "language": null, "topic": null, "status": "error", "error": "Missing topic or match_id" }
```

Unknown commands get no reply. A frame that isn't a JSON object closes the connection.

### Example client

```js
const socket = new WebSocket("wss://publisher.prod.song.brainanalytics.co/ws?token=YOUR_TOKEN");
const subscribe = {
  command: "subscribe",
  topic: "ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_status",
  match_id: 19732648,
  language: "en",
};
const seen = new Set();
let pinger;

function handle(msg, type) {
  if (msg.seq) {
    const key = `${msg.match_id}|${msg.topic}|${msg.language}|${msg.seq}`;
    if (seen.has(key)) return;
    seen.add(key);
  }
  show(type, msg.data);
}

socket.onopen = () => {
  socket.send(JSON.stringify(subscribe));
  pinger = setInterval(() => socket.send(JSON.stringify({ command: "ping" })), 30000);
};

socket.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case "ack":
    case "pong":
      return;
    case "unsubscribed": // nothing heard from us for 60 seconds
      return socket.send(JSON.stringify(subscribe));
    case "snapshot":
      if (msg.chunk === 1) {
        seen.clear();
        clearMatch(); // a new replay is starting
      }
      return msg.messages.forEach((item) => handle(item, item.publish_type));
    default:
      return handle(msg, msg.type);
  }
};

socket.onclose = () => clearInterval(pinger); // then reconnect, with a backoff
```

```python
import asyncio
import json

import websockets

URL = "wss://publisher.prod.song.brainanalytics.co/ws?token=YOUR_TOKEN"
SUBSCRIBE = {
    "command": "subscribe",
    "topic": "ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_status",
    "match_id": 19732648,
    "language": "en",
}
seen = set()


def handle(msg, kind):
    if msg.get("seq"):
        key = (msg["match_id"], msg["topic"], msg["language"], msg["seq"])
        if key in seen:
            return
        seen.add(key)
    print(kind, msg["data"])


async def keep_alive(socket):
    # The library's own WebSocket pings don't reset the server's 60-second timer. This does.
    while True:
        await asyncio.sleep(30)
        await socket.send(json.dumps({"command": "ping"}))


async def main():
    # Replay frames of odds can pass the library's default 1 MB message limit.
    async with websockets.connect(URL, max_size=None) as socket:
        await socket.send(json.dumps(SUBSCRIBE))
        pinger = asyncio.create_task(keep_alive(socket))
        try:
            async for raw in socket:
                msg = json.loads(raw)
                if msg["type"] in ("ack", "pong"):
                    continue
                if msg["type"] == "unsubscribed":  # nothing heard from us for 60 seconds
                    await socket.send(json.dumps(SUBSCRIBE))
                elif msg["type"] == "snapshot":
                    if msg["chunk"] == 1:
                        seen.clear()  # a new replay is starting
                    for item in msg["messages"]:
                        handle(item, item["publish_type"])
                else:
                    handle(msg, msg["type"])
        finally:
            pinger.cancel()


asyncio.run(main())
```

### Session overview

```mermaid height=520
sequenceDiagram
  accTitle: A WebSocket session
  autonumber
  participant C as Your app
  participant P as Publisher

  C->>P: GET /fixtures/live (X-Token)
  P-->>C: 200 {fixtures: [...]}

  C->>P: WebSocket /ws?token=...
  P-->>C: connection accepted

  C->>P: subscribe ai-commentary-sister-song-v1,ai-results-sister-song-v1,event,... (language "en")
  P-->>C: one ack per topic, then snapshot frames 1..n

  loop every 30 s
    C->>P: {command: "ping"}
    P-->>C: {type: "pong"}
  end

  P-->>C: live messages: ai_commentary, ai_results, match_commentary, event, match_status, pressure, odds
```

## Replays, ordering and duplicates

### Replay frames

When you connect over SSE, or subscribe over a WebSocket, you first get a replay. It holds every message already published for that match and those topics, oldest first, split into frames of up to 30 messages. You always get at least one frame. If nothing has been published yet, its `messages` list is empty.

```json
{
  "type": "snapshot",
  "publish_type": "snapshot",
  "timestamp": "2026-10-25T21:40:00.512345",
  "match_id": 19732648,
  "language": "en",
  "topics": ["ai-commentary-sister-song-v1", "pressure"],
  "chunk": 1,
  "total_chunks": 8,
  "messages": [
    {
      "id": 1940582,
      "created_at": "2026-10-25T19:46:11.147292Z",
      "timestamp": "2026-10-25T19:46:11.127134Z",
      "seq": 1,
      "topic": "ai-commentary-sister-song-v1",
      "match_id": 19732648,
      "language": "en",
      "publish_type": "ai_commentary",
      "data": {
        "id": "5792b134-ee1d-456d-89ec-271db69a88bd",
        "minute": 0,
        "period_id": 0,
        "period_name": "Not Started",
        "commentary": "Welcome everyone to our stream, let's analyze this massive El Clásico together and find some smart investments!",
        "action_type": "welcome",
        "bet_slips": []
      }
    }
  ]
}
```

| Field                   | Type            | Meaning                                                                                                                           |
| ----------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `type`, `publish_type`  | string          | Both `"snapshot"`                                                                                                                 |
| `timestamp`             | string          | When the frame was built, in UTC                                                                                                  |
| `match_id`              | integer         | The fixture ID                                                                                                                    |
| `language`              | string          | The language you asked for                                                                                                        |
| `topics`                | array of string | The topics replayed, in any order                                                                                                 |
| `chunk`, `total_chunks` | integer         | This frame's number, from 1, and how many frames the replay has                                                                   |
| `messages`              | array of object | Up to 30 messages, oldest first. They have the fields of live SSE messages, plus their stored `id` (an integer) and `created_at`. |

- `chunk: 1` always starts a new replay. Drop what you hold for those topics, then apply the frames in order. You're up to date when `chunk` equals `total_chunks`.
- Replays of older matches can lack fields added since. Treat a missing field like `null`.

> [!NOTE]
> `odds` and `match_status` replay every message sent so far, though only the latest one is current. Late in a match, an `odds` replay can be several megabytes, and a single frame can pass 1 MB.

### Duplicates and gaps

- `seq` starts at 1 and goes up by 1 within each stream (match, topic and language).
- The end of a replay can overlap the first live messages. Drop duplicates on `(match_id, topic, language, seq)`.
- Rarely, a live message has `seq: null`, or `0` on its translations: we couldn't store it, so it won't appear in any replay. Show it without deduplicating it.
- A replay can be up to 5 seconds old. So a message published just before you connected can be missing from both the replay and the live stream. If a stream's `seq` skips a number, resubscribe or reconnect a few seconds later to fill the gap.

### Ordering

- Within one stream, order messages by `seq`.
- `seq` is counted separately for each stream, so it can't order messages across topics. Across topics, use `timestamp` (when the message was published) or the match minute in `data`.

### Times

All times are UTC. Live messages, acks and replay frames have no zone suffix (`2026-10-25T20:26:01.112723`). Messages inside a replay, and tips' `created_at`, end in `Z`. Treat both as UTC. The fractional seconds are left out when they're zero.

## Message reference

Each section shows the `data` of one message type.

> [!NOTE]
> Store IDs as 64-bit integers. `bet_id`, `wager_selection_id` (`wsid` in `odds`), `market_line_id` (`mlid`) and pressure `id` already exceed 32 bits. They're all well within the range JavaScript numbers hold exactly.

### `ai_commentary`

The strategy's commentary, and any bets it places.

```json
{
  "id": "8f4cf6e8-5cf4-4c36-88e9-b58c974e9d78",
  "minute": 75,
  "period_id": 2,
  "period_name": "2nd-half",
  "commentary": "Barcelona are dominating the possession charts and forcing errors. Let us grab the 1X2 market for a home win at 2.6 while the price is high.",
  "action_type": "snipe_live_bet",
  "bet_slips": [
    {
      "bet_id": 1792964349638601,
      "market_line_id": 2552318214,
      "market_name": "1X2",
      "bet_type_id": 3,
      "period_id": 1,
      "selection_id": 5,
      "selection_name": "Home",
      "wager_selection_id": 33142892065,
      "odds": 2.6,
      "handicap": null,
      "handicap_is_line": true,
      "specifiers": "",
      "odds_type": null,
      "stake": 25.0,
      "bet_placed_home_score": 1,
      "bet_placed_away_score": 1,
      "bet_placed_home_corners": 4,
      "bet_placed_away_corners": 6,
      "im_home_team_id": 80987,
      "im_away_team_id": 870,
      "confidence": 0.45,
      "implied_probability": 0.38,
      "confidence_source": "model"
    }
  ]
}
```

| Field                      | Type               | Meaning                                                                                          |
| -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------ |
| `id`                       | string or null     | The item's UUID. It's the same in every language. It can be `null` on old messages.              |
| `minute`                   | integer            | Match minute when the strategy acted                                                             |
| `period_id`, `period_name` | integer, string    | `0` `"Not Started"`, `1` `"1st-half"`, `2` `"2nd-half"`, `3` `"extra-time"` or `5` `"penalties"` |
| `commentary`               | string             | The text, in the stream's language                                                               |
| `action_type`              | string             | What the strategy is doing (see [Action types](#action-types))                                   |
| `bet_slips`                | array of bet slips | The bets placed by this action. Empty when there are none.                                       |

> [!NOTE]
> AI minutes don't always go up. The `minute` on `ai_commentary` and `ai_results` holds still through half-time and can step back at full time. Order a strategy's messages by `seq`.

#### Action types

Use them to drive your UI, for example icons or colours.

| Group     | `action_type`         | The strategy…                                    |
| --------- | --------------------- | ------------------------------------------------ |
| Betting   | `snipe_live_bet`      | bets on a value opportunity                      |
|           | `double_down`         | adds another bet on an outcome it already backs  |
|           | `hedge_bet`           | bets against one of its bets to lock in a result |
|           | `cash_out_decision`   | takes a profit or cuts a loss                    |
|           | `cash_out_temptation` | debates whether to cash out                      |
|           | `tilt_bet`            | bets aggressively after a loss                   |
| Advice    | `highlight_value`     | points out value without betting                 |
|           | `warn_trap`           | warns against a bet                              |
|           | `suggest_fun_bet`     | suggests a long shot for fun                     |
| Reactions | `react_goal_favored`  | celebrates a goal that helps its bets            |
|           | `react_goal_opposed`  | reacts to a goal that hurts its bets             |
|           | `react_goal_neutral`  | appreciates a goal it has no stake in            |
|           | `react_var_check`     | waits on a VAR decision                          |
|           | `react_near_miss`     | reacts to a shot off the post or a big save      |
|           | `analyze_momentum`    | comments on the flow of the game                 |
|           | `critique_player`     | blames a player                                  |
| Mood      | `sweating`            | feels the tension late in a close bet            |
|           | `bragging`            | gloats after a win                               |
|           | `coping`              | explains away a loss                             |
|           | `rally_cry`           | urges a result ("One more corner!")              |
| Audience  | `ask_chat_opinion`    | asks viewers what they think                     |
|           | `shoutout_winners`    | celebrates with viewers who won                  |
| Session   | `welcome`             | opens the stream, before or at kick-off          |
|           | `goodbye`             | signs off after the match                        |

#### Bet slips

`ai_results` and tips reuse the same fields.

| Field                                                | Type                            | Meaning                                                                                                                                 |
| ---------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `bet_id`                                             | integer                         | Unique bet ID. It also appears in `ai_results` and tips.                                                                                |
| `market_line_id`                                     | integer                         | IM market line ID (`mlid` in `odds`)                                                                                                    |
| `market_name`                                        | string                          | For example `"Handicap"`, `"Over/Under"`, `"1X2"`, `"1H Over/Under"` or `"Corner Handicap"`                                             |
| `bet_type_id`                                        | integer or null                 | IM bet type ID (`btid` in `odds`)                                                                                                       |
| `period_id`                                          | integer or null                 | IM game period: `1` full match, `2` first half, `3` second half                                                                         |
| `selection_id`, `selection_name`                     | integer, string                 | The selection, for example `5` `"Home"` on 1X2, or `3` `"Over"`                                                                         |
| `wager_selection_id`                                 | integer or null                 | IM wager selection ID (`wsid` in `odds`)                                                                                                |
| `odds`                                               | number                          | Decimal odds when the bet was placed                                                                                                    |
| `handicap`                                           | number or null                  | The line bet on this selection, for example `-0.5` for Home −0.5, or the total on over/under markets. `null` on markets without one.    |
| `handicap_is_line`                                   | boolean                         | `true` on current slips. Older slips don't have it: see the warning below.                                                              |
| `specifiers`, `odds_type`                            | string or null, integer or null | IM details. Usually `""` and `null`.                                                                                                    |
| `stake`                                              | number                          | Stake, in notional units. PnL uses the same units.                                                                                      |
| `bet_placed_home_score`, `bet_placed_away_score`     | integer                         | Score when the bet was placed                                                                                                           |
| `bet_placed_home_corners`, `bet_placed_away_corners` | integer or null                 | Corners when the bet was placed. `null` on old bets.                                                                                    |
| `im_home_team_id`, `im_away_team_id`                 | integer or null                 | IM team IDs                                                                                                                             |
| `confidence`                                         | number or null                  | The strategy's estimate of the chance the bet wins, from 0 to 1. Show it as a percentage.                                               |
| `implied_probability`                                | number or null                  | `1 / odds` when the bet was placed, from 0 to 1                                                                                         |
| `confidence_source`                                  | string or null                  | `"model"` when `confidence` is the strategy's own estimate. `"market"` when it gave none, so `confidence` equals `implied_probability`. |

The three confidence fields are rounded to 2 decimal places. They're all `null` on old bets, and when the odds were 1 or lower.

> [!WARNING]
> **Older bets have the opposite handicap sign.** Current bet slips and tips have `handicap_is_line: true`. Older ones don't have it, or have `false`, and on handicap markets (where `market_name` or `market_type` contains "Handicap") their `handicap` is the negative of the line bet. For example, `"selection_name": "Away", "handicap": -0.25` without the marker was a bet on Away +0.25, so flip the sign when you display it. Over/under lines and the `odds` topic were always correct.

### `ai_results`

The strategy's results for the match, about once a minute. Each message gives the full picture so far, not a change.

```json
{
  "settled_pnl": 15.25,
  "unsettled_pnl": 0.0,
  "minute": 76,
  "bets": [
    {
      "bet_slip": { "bet_id": 1792959428604594, "market_name": "1H Over/Under", "selection_name": "Over", "odds": 1.84, "handicap": 1.25, "stake": 25.0 },
      "state": "half_lost",
      "live_state": "half_lost",
      "settled": true,
      "pnl": -12.5
    },
    {
      "bet_slip": { "bet_id": 1792964349638601, "market_name": "1X2", "selection_name": "Home", "odds": 2.6, "handicap": null, "stake": 25.0 },
      "state": "pending",
      "live_state": "lost",
      "settled": false,
      "pnl": 0.0
    }
  ]
}
```

The `bet_slip` objects are shortened here. Real ones have every bet slip field.

| Field           | Type            | Meaning                                                       |
| --------------- | --------------- | ------------------------------------------------------------- |
| `settled_pnl`   | number          | Profit or loss from settled bets. This is the strategy's PnL. |
| `unsettled_pnl` | number          | Always `0`: a bet adds to PnL only once it settles            |
| `minute`        | integer         | Match minute                                                  |
| `bets`          | array of object | Every bet the strategy has placed in this match               |

Each entry in `bets`:

| Field        | Type    | Meaning                                                                                                                                     |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `bet_slip`   | object  | The bet, as in `ai_commentary`                                                                                                              |
| `state`      | string  | `pending`, `won`, `lost`, `half_won`, `half_lost` or `push`                                                                                 |
| `live_state` | string  | What the bet would settle as if the match ended now (same values). It equals `state` once the bet settles. Some old messages don't have it. |
| `settled`    | boolean | `true` once the result is final                                                                                                             |
| `pnl`        | number  | Profit or loss on this bet. `0` until it settles.                                                                                           |

### `match_commentary`

Text commentary from our data provider. It's translated into each language.

```json
{
  "id": 11580888,
  "minute": 41,
  "extra_minute": null,
  "comment": "Goal! Real Madrid lead 1-0 against Barcelona as Kylian Mbappé scores with a right-footed shot from the center of the box into the bottom left corner.",
  "is_goal": true,
  "is_important": true
}
```

| Field                    | Type                     | Meaning                                                                                                                |
| ------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `id`                     | integer                  | Line ID. It's the same in every language.                                                                              |
| `minute`, `extra_minute` | integer, integer or null | Match minute, and minutes into stoppage time: `90` and `8` mean 90+8'. `extra_minute` is `null` outside stoppage time. |
| `comment`                | string                   | The text, in the stream's language                                                                                     |
| `is_goal`                | boolean                  | `true` on goal lines                                                                                                   |
| `is_important`           | boolean                  | `true` on key moments                                                                                                  |

`minute` is always set. A line without its own minute gets the minute of the line before it, or `0` if there's none.

> [!NOTE]
> Messages are never withdrawn. If our data provider rewords a commentary line, you get both versions.

### `event`

Structured match events.

```json
{
  "id": 158411184,
  "type_id": 14,
  "type_name": "Goal",
  "minute": 61,
  "extra_minute": null,
  "period_id": 7194994,
  "side": "home",
  "participant_id": 83,
  "player_id": 160258,
  "player_name": "Raphinha",
  "related_player_id": 37288001,
  "related_player_name": "Pedri",
  "result": "1-1",
  "info": "Right foot shot",
  "addition": "2nd Goal",
  "sort_order": 2,
  "rescinded": null,
  "coach_id": null,
  "on_bench": false,
  "injured": null
}
```

| Field                                      | Type                            | Meaning                                                                                                             |
| ------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `id`                                       | integer                         | Event ID                                                                                                            |
| `type_id`, `type_name`                     | integer, string                 | Event type (see [Event types](#event-types))                                                                        |
| `minute`, `extra_minute`                   | integer, integer or null        | Match minute and minutes into stoppage time. For penalty shootout kicks, `minute` is the kick number.               |
| `period_id`                                | integer or null                 | ID of the period it happened in. It matches `periods[].id` in `match_status`.                                       |
| `side`                                     | string                          | `"home"` or `"away"`. Events without a team are reported as `"home"`.                                               |
| `participant_id`                           | integer or null                 | Team ID                                                                                                             |
| `player_id`, `player_name`                 | integer or null, string or null | The main player: the scorer, the booked player or the player coming on                                              |
| `related_player_id`, `related_player_name` | integer or null, string or null | The other player: the assist, or the player going off                                                               |
| `result`                                   | string or null                  | Score after a goal, for example `"1-1"`                                                                             |
| `info`                                     | string or null                  | Detail, for example `"Right foot shot"` or `"Unsportsmanlike conduct"`                                              |
| `addition`                                 | string or null                  | Label, for example `"2nd Goal"`, `"6th Yellowcard"` or `"Goal disallowed"`                                          |
| `sort_order`                               | integer or null                 | How many events of this type there have been so far (the 2 in "2nd Goal"). It doesn't order events within a minute. |
| `rescinded`, `on_bench`                    | boolean or null                 | Other details, often `null`                                                                                         |
| `coach_id`                                 | integer or null                 | Other details, often `null`                                                                                         |
| `injured`                                  | boolean, string or null         | Other details, often `null`                                                                                         |

Only `id`, `type_id`, `type_name`, `minute` and `side` are always set.

> [!NOTE]
> Events are sent once and never updated. A goal later disallowed stays in the feed, followed by a `VAR` event with `addition: "Goal disallowed"`.

#### Event types

| `type_id` | `type_name`           |
| --------: | --------------------- |
| `14`      | Goal                  |
| `15`      | Own Goal              |
| `16`      | Penalty (scored)      |
| `17`      | Missed Penalty        |
| `18`      | Substitution          |
| `19`      | Yellowcard            |
| `20`      | Redcard               |
| `21`      | Yellow/Red card       |
| `10`      | VAR                   |
| `1697`    | VAR_CARD              |
| `22`      | Penalty Shootout Miss |
| `23`      | Penalty Shootout Goal |

Other Sportmonks event types may appear. Corners aren't sent as events. VAR events say what happened in `addition`, for example `"Pending VAR"`, `"Goal disallowed"` or `"Penalty awarded"`.

### `pressure`

How much pressure each team is putting on, minute by minute. Each minute has two messages, one per team.

```json
{ "id": 7308289375, "minute": 23, "pressure": 45.3, "participant_id": 83, "side": "home" }
```

| Field            | Type            | Meaning                                                              |
| ---------------- | --------------- | -------------------------------------------------------------------- |
| `id`             | integer         | Reading ID                                                           |
| `minute`         | integer         | Match minute                                                         |
| `pressure`       | number          | That team's pressure in that minute, from 0 to 100                   |
| `side`           | string or null  | `"home"` or `"away"`. It can be `null` if the team isn't recognised. |
| `participant_id` | integer or null | Team ID                                                              |

To show momentum, compare the two teams' values for each minute.

> [!NOTE]
> Not every competition has pressure. Some, currently including the UEFA Champions League, send no pressure data, so their matches have no `pressure` messages.

### `match_status`

The full current state of the match. It's sent about once a minute, and only once during half-time.

```json
{
  "id": 19732648,
  "name": "FC Barcelona vs Real Madrid",
  "state": { "name": "2nd Half", "short_name": "2nd" },
  "result_info": null,
  "starting_at": "2026-10-25 20:00:00",
  "scores": [
    { "score": { "goals": 0, "participant": "home" }, "description": "CURRENT", "participant_id": 83 },
    { "score": { "goals": 1, "participant": "away" }, "description": "CURRENT", "participant_id": 3468 },
    { "score": { "goals": 0, "participant": "home" }, "description": "1ST_HALF", "participant_id": 83 },
    { "score": { "goals": 1, "participant": "away" }, "description": "1ST_HALF", "participant_id": 3468 }
  ],
  "periods": [
    { "id": 7194899, "fixture_id": 19732648, "type_id": 1, "description": "1st-half", "sort_order": 1, "started": 1792958554, "ended": 1792961389, "ticking": false, "minutes": 47, "seconds": 15, "time_added": 2, "has_timer": false },
    { "id": 7194994, "fixture_id": 19732648, "type_id": 2, "description": "2nd-half", "sort_order": 2, "started": 1792962497, "ended": null, "ticking": true, "minutes": 53, "seconds": 43, "time_added": null, "has_timer": true }
  ]
}
```

| Field         | Type                    | Meaning                                                                                       |
| ------------- | ----------------------- | --------------------------------------------------------------------------------------------- |
| `id`, `name`  | integer, string         | Fixture ID and name                                                                           |
| `state`       | object or null          | Match state: `name` and `short_name`, both strings (see [Match states](#match-states))        |
| `result_info` | string or null          | Result text after the match, for example `"Real Madrid won after full-time."`. `null` before. |
| `starting_at` | string                  | Kick-off in UTC, written `"2026-10-25 20:00:00"` (with a space, not `T`)                      |
| `scores`      | array of object or null | Scores, one entry per team for each `description` (see [Scores](#scores))                    |
| `periods`     | array of object or null | The periods played so far (see [Periods](#periods))                                           |

#### Scores

| Field               | Type    | Meaning                         |
| ------------------- | ------- | ------------------------------- |
| `score.goals`       | integer | Goals                           |
| `score.participant` | string  | `"home"` or `"away"`            |
| `description`       | string  | Which score this is (see below) |
| `participant_id`    | integer | Team ID                         |

`CURRENT` is the live score. `1ST_HALF` is the half-time score, `2ND_HALF` the score after the second half (so far), and `2ND_HALF_ONLY` the goals scored in the second half alone. `ET`, `ET_1ST_HALF`, `ET_2ND_HALF` and `PENALTY_SHOOTOUT` appear when extra time or a shootout is played.

#### Periods

| Field                    | Type            | Meaning                                                                                                                                 |
| ------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                     | integer         | Period ID. Events' `period_id` points here.                                                                                             |
| `type_id`, `description` | integer, string | `1` `"1st-half"`, `2` `"2nd-half"`, `3` `"extra-time"` or `5` `"penalties"`                                                             |
| `sort_order`             | integer         | Order of the period                                                                                                                     |
| `started`, `ended`       | integer or null | Unix time in seconds. `ended` is `null` while the period runs.                                                                          |
| `ticking`                | boolean         | `true` while the clock runs                                                                                                             |
| `minutes`, `seconds`     | integer or null | The match clock, for example 53:43. The second half carries on from 45. `minutes` is `null` if the provider sends an implausible value. |
| `time_added`             | integer or null | Stoppage time announced, in minutes                                                                                                     |
| `has_timer`              | boolean         | `true` while the provider times the period. It's `false` once the period ends, and for penalties.                                       |
| `fixture_id`             | integer         | Fixture ID                                                                                                                              |

> [!NOTE]
> Period clocks can jump. They come from our data provider, and now and then they jump ahead or back, for example at second-half kick-off. Don't assume they only increase.

#### Match states

`state.name` / `state.short_name`: Not Started / NS, 1st Half / 1st, Half Time / HT, 2nd Half / 2nd, Extra Time / et, Extra Time - Break / ETB, Penalties / PEN, Break / BRK, Full Time / FT, After Extra Time / AET, After Penalties / FTP, Postponed / POST, Delayed / DELA, Suspended / SUSP, Interrupted / INT, Abandoned / ABAN, Awaiting Updates / AU.

#### State codes

`state_id` and `state_name` in fixtures, and `match_state` in tips, use these codes:

- Not started: `1` NS
- In play: `2` INPLAY_1ST_HALF, `3` HT, `4` BREAK, `22` INPLAY_2ND_HALF, `6` INPLAY_ET, `21` EXTRA_TIME_BREAK, `23` INPLAY_ET_2ND_HALF, `25` PEN_BREAK, `9` INPLAY_PENALTIES
- Finished: `5` FT, `7` AET, `8` FT_PEN
- Other: `10` POSTPONED, `11` SUSPENDED, `12` CANCELLED, `13` TBA, `14` WO, `15` ABANDONED, `16` DELAYED, `17` AWARDED, `18` INTERRUPTED, `19` AWAITING_UPDATES, `20` DELETED, `26` PENDING

### `odds`

Every live market for the match, in IM's compact format. Each message holds the full list, so replace what you have.

```json
{
  "ht": "Barcelona",
  "at": "Real Madrid",
  "htid": 80987,
  "atid": 870,
  "hs": 0,
  "as": 1,
  "rbt": "2H 53:53",
  "mls": [
    {
      "btn": "Handicap",
      "btid": 1,
      "mlid": 2552318204,
      "gp": 1,
      "mll": 1,
      "isl": false,
      "pen": null,
      "peid": null,
      "wss": [
        { "sen": "Home", "seid": 1, "wsid": 33142524486, "h": 0.5, "dih": "-0.5", "o": 0.86, "ol": [{ "ot": 3, "ov": { "A": "1.86" } }], "sp": "" },
        { "sen": "Away", "seid": 2, "wsid": 33142524487, "h": 0.5, "dih": "+0.5", "o": -0.94, "ol": [{ "ot": 3, "ov": { "A": "2.06" } }], "sp": "" }
      ]
    }
  ]
}
```

#### Top level

| Field          | Type            | Meaning                                    |
| -------------- | --------------- | ------------------------------------------ |
| `ht`, `at`     | string          | Home and away team names, as IM names them |
| `htid`, `atid` | integer or null | IM team IDs                                |
| `hs`, `as`     | integer or null | Current score, according to IM             |
| `rbt`          | string or null  | IM's match clock, for example `"2H 53:53"` |
| `mls`          | array of object | Market lines                               |

#### Market lines (`mls`)

| Field         | Type                            | Meaning                                                                         |
| ------------- | ------------------------------- | ------------------------------------------------------------------------------- |
| `btn`         | string                          | Market name, for example `"Handicap"`, `"1H Over/Under"` or `"Corner Handicap"` |
| `btid`        | integer                         | IM bet type ID (`bet_type_id` on bet slips)                                     |
| `mlid`        | integer                         | Market line ID (`market_line_id` on bet slips)                                  |
| `gp`          | integer or null                 | Game period: `1` full match, `2` first half, `3` second half                    |
| `mll`         | integer                         | Line level: `1` is the main line, and `2` and above are alternative lines       |
| `isl`         | boolean                         | `true` when the market is locked and can't be bet on                            |
| `wss`         | array of object                 | Selections                                                                      |
| `pen`, `peid` | string or null, integer or null | Old period fields, usually `null`                                               |

#### Selections (`wss`)

| Field  | Type            | Meaning                                                                                                                                                                       |
| ------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sen`  | string or null  | Selection name, for example `"Home"`, `"Over"`, `"Draw"` or `"1-2"`                                                                                                           |
| `seid` | integer or null | Selection ID (`selection_id` on bet slips)                                                                                                                                    |
| `wsid` | integer or null | Wager selection ID (`wager_selection_id` on bet slips)                                                                                                                        |
| `ol`   | array of object | The decimal price, as a string: `[{"ot": 3, "ov": {"A": "1.86"}}]`. Use this for prices. It can be empty.                                                                     |
| `o`    | number or null  | IM's raw price. Its format depends on the market, so use `ol` instead.                                                                                                        |
| `h`    | number or null  | The line. On handicap markets, both selections carry the same number: the handicap Home gives. `h: 0.5` means Home −0.5 and Away +0.5. On over/under markets, it's the total. |
| `dih`  | string or null  | The line as IM displays it for this selection, for example `"-0.5"` or `"+0.5/1"` (a quarter line, split across two lines)                                                    |
| `sp`   | string or null  | Specifiers, usually `""`                                                                                                                                                      |

> [!WARNING]
> Read prices from `ol`, not `o`. IM's raw price in `o` is in Malay format on handicap and over/under markets and decimal on the others, so the same number means different odds.

## Tips

`GET /tips` returns the strategies' bets as tips: the bet, a short written reason, and whether you can still follow it.

| Parameter     | Type    | Meaning                                                                                                                             |
| ------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `language`    | string  | `en` (default), `zh`, `vi` or `th`. `all` returns `400`.                                                                            |
| `strategy_id` | string  | Only tips from this strategy                                                                                                        |
| `match_id`    | integer | Only tips for this match                                                                                                            |
| `live_only`   | boolean | `true` (default): only tips you can still follow now. `false`: the newest tips whatever their status, each with its current status. |

You get up to 200 tips, newest first. Each bet becomes one tip per language.

A tip is live (`is_live: true`) when all of these are true:

- the match is in play
- the tip is less than 30 minutes old
- the bet hasn't settled, and the strategy hasn't cashed it out or hedged it
- the score hasn't changed since the bet was placed
- the same selection and line are still on offer, unlocked, at odds of at least `minimum_odds`

```json
{
  "bet_id": 1792964349638601,
  "match_id": 19732648,
  "strategy_id": "sister-song-v1",
  "language": "en",
  "market_type": "1X2",
  "selection": "Home",
  "handicap": null,
  "handicap_is_line": true,
  "odds": 2.6,
  "odds_type": "decimal",
  "minimum_odds": 2.6,
  "current_odds": 2.62,
  "probability": 0.45,
  "implied_probability": 0.38,
  "estimated_odds": 2.2222,
  "expected_value": 0.17,
  "bet_type_id": 3,
  "selection_id": 5,
  "period_id": 1,
  "market_line_id": 2552318214,
  "im_competition_id": 130,
  "home_team_id": 83,
  "away_team_id": 3468,
  "home_team_name": "FC Barcelona",
  "away_team_name": "Real Madrid",
  "placed_minute": 75,
  "placed_home_score": 1,
  "placed_away_score": 1,
  "tips_summary": "FC Barcelona are dominating possession and applying sustained attacking pressure as the match enters the final stages.",
  "tips_reasoning": "- FC Barcelona hold 60 percent of the ball possession and lead the total shots count 14 to 8.\n- The hosts have generated 44 dangerous attacks compared to Real Madrid's 23.\n- Barcelona lead the shots inside the box with 9 attempts against Real Madrid's 4.",
  "created_at": "2026-10-25T21:39:10.767092Z",
  "is_live": true,
  "bet_state": "pending",
  "settled": false,
  "current_home_score": 1,
  "current_away_score": 1,
  "current_minute": 76,
  "match_state": "INPLAY_2ND_HALF"
}
```

| Field                                                        | Type            | Meaning                                                                                 |
| ------------------------------------------------------------ | --------------- | --------------------------------------------------------------------------------------- |
| `bet_id`, `match_id`                                         | integer         | Which bet and match                                                                     |
| `strategy_id`, `language`                                    | string          | Which strategy, and the tip's language                                                  |
| `market_type`, `selection`                                   | string          | Market and selection, as on the bet slip                                                |
| `handicap`                                                   | number or null  | The line, as on the bet slip                                                            |
| `handicap_is_line`                                           | boolean         | `true` on current tips. On older ones, flip the sign: see [Bet slips](#bet-slips).      |
| `odds`                                                       | number          | Odds when the bet was placed                                                            |
| `odds_type`                                                  | string          | Always `"decimal"`                                                                      |
| `minimum_odds`                                               | number          | The lowest odds at which the tip is still worth taking. Currently the same as `odds`.   |
| `current_odds`                                               | number or null  | Latest decimal odds for the same selection and line. `null` if it's no longer on offer. |
| `probability`                                                | number or null  | The strategy's estimate of the chance the bet wins, from 0 to 1. `null` if it gave none. |
| `implied_probability`                                        | number or null  | `1 / odds` when the bet was placed                                                      |
| `estimated_odds`                                             | number or null  | `1 / probability`                                                                       |
| `expected_value`                                             | number or null  | `probability × odds − 1`: `0.17` means +17%                                             |
| `bet_type_id`, `period_id`                                   | integer or null | IM IDs, as on the bet slip                                                              |
| `selection_id`, `market_line_id`                             | integer         | IM IDs, as on the bet slip                                                              |
| `im_competition_id`                                          | integer or null | IM competition ID                                                                       |
| `home_team_id`, `away_team_id`                               | integer         | Team IDs                                                                                |
| `home_team_name`, `away_team_name`                           | string          | Team names, in the tip's language                                                       |
| `placed_minute`, `placed_home_score`, `placed_away_score`    | integer         | Minute and score when the bet was placed                                                |
| `tips_summary`                                               | string          | One line on why                                                                         |
| `tips_reasoning`                                             | string          | Up to 3 bullet points, as markdown lines starting with `- `                             |
| `created_at`                                                 | string          | When the tip was made, in UTC                                                           |
| `is_live`                                                    | boolean         | Whether you can still follow the tip (see above)                                        |
| `bet_state`                                                  | string or null  | The bet's state (`pending`, `won`, …). `null` when unknown.                             |
| `settled`                                                    | boolean         | Whether the result is final. `false` when unknown.                                      |
| `current_home_score`, `current_away_score`, `current_minute` | integer or null | The match now. `null` when unknown.                                                     |
| `match_state`                                                | string or null  | A [state code](#state-codes) name, or `"unknown"`. `null` when unknown.                 |

## Staying up to date

This guide always describes the current production API, at [song.brainanalytics.co/docs](https://song.brainanalytics.co/docs).

- **Changelog.** Every change is listed, newest first, at [song.brainanalytics.co/docs/changelog](https://song.brainanalytics.co/docs/changelog). To hear about changes as they happen, subscribe to its feed, `https://song.brainanalytics.co/docs/changelog.xml`, in a feed reader or in Slack with `/feed subscribe https://song.brainanalytics.co/docs/changelog.xml`.
- **Additions come without notice.** We add fields, message types, topics and values (such as new `action_type` values) as we go. Ignore anything you don't recognise.
- **Breaking changes come with notice.** Before we remove or rename anything, or change what a value means, we tell you in advance and release it to staging first.

## Glossary

- **Strategy**: an AI persona that watches a match, comments on it and places bets. Each has a text ID, such as `sister-song-v1`, and its own two topics.
- **Topic**: one kind of message for a match, such as `match_status` or `ai-commentary-sister-song-v1`. See [Topics and languages](#topics-and-languages).
- **Language**: `en`, `zh`, `vi` or `th`. Per-language topics are published once in each language, and the others once, with `language: "all"`.
- **Stream**: one topic of one match in one language. `seq` counts the messages in a stream.
- **Replay**: the `snapshot` frames that start every connection and subscription, holding everything already published. See [Replay frames](#replay-frames).
- **`seq`**: a message's position in its stream, from 1. Use it to drop duplicates and to order the stream.
- **Match ID**: our data provider's fixture ID: `id` in the fixture lists, `match_id` everywhere else.
- **Handicap line**: the handicap on the selection bet on, for example `-0.5` for Home −0.5. See [Bet slips](#bet-slips).
- **Tip**: a strategy's bet, written up with its reason, that you can follow while it's live. See [Tips](#tips).
- **IM**: the sportsbook whose markets and odds the strategies bet on. Its IDs appear in `odds`, bet slips and tips.
- **Sportmonks**: our data provider for fixtures, match events, commentary, pressure and match status. Fixture, team and event type IDs are theirs.
