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

# Unified Schema

> One shape for events, markets, and outcomes — across every venue.

PMXT normalizes every supported venue to the same three-level shape:

```
Event  (a topic, like "2028 US Presidential Election")
  └─ Market  (a concrete question, like "Will Gavin Newsom win?")
       └─ Outcome  (a tradable side, like "Yes" @ 0.31)
```

Every response — from the local server, from the hosted Router, or from
a hosted venue pass-through — uses the same field names. Write your client
once, switch venues with a config change.

<Note>
  PMXT serves reads from a cached Postgres catalog for speed (\~10 ms),
  or passes through live to the venue for freshness. The SDK chooses
  per-method based on whether the catalog can safely answer; the response
  envelope is identical either way.
</Note>

## UnifiedMarket

| Field             | Type               | Notes                                                                                                      |
| ----------------- | ------------------ | ---------------------------------------------------------------------------------------------------------- |
| `marketId`        | `string`           | Source-scoped market id; hosted catalog rows use PMXT UUIDs, while venue clients may use venue-native ids. |
| `eventId`         | `string \| null`   | Parent event, if any.                                                                                      |
| `title`           | `string`           | Human-readable market question.                                                                            |
| `slug`            | `string \| null`   | Venue-native slug, when available.                                                                         |
| `description`     | `string \| null`   | Long-form resolution criteria.                                                                             |
| `url`             | `string \| null`   | Canonical venue URL for the market.                                                                        |
| `image`           | `string \| null`   | Venue-hosted image.                                                                                        |
| `category`        | `string \| null`   | Normalized category (e.g. `Sports`, `Politics`).                                                           |
| `tags`            | `string[] \| null` | Free-form tags from the venue.                                                                             |
| `volume`          | `number`           | All-time volume, in USD (or venue base unit).                                                              |
| `volume24h`       | `number`           | Trailing-24h volume.                                                                                       |
| `liquidity`       | `number`           | Depth metric — venue-specific, compared like-for-like.                                                     |
| `resolutionDate`  | `string \| null`   | ISO 8601, UTC.                                                                                             |
| `tickSize`        | `number \| null`   | Minimum price increment, when the venue exposes one.                                                       |
| `status`          | `string \| null`   | Venue status — `active`, `closed`, `resolved`, ...                                                         |
| `contractAddress` | `string \| null`   | On-chain address, when the venue is on-chain.                                                              |
| `outcomes`        | `UnifiedOutcome[]` | See below.                                                                                                 |

## UnifiedOutcome

| Field            | Type     | Notes                                                                                                           |
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `outcomeId`      | `string` | Source-scoped outcome id; hosted catalog rows use PMXT UUIDs, while venue clients use venue-native trading ids. |
| `marketId`       | `string` | Back-reference to the parent market.                                                                            |
| `label`          | `string` | Display label (e.g. `Yes`, `No`, `Donald Trump`).                                                               |
| `price`          | `number` | Last price, 0–1 for binary venues.                                                                              |
| `priceChange24h` | `number` | Absolute change vs 24h ago.                                                                                     |
| `metadata`       | `object` | Venue-specific fields (e.g. `clobTokenId`).                                                                     |

<Note>
  Identifier semantics are source-aware: Router and hosted catalog rows use stable PMXT UUIDs for `marketId` and `outcomeId`. Venue clients and local pass-throughs may use venue-native identifiers. Do not assume every `marketId` / `outcomeId` is a UUID or every outcome id is venue-native. See [Catalog UUID vs Venue ID](/concepts/catalog-uuid-vs-venue-id) when crossing between Router results, hosted trading, and venue-direct clients.
</Note>

## UnifiedEvent

| Field         | Type               | Notes                                                                   |
| ------------- | ------------------ | ----------------------------------------------------------------------- |
| `id`          | `string`           | Stable PMXT event id.                                                   |
| `title`       | `string`           | Event title.                                                            |
| `slug`        | `string \| null`   |                                                                         |
| `description` | `string \| null`   |                                                                         |
| `category`    | `string \| null`   |                                                                         |
| `tags`        | `string[] \| null` |                                                                         |
| `volume`      | `number`           |                                                                         |
| `volume24h`   | `number`           |                                                                         |
| `url`         | `string \| null`   |                                                                         |
| `image`       | `string \| null`   |                                                                         |
| `markets`     | `UnifiedMarket[]`  | Child markets. Nested on every event response — no second fetch needed. |

<Note>
  Fields that a specific venue doesn't expose come back as `null`. That's
  intentional — `null` always means "venue has no value for this field",
  never "PMXT failed to populate it".
</Note>

## Where the shape is defined

The canonical definition lives in
[`core/src/types.ts`](https://github.com/pmxt-dev/pmxt/blob/main/core/src/types.ts)
in the `pmxt` repo, and every SDK client (TypeScript and Python) mirrors
it. The [OpenAPI reference](/api-reference/overview) is generated from
the same source on every `pmxt-core` release.