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

# Oracle Event

> UMA Optimistic Oracle events — market initializations, proposals, disputes, resolutions, settlements, and admin actions on Polymarket.

Oracle events stream the full lifecycle of Polymarket's UMA-based market resolution system. Every Polymarket market is resolved through UMA's Optimistic Oracle, which uses a propose-challenge-resolve cycle on the Polygon blockchain.

**The only WebSocket stream of enriched UMA oracle events.** Decoded from on-chain event logs, enriched with full market metadata (title, outcomes, images, token IDs), and pushed to your connection in real-time.

## How Polymarket Resolution Works

1. A market is **initialized** on-chain (QuestionInitialized on the UMA adapter)
2. A **proposer** submits an answer (YES or NO) via ProposePrice on UMA's Optimistic Oracle V2 and posts a USDC bond
3. A 2-hour **liveness window** opens where anyone can dispute
4. If no dispute, the oracle **settles** (Settle event on OO V2) and the market **resolves** (QuestionResolved on the adapter)
5. For neg-risk markets (the majority), a second transaction calls `resolveQuestion()` on the NegRiskOperator, which triggers **condition\_resolution** on the Conditional Tokens contract. **Positions become redeemable at this point.**
6. If disputed, the question **resets** and goes to UMA's DVM for a token-holder vote
7. Admins can **flag**, **pause**, or **manually resolve** markets in edge cases

## Subscribe

```json theme={null}
{
  "action": "subscribe",
  "type": "oracle"
}
```

## Oracle Event Types

Every oracle event has an `oracle_type` field indicating what happened:

<ResponseField name="initialization" type="string">
  Market initialized on-chain. The UMA adapter has registered a new question. This is the first on-chain event in a market's lifecycle.
</ResponseField>

<ResponseField name="proposal" type="string">
  Resolution proposed on UMA Optimistic Oracle V2 (ProposePrice). A proposer has submitted an answer and posted a bond. The 2-hour liveness countdown begins. Includes `proposer` address, `proposed_price` (1.0 = YES, 0.0 = NO), and `expiration_timestamp`.
</ResponseField>

<ResponseField name="dispute" type="string">
  Resolution disputed on UMA Optimistic Oracle V2 (DisputePrice). Someone challenged the proposed outcome. The market re-enters the proposal phase or escalates to UMA's DVM for a token-holder vote. **High signal, rare event.** Price swings are likely. Includes `proposer`, `disputer`, and `proposed_price`.
</ResponseField>

<ResponseField name="settled" type="string">
  Settled on UMA Optimistic Oracle V2 after the liveness period expires. The oracle has accepted the proposed answer. Includes `resolved_price` and `proposer`.
</ResponseField>

<ResponseField name="resolution" type="string">
  Market officially resolved via UMA oracle (QuestionResolved on the adapter). The most common event type (\~200+ per hour during active sports periods). Includes the final `resolved_price`, `payouts` array, and `resolved_outcome`.
</ResponseField>

<ResponseField name="reset" type="string">
  Question reset after a dispute. The market goes back to the proposal phase.
</ResponseField>

<ResponseField name="flag" type="string">
  Market flagged by admin. Something may be wrong with the resolution.
</ResponseField>

<ResponseField name="manual_resolution" type="string">
  Market manually resolved by admin, bypassing the normal oracle flow. Includes `payouts` array.
</ResponseField>

<ResponseField name="condition_resolution" type="string">
  Condition resolved on the Conditional Tokens contract (ConditionResolution event). **This is the moment positions become redeemable.** For neg-risk markets (the majority on Polymarket), this fires in a separate transaction \~2-3 minutes after `resolution`. For standard markets, it fires atomically with `resolution`. Includes `resolved_price`, `payouts`, `condition_id`, and full market metadata. Use this event to trigger redemption workflows.
</ResponseField>

## Resolution Event (real payload)

A tennis market resolved — Baena won the first set:

```json theme={null}
{
  "type": "oracle",
  "timestamp": 1773755193000,
  "data": {
    "adapter_address": "0x65070be91477460d8a7aeeb94ef92fe056c2f2a7",
    "block_number": 84317580,
    "condition_id": "0xb0b51e92993bf204c76f10a49bdaa595d817f1768a9ae79e546e83695f1cb142",
    "event_title": "Murcia: Nikolas Sanchez Izquierdo vs Roberto Carballes Baena",
    "event_type": "oracle",
    "log_index": 197,
    "market_image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/atp-tour-b4390c4fb8.jpg",
    "market_slug": "atp-izquier-baena-2026-03-16-first-set-winner-Izquierdo-vs-Baena",
    "market_title": "Set 1 Winner: Izquierdo vs Baena",
    "neg_risk": false,
    "oracle_type": "resolution",
    "outcomes": ["Izquierdo", "Baena"],
    "payouts": [0, 1],
    "question_id": "0x34241c96d35a8ffbd4093f9a360e08f97c5691f66e9bfe29dd46e4763dae833e",
    "resolved_outcome": "Baena",
    "resolved_price": 0,
    "timestamp": 1773755193000,
    "token_ids": [
      "100092605222559788173670687007064638617594421724580870112622623059744413023416",
      "82111831612810431769649657775457339958533284370449876495200499593908955489467"
    ],
    "tokens": {
      "100092605222559788173670687007064638617594421724580870112622623059744413023416": "Izquierdo",
      "82111831612810431769649657775457339958533284370449876495200499593908955489467": "Baena"
    },
    "tx_hash": ""
  }
}
```

## Proposal Event (ProposePrice from OO V2)

A proposer submits YES for an XRP price market, with a 2-hour liveness window. Proposals include full market metadata:

```json theme={null}
{
  "type": "oracle",
  "timestamp": 1773755537000,
  "data": {
    "adapter_address": "0x65070be91477460d8a7aeeb94ef92fe056c2f2a7",
    "block_number": 84317752,
    "condition_id": "0xc9d0815d7f12e601ac3ce457de5b5d6f18ba5f48df5ffd246cec4c19a9254200",
    "event_title": "What price will XRP hit on March 17?",
    "event_type": "oracle",
    "expiration_timestamp": 1773762737000,
    "log_index": 372,
    "market_image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/XRP-logo.png",
    "market_slug": "will-xrp-dip-to-1pt5-on-march-17",
    "market_title": "Will XRP dip to $1.50 on March 17?",
    "neg_risk": false,
    "oracle_type": "proposal",
    "outcomes": ["Yes", "No"],
    "proposed_price": 1,
    "proposer": "0xedc1e7a3a9275c512f669cb9236f1d03c2fc2e39",
    "question_id": "oo_v2:0x65070be91477460d8a7aeeb94ef92fe056c2f2a7:1773720049",
    "timestamp": 1773755537000,
    "token_ids": [
      "29532348047030596543075496892560093525999458628692812631919395372535371275514",
      "43096817250499798050326473461465682146308168398097552897166323529988349492396"
    ],
    "tokens": {
      "29532348047030596543075496892560093525999458628692812631919395372535371275514": "Yes",
      "43096817250499798050326473461465682146308168398097552897166323529988349492396": "No"
    },
    "tx_hash": ""
  }
}
```

## Field Reference

### Core Fields (all oracle events)

<ResponseField name="oracle_type" type="string" required>
  Type of oracle event: `initialization`, `proposal`, `dispute`, `settled`, `resolution`, `condition_resolution`, `reset`, `flag`, `unflag`, `pause`, `unpause`, `manual_resolution`.
</ResponseField>

<ResponseField name="question_id" type="string" required>
  UMA's unique identifier for this market question.
</ResponseField>

<ResponseField name="adapter_address" type="string" required>
  Which UMA adapter contract this event relates to.
</ResponseField>

<ResponseField name="block_number" type="number" required>
  Polygon block number where the event was emitted.
</ResponseField>

<ResponseField name="log_index" type="number" required>
  Position of this event within the block's logs.
</ResponseField>

<ResponseField name="timestamp" type="number" required>
  Block timestamp in milliseconds.
</ResponseField>

### Proposal Fields (proposal only)

<ResponseField name="proposer" type="string">
  Address of the account that proposed the resolution.
</ResponseField>

<ResponseField name="proposed_price" type="number">
  The proposed answer. `1.0` = YES (first outcome), `0.0` = NO (second outcome).
</ResponseField>

<ResponseField name="expiration_timestamp" type="number">
  When the 2-hour liveness window expires (unix milliseconds). After this time, the proposal can be settled if not disputed.
</ResponseField>

### Dispute Fields (dispute only)

<ResponseField name="disputer" type="string">
  Address of the account that disputed the proposal.
</ResponseField>

<ResponseField name="proposer" type="string">
  Address of the original proposer whose answer is being challenged.
</ResponseField>

<ResponseField name="proposed_price" type="number">
  The proposed answer that was disputed.
</ResponseField>

### Resolution Fields (resolution, condition\_resolution, settled, and manual\_resolution)

<ResponseField name="resolved_price" type="number">
  The settled price from UMA. `1.0` = first outcome wins (usually YES), `0.0` = second outcome wins (usually NO), `0.5` = split/tie.
</ResponseField>

<ResponseField name="resolved_outcome" type="string">
  Human-readable winning outcome (e.g. "Yes", "No", "L1ga Team"). Derived from `resolved_price` + market metadata. Returns `"Split"` for voided markets where payouts are `[1, 1]`.
</ResponseField>

<ResponseField name="payouts" type="array">
  Payout array from UMA. `[1, 0]` means the first outcome wins. `[0, 1]` means the second outcome wins. `[1, 1]` means a split (both outcomes pay out). Present on `resolution`, `condition_resolution`, and `manual_resolution`.
</ResponseField>

### Enrichment Fields (from Polymarket metadata)

These fields are populated automatically when the market's metadata is available.

<ResponseField name="condition_id" type="string">
  Polymarket's condition identifier for this market.
</ResponseField>

<ResponseField name="market_title" type="string">
  Human-readable market question (e.g. "Will Bitcoin reach \$100K?").
</ResponseField>

<ResponseField name="market_slug" type="string">
  URL slug for the market on polymarket.com.
</ResponseField>

<ResponseField name="event_title" type="string">
  Parent event name if this market is part of a group (e.g. "Dota 2: Pipsqueak+4 vs L1ga Team (BO3)").
</ResponseField>

<ResponseField name="market_image" type="string">
  Market image URL from Polymarket.
</ResponseField>

<ResponseField name="outcomes" type="array">
  All outcome names for this market (e.g. `["Yes", "No"]` or `["Pipsqueak+4", "L1ga Team"]`).
</ResponseField>

<ResponseField name="token_ids" type="array">
  All conditional token IDs for this market.
</ResponseField>

<ResponseField name="tokens" type="object">
  Map of token ID to outcome name (e.g. `{"2174263...": "Yes", "4839315...": "No"}`).
</ResponseField>

<ResponseField name="neg_risk" type="boolean">
  Whether this market uses the neg-risk framework (multi-outcome markets like elections).
</ResponseField>

## Frequency

Oracle events are **not evenly distributed**. They come in bursts when UMA's resolver bot processes batches of markets.

| Period                     | Typical Volume                                        |
| -------------------------- | ----------------------------------------------------- |
| Active sports hours        | 200+ resolutions/hour, proposals flowing continuously |
| Quiet periods              | 10-50 resolutions/hour                                |
| Proposals (ProposePrice)   | \~30/hour, continuous flow                            |
| Settlements (Settle)       | \~30/hour, fires after 2-hour liveness                |
| Disputes                   | A few per month (high signal)                         |
| Flags / Manual resolutions | Very rare                                             |

## Trading Implications

| Event                     | What It Means                                                                                  | Action                                     |
| ------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------ |
| **initialization**        | New market registered on-chain.                                                                | First signal of a new tradeable market     |
| **proposal**              | Answer proposed, 2-hour countdown started.                                                     | Monitor for disputes, position accordingly |
| **dispute**               | Proposed outcome challenged. Uncertainty returns.                                              | Watch for price swings, potential arb      |
| **settled**               | Oracle accepted the answer after liveness.                                                     | Resolution imminent                        |
| **resolution**            | Market outcome decided on UMA adapter. For neg-risk markets, positions are not yet redeemable. | Outcome known, prepare for redemption      |
| **condition\_resolution** | Condition resolved on CTF contract. **Positions are now redeemable.**                          | Trigger redemption, notify users           |
| **reset**                 | Market re-enters proposal phase after dispute.                                                 | Resolution delayed, reassess positions     |
| **flag**                  | Admin flagged an issue. Market may be paused.                                                  | Caution, reduce exposure                   |
| **manual\_resolution**    | Admin override. Could be controversial.                                                        | Check outcome, compare to expectations     |