> ## Documentation Index
> Fetch the complete documentation index at: https://docs.predexon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Oracle Events

> Real-time UMA oracle events: proposals, disputes, settlements, and resets for Polymarket markets

The oracle channel (`"oracle"`) streams real-time UMA oracle resolution events for Polymarket markets. Track when outcomes are proposed, disputed, settled, or reset.

Polymarket uses the [UMA Optimistic Oracle](https://docs.polymarket.com/concepts/resolution) to resolve markets. The process follows a propose-challenge-settle cycle: a proposer submits an outcome with a bond, a 2-hour challenge window opens, and if undisputed the outcome is accepted. Disputes escalate to UMA's voting mechanism.

## Subscribe

```json theme={null}
{
  "action": "subscribe",
  "platform": "polymarket",
  "version": 1,
  "type": "oracle",
  "filters": {
    "condition_ids": ["0x4c57..."]
  }
}
```

### Filter Types

| Filter          | Description          | Example                        |
| --------------- | -------------------- | ------------------------------ |
| `condition_ids` | Market condition IDs | `["0x4c57..."]`                |
| `market_slugs`  | Market URL slugs     | `["will-x-happen-by-april-7"]` |

Use `["*"]` for the full firehose of all oracle events (in either filter).

<Note>
  `users` and `token_ids` filters are not supported on the oracle channel.
</Note>

***

## Event Types

### proposal

Outcome proposed. A 2-hour liveness window starts, during which the proposal can be disputed.

Frequency: \~6,800/day

```json theme={null}
{
  "type": "event",
  "subscription_id": "sub_xxx",
  "data": {
    "event_type": "proposal",
    "condition_id": "0x4c57...",
    "market_id": "123456",
    "title": "Will X happen by April 7?",
    "market_slug": "will-x-happen-by-april-7",
    "image": "https://...",
    "outcomes": ["Yes", "No"],
    "tokens": [{"token_id": "82855...", "label": "Yes"}, {"token_id": "55194...", "label": "No"}],
    "is_neg_risk": false,
    "proposer": "0xabc...",
    "proposed_price": "1",
    "expiration_timestamp": 1775204004,
    "request_timestamp": 1775196804,
    "timestamp": 1775196804
  }
}
```

***

### settled

Oracle accepted the proposed answer. The market is resolving.

Frequency: \~6,600/day

```json theme={null}
{
  "type": "event",
  "subscription_id": "sub_xxx",
  "data": {
    "event_type": "settled",
    "condition_id": "0x4c57...",
    "market_id": "123456",
    "title": "Will X happen by April 7?",
    "market_slug": "will-x-happen-by-april-7",
    "image": "https://...",
    "outcomes": ["Yes", "No"],
    "tokens": [{"token_id": "82855...", "label": "Yes"}, {"token_id": "55194...", "label": "No"}],
    "is_neg_risk": false,
    "proposer": "0xabc...",
    "disputer": null,
    "settled_price": "1",
    "payout": "752000000",
    "request_timestamp": 1775196804,
    "timestamp": 1775204005
  }
}
```

***

### dispute

Proposal challenged. Rare but high signal.

Frequency: \~15/day

```json theme={null}
{
  "type": "event",
  "subscription_id": "sub_xxx",
  "data": {
    "event_type": "dispute",
    "condition_id": "0x4c57...",
    "market_id": "123456",
    "title": "Will X happen by April 7?",
    "market_slug": "will-x-happen-by-april-7",
    "image": "https://...",
    "outcomes": ["Yes", "No"],
    "tokens": [{"token_id": "82855...", "label": "Yes"}, {"token_id": "55194...", "label": "No"}],
    "is_neg_risk": false,
    "proposer": "0xabc...",
    "disputer": "0xdef...",
    "proposed_price": "1",
    "request_timestamp": 1775196804,
    "timestamp": 1775200405
  }
}
```

***

### reset

Dispute succeeded. The market re-enters the proposal phase.

Frequency: \~15/day

```json theme={null}
{
  "type": "event",
  "subscription_id": "sub_xxx",
  "data": {
    "event_type": "reset",
    "condition_id": "0x4c57...",
    "question_id": "0x9f8e...",
    "title": "Will X happen by April 7?",
    "market_slug": "will-x-happen-by-april-7",
    "image": "https://...",
    "outcomes": ["Yes", "No"],
    "tokens": [{"token_id": "82855...", "label": "Yes"}, {"token_id": "55194...", "label": "No"}],
    "is_neg_risk": false,
    "request_timestamp": 1775196804,
    "timestamp": 1775200406
  }
}
```

***

## Field Reference

### Common Fields (all event types)

| Field               | Type      | Description                                          |
| ------------------- | --------- | ---------------------------------------------------- |
| `event_type`        | string    | `"proposal"`, `"settled"`, `"dispute"`, or `"reset"` |
| `condition_id`      | string    | Market condition ID (hex)                            |
| `title`             | string    | Market question text                                 |
| `market_slug`       | string    | Market URL slug                                      |
| `image`             | string    | Market image URL                                     |
| `outcomes`          | string\[] | Outcome labels (e.g. `["Yes", "No"]`)                |
| `tokens`            | object\[] | Token IDs with labels (`token_id`, `label`)          |
| `is_neg_risk`       | boolean   | Whether the market uses neg-risk framework           |
| `timestamp`         | number    | When Predexon processed the event (Unix s)           |
| `request_timestamp` | number    | When the original price request was made (Unix s)    |

### Event-Specific Fields

| Field                  | Type         | Events                     | Description                                                           |
| ---------------------- | ------------ | -------------------------- | --------------------------------------------------------------------- |
| `market_id`            | string       | proposal, dispute, settled | Polymarket market ID                                                  |
| `question_id`          | string       | reset                      | UMA question ID                                                       |
| `proposer`             | string       | proposal, dispute, settled | Address that proposed the outcome                                     |
| `disputer`             | string\|null | dispute, settled           | Address that disputed. Present but `null` in settled when undisputed. |
| `proposed_price`       | string       | proposal, dispute          | Proposed outcome: `"1"` = Yes, `"0"` = No                             |
| `settled_price`        | string       | settled                    | Final resolved outcome: `"1"` = Yes, `"0"` = No                       |
| `expiration_timestamp` | number       | proposal                   | 2-hour liveness window end (Unix s)                                   |
| `payout`               | string       | settled                    | Bond payout amount (uint256)                                          |

***

## Unsubscribe

To stop receiving oracle events, send an unsubscribe with the subscription ID from the original `ack`:

```json theme={null}
{
  "action": "unsubscribe",
  "subscription_id": "sub_xxx"
}
```

See [Subscriptions](/websocket/subscriptions) for full details on subscription management, including updating filters on an existing subscription.