# Chance History

Use this stream for live probability updates and chart backfill.

### Endpoint

```
wss://chance-history-service.outpoll.com/ws
```

### Authentication

No authentication required.

### Message envelope

```json
{
  "t": "<TYPE>",
  "e": "<EVENT_ID>",
  "o": ["<OUTCOME_ID>"],
  "d": { ... },
  "r": "<ERROR_MESSAGE>"
}
```

| Field | Type      | Description                    |
| ----- | --------- | ------------------------------ |
| `t`   | string    | Message type                   |
| `e`   | string    | Event ID                       |
| `o`   | string\[] | Outcome IDs                    |
| `d`   | object    | Message payload                |
| `r`   | string    | Error message for failed calls |

### Subscribe

```json
{
  "t": "SUBSCRIBE",
  "e": "54ccea1a-16fd-469c-8018-84b375243e8a",
  "o": [
    "b21f6fd8-b9d1-4b9f-bb79-ef141e3dcb76",
    "97b06d16-aeff-4dd4-b08b-1ba30a2b8895"
  ]
}
```

After subscribe, the server sends:

1. `probability` with the latest known value
2. `success` with subscribe confirmation

### Live updates

#### Probability update

```json
{
  "t": "probability",
  "e": "54ccea1a-16fd-469c-8018-84b375243e8a",
  "o": ["b21f6fd8-b9d1-4b9f-bb79-ef141e3dcb76"],
  "d": {
    "t": 1712160300,
    "p": 0.67
  }
}
```

#### History update

```json
{
  "t": "UPDATE_HISTORY",
  "e": "54ccea1a-16fd-469c-8018-84b375243e8a",
  "o": ["b21f6fd8-b9d1-4b9f-bb79-ef141e3dcb76"],
  "d": {
    "t": 1712160300,
    "p": 0.67
  }
}
```

| Field | Type   | Description                     |
| ----- | ------ | ------------------------------- |
| `d.t` | number | Unix timestamp in seconds       |
| `d.p` | number | Probability from `0.0` to `1.0` |

### Unsubscribe

```json
{
  "t": "UNSUBSCRIBE",
  "o": [
    "b21f6fd8-b9d1-4b9f-bb79-ef141e3dcb76"
  ]
}
```

Success response:

```json
{
  "t": "success",
  "o": ["b21f6fd8-b9d1-4b9f-bb79-ef141e3dcb76"],
  "d": { "message": "unsubscribe successful" }
}
```

### Request history

```json
{
  "t": "HISTORY",
  "e": "54ccea1a-16fd-469c-8018-84b375243e8a",
  "o": [
    "b21f6fd8-b9d1-4b9f-bb79-ef141e3dcb76"
  ],
  "d": {
    "p": "1H",
    "f": "2026-01-01T00:00:00Z",
    "t": "2026-01-01T12:00:00Z"
  }
}
```

#### Supported periods

| Code  |
| ----- |
| `1s`  |
| `5s`  |
| `5M`  |
| `10M` |
| `30M` |
| `1H`  |
| `3H`  |
| `4H`  |
| `6H`  |
| `1d`  |
| `7d`  |
| `1m`  |

You can also pass a custom number of seconds as a string.

### History response

```json
{
  "t": "HISTORY_RESPONSE",
  "e": "54ccea1a-16fd-469c-8018-84b375243e8a",
  "o": ["b21f6fd8-b9d1-4b9f-bb79-ef141e3dcb76"],
  "d": {
    "b21f6fd8-b9d1-4b9f-bb79-ef141e3dcb76": [
      { "t": 1735689600, "p": 0.50 },
      { "t": 1735693200, "p": 0.52 },
      { "t": 1735696800, "p": 0.55 }
    ]
  }
}
```

Each point includes:

| Field | Type   | Description             |
| ----- | ------ | ----------------------- |
| `t`   | number | Period end in Unix time |
| `p`   | number | Close probability value |

{% hint style="info" %}
The first point is an anchor value at or before `from`. If no data exists in range, the service returns a flat line.
{% endhint %}

### REST parity

The same history is available over REST:

```
GET /api/events/{eventId}/outcomes/{outcomeId}/history
```

### Python example

{% code title="chance\_history.py" %}

```python
import asyncio, json, websockets

async def chart_stream():
    uri = "wss://chance-history-service.outpoll.com/ws"
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "t": "SUBSCRIBE",
            "e": "54ccea1a-16fd-469c-8018-84b375243e8a",
            "o": ["b21f6fd8-b9d1-4b9f-bb79-ef141e3dcb76"],
        }))

        async for msg in ws:
            data = json.loads(msg)
            print(data["t"], data["d"])
```

{% endcode %}