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

# UMA REST API

> Look up captured UMA resolution state by question or condition ID, or read recently updated questions.

Use REST to read the resolution state already captured by Bravado for Polymarket. Read the [UMA overview](https://docs.bravadotrade.com/products/uma-api.md) for the lifecycle and [coverage limits](https://docs.bravadotrade.com/products/uma-api.md#coverage-and-history).

> [!NOTE]
>
> Use the same Market Data credential (`stream.read`) as the UMA WebSocket, with HMAC authentication and an active paid plan. There is no separate UMA key. Successful REST reads cost **1 API credit per response**, including cached reads.

> [!NOTE]
>
> These endpoints do not provide a full historical archive. There is no date-range filter, cursor, offset or backfill endpoint. Question and market lookups cover captured records still retained by the service. `/uma/recent` returns at most 500 current question records, not a paginated event log.

## Make a signed request

Use your existing Market Data key and secret from [Console](https://console.bravadotrade.com/keys), on an active paid plan. This example makes one REST request. A successful response costs **1 API credit**. Keep the secret on your server.

```javascript Node.js theme={null}
import { createHash, createHmac } from "node:crypto";

const key = process.env.BRAVADO_API_KEY;
const secret = process.env.BRAVADO_API_SECRET;
if (!key || !secret) throw new Error("Set BRAVADO_API_KEY and BRAVADO_API_SECRET");

const url = new URL("https://partner-api.bravadotrade.com/uma/recent");
url.searchParams.set("limit", "1");
url.searchParams.sort();
const timestamp = String(Date.now());
const requestTarget = url.pathname + url.search;
const bodyHash = createHash("sha256").update("").digest("hex");
const payload = [timestamp, "GET", requestTarget, bodyHash].join("\n");
const response = await fetch(url, {
  headers: {
    "X-Bravado-API-Key": key,
    "X-Bravado-Timestamp": timestamp,
    "X-Bravado-Signature": createHmac("sha256", secret).update(payload).digest("hex"),
  },
});
console.log("HTTP", response.status);
console.log(await response.json());
```

A `200` with `questions` confirms that your authenticated REST read succeeded. An empty `questions` array reports no matching recent records; it does not establish complete historical coverage. A `401` only confirms an authentication refusal, not a successful read of resolution data.

## Endpoints

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 captured, retained lifecycle state of one question. Stage objects are present only when Bravado has captured that stage; a record is not a guarantee of complete event history.

```text theme={null}
GET https://partner-api.bravadotrade.com/uma/question?id=<0x questionId>
```

**id** `string` *required*

The `0x` 32-byte `question_id`.

**question\_id** `string`

Hex question id (`keccak256(ancillaryData)`).

**condition\_id** `string`

Hex CTF condition id for the market.

**title** `string`

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

**answer** `string`

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

**settled** `boolean`

Whether the resolution has finalized on-chain.

**proposed** `object`

**stage fields**

**proposer** `string`

Address that posted the proposal.

**answer** `string`

Answer classified from the proposed price.

**price\_raw** `string`

Exact `int256` price, hex.

**request\_ts** `integer`

Oracle request timestamp (unix seconds).

**block** `integer`

Polygon block.

**tx** `string`

Transaction hash.

**log\_index** `integer`

Log index within the block.

**seen\_pending** `boolean`

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

**disputed** `object`

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

**settled\_at** `object`

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

**updated\_ms** `integer`

When Bravado last updated this record (unix ms).

```json Example response theme={null}
{
  "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 retained record as `/uma/question`, looked up by the market's CTF condition id. It has the same coverage and retention limits.

```text theme={null}
GET https://partner-api.bravadotrade.com/uma/market?condition_id=<0x conditionId>
```

**condition\_id** `string` *required*

The `0x` 32-byte CTF condition id.

### `GET /uma/recent`

Recently updated question records, newest first by last update. Each question appears with its current captured state, not as one row per proposal, dispute or settlement event. The `stage` filter selects the current stage: a question that has settled is not returned as `proposed` even if its record includes an earlier proposal.

```text theme={null}
GET https://partner-api.bravadotrade.com/uma/recent?stage=settled&limit=100
```

**stage** `string`

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

**limit** `integer` (default: 100)

Max question records in this response (1–500). This is a result cap, not a page size: there is no cursor, offset or next page.

**questions** `array`

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

**count** `integer`

Number of records returned.

## Missing records and freshness

* A `404` from a question or market lookup means no retained record is available for that ID. It does not establish that the market never existed, never resolved or never had a dispute.
* A missing `proposed`, `disputed` or `settled_at` object means that stage is absent from the captured record. Do not infer a complete event history from omitted fields.
* `updated_ms` is the record's last update time, not the time of your request. Responses can be cached; a cached response may also be served during an upstream interruption. Check this timestamp before relying on freshness.
* A `502` can indicate that the resolution feed is unavailable. Do not interpret it as an empty result or an unresolved market.

For access refusals, check your signature (`401`), credential scope and active paid plan (`403`), and credit allowance (`402`). See [HMAC authentication](https://docs.bravadotrade.com/authentication.md) and [API credits](https://docs.bravadotrade.com/api-credits.md).

## Continue with live updates

Use the [WebSocket](https://docs.bravadotrade.com/api/market-data/uma-websocket.md) for new events. REST can refresh a retained question's state after a disconnect, but neither interface guarantees recovery of every intermediate event you missed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.