UMA API: Optimistic Oracle Resolution Data

Polymarket markets do not settle themselves. When a market’s event concludes, the outcome has to be reported on-chain and accepted before holders can redeem winning shares. Polymarket uses UMA’s Optimistic Oracle (V2) for that step, and the Bravado UMA API exposes the resolution lifecycle as both queryable data (REST) and a realtime stream (WebSocket).

The UMA REST endpoints and stream are served from partner-api.bravadotrade.com, the same host as the rest of the Bravado API. Requests require an active paid plan, a WebSockets API key with stream.read, and HMAC authentication. Coverage today is Polymarket.

Why Bravado over reading the chain

Resolution data exists on-chain, so this is not about access. It is about not having to build an indexer to answer a question every prediction market application eventually has to answer: is this position actually finished?

	Reading the chain yourself	Bravado UMA API
Setup	Index the UMA oracle + adapter events yourself	Query an endpoint / subscribe to a stream
Lifecycle state	Decode `ProposePrice` / `DisputePrice` / `Settle` logs	`stage` returned as data
Answer	Interpret the raw `int256` price	`answer` classified (`yes` / `no` / `50-50` / `too-early`)
Correlation to positions	Map oracle events back to your holdings	`condition_id` aligned with the same market identifiers as the rest of Bravado
Freshness	Wait for the confirmed resolution	The proposal streams from the mempool ~1 s before it is mined (`seen_pending`), then confirms with the block

The practical payoff is that a “concluded” event and a redeemable position stop being the same thing in your data model. An application that conflates them will show users balances they cannot access, and book PnL that has not been realised.

How UMA resolution works

Bravado decodes UMA’s Optimistic Oracle V2 directly, so you see each step as it happens.

Proposal

Once the event concludes, a proposer posts the outcome to the oracle with a bond. This is the proposed stage; answer carries the proposed result. Bravado decodes the proposer’s transaction straight from the mempool, so the proposal is delivered with "seen_pending":true ~0.3–1.4 s before it is mined, then a confirming frame follows with the block and tx.

Challenge window

The proposal stays open for a fixed liveness period. If nobody disputes it, it settles automatically on the proposed answer.

Dispute (optional)

Any party may dispute within the window by posting their own bond (disputed stage). A disputed request escalates to UMA’s token-holder vote rather than settling on the proposer’s word.

Settlement

The final answer is written on-chain (settled stage, with the payout). Winning outcome tokens become redeemable at $1; losing tokens go to $0.

A market whose event has visibly concluded is not necessarily settled. Always confirm settled: true before treating a position as realized — an undisputed proposal can still be disputed until its challenge window closes.

Identifiers

Every lifecycle record carries two ids:

question_id — keccak256(ancillaryData), the UMA adapter’s question id. This is the stable, exact key for a resolution.
condition_id — the CTF condition id used everywhere else in Bravado to identify the market. Use it to join resolution state to positions and trades.

The answer field classifies the oracle’s int256 price: yes, no, 50-50, too-early, or other; price_raw preserves the exact value.

REST — query resolution state

Base URL: https://partner-api.bravadotrade.com. Sign every REST request with HMAC, including its sorted query parameters. JSON; ids are hex, payout is an integer micro-USDC string.

`GET /uma/question`

The full lifecycle of one question.

GET https://partner-api.bravadotrade.com/uma/question?id=<0x questionId>

string

required

The 0x 32-byte question_id.

string

Hex question id (keccak256(ancillaryData)).

string

Hex CTF condition id for the market.

string

Human-readable market question (from the ancillary data).

string

Latest answer: yes · no · 50-50 · too-early · other.

boolean

Whether the resolution has finalized on-chain.

object

Show stage fields

string

Address that posted the proposal.

string

Answer classified from the proposed price.

string

Exact int256 price, hex.

integer

Oracle request timestamp (unix seconds).

integer

Polygon block.

string

Transaction hash.

integer

Log index within the block.

boolean

Present and true while this proposal/dispute is known only from the mempool (block is 0); cleared once mined.

object

Same shape as proposed, plus disputer. Present only if the proposal was disputed.

object

Same shape, plus payout (micro-USDC string). Present once settled.

integer

When Bravado last updated this record (unix ms).

Example response

{
  "question_id": "0x3281d5f64c96c007212bdc90b29cb51581058dac59a57fc2b98a31fd7abe0538",
  "condition_id": "0x19c79788f1288b497b5305f81b71c3f20db1ae338b049d733dcb09b5d5d352f6",
  "title": "Will Ben Shelton win the 2026 Men's US Open?",
  "answer": "no",
  "settled": true,
  "proposed": {
    "proposer": "0xef3990a7c8fa92d84dce0e7816ca3410820c1d36",
    "answer": "no", "price_raw": "0x00…00",
    "request_ts": 1767385181, "block": 93012001, "tx": "0x42879bd3…", "log_index": 5
  },
  "settled_at": {
    "answer": "no", "price_raw": "0x00…00", "payout": "500800000",
    "request_ts": 1767385181, "block": 93012040, "tx": "0x7c80413d…", "log_index": 9
  },
  "updated_ms": 1789253500123
}

`GET /uma/market`

The same record, keyed by the market’s CTF condition id.

GET https://partner-api.bravadotrade.com/uma/market?condition_id=<0x conditionId>

string

required

The 0x 32-byte CTF condition id.

`GET /uma/recent`

Recently-updated questions, newest first — a feed of live proposals, disputes, and settlements.

GET https://partner-api.bravadotrade.com/uma/recent?stage=settled&limit=100

string

Filter by current stage: proposed · disputed · settled. Omit for all.

integer

default:"100"

Max records (1–500).

array

Array of question records (same shape as GET /uma/question).

integer

Number of records returned.

WebSocket — stream the lifecycle

For push instead of poll, connect to wss://partner-api.bravadotrade.com/uma/ws. Authenticate the upgrade with HMAC. No subscription message is needed — every Polymarket proposal, dispute, and settlement is pushed to you as a uma frame. To follow a single market, filter on question_id (or condition_id) client-side.

Node.js

// npm install ws
import WebSocket from "ws";
import { createHash, createHmac } from "node:crypto";
const timestamp = String(Date.now());
const payload = [timestamp, "GET", "/uma/ws", createHash("sha256").update("").digest("hex")].join("\n");
const ws = new WebSocket("wss://partner-api.bravadotrade.com/uma/ws", {
  headers: {
    "X-Bravado-API-Key": process.env.BRAVADO_API_KEY,
    "X-Bravado-Timestamp": timestamp,
    "X-Bravado-Signature": createHmac("sha256", process.env.BRAVADO_API_SECRET).update(payload).digest("hex"),
  },
});
ws.on("message", data => console.log(JSON.parse(data.toString())));

For browser clients, have your server sign GET /uma/ticket and return the ticket only to an authorised user. Connect to /uma/ws?ticket=.... Tickets expire after 60 seconds and can be redeemed once. Each reconnect needs a new ticket. Never put the API secret in browser code. The Console playground handles this flow. Successful REST reads cost one credit. Stream payloads use the authenticated WebSocket credit model. Missing credentials are rejected; the Free plan cannot access UMA. A pending proposal is not a final settlement. The uma frame carries stage, answer, question_id, condition_id, proposer, disputer, price_raw, payout, request_ts, title, block, tx, and log_index. A proposal or dispute decoded from the mempool carries "seen_pending":true with block:0; the same question_id is re-sent once mined with the real block/tx (the pending→mined pair). Settlements are mined-only and never carry seen_pending.

Trade API — order execution; redeem settled positions via POST /v2/trade/positions/redeem
Trader Data API — wallet PnL, trade logs, and tax statements
Market Data — realtime trades and order books over WebSockets
Polymarket — market coverage and supported features

Get Started

Supported Prediction Markets

Market Data

Trader Data

Execution

Automation

Resolution

Tools

Use Cases

SDKs

UMA API: Optimistic Oracle Resolution Data

Why Bravado over reading the chain

How UMA resolution works

Identifiers

REST — query resolution state

`GET /uma/question`

`GET /uma/market`

`GET /uma/recent`

WebSocket — stream the lifecycle

​Why Bravado over reading the chain

​How UMA resolution works

​Identifiers

​REST — query resolution state

​GET /uma/question

​GET /uma/market

​GET /uma/recent

​WebSocket — stream the lifecycle

​Related

Why Bravado over reading the chain

How UMA resolution works

Identifiers

REST — query resolution state

`GET /uma/question`

`GET /uma/market`

`GET /uma/recent`

WebSocket — stream the lifecycle

Related