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

# Prediction Market Data Model

> How prediction market data is structured across events, markets, and trades

This page describes the core entities in the Prediction Markets API and how they
relate. All field names below come from
`resources/metadata-api/openapi.json`.

## High-Level Model

Events group one or more markets. Each market has onchain accounts (mints and a
ledger), and produces orderbook and trade data. The API does not expose a
dedicated “Order” schema; order intent is represented in the orderbook payloads.

```mermaid theme={null}
flowchart TD
  Event -->|contains| Market
  Event -->|sources| SettlementSource
  Market -->|accounts map to| MarketAccountInfo
  Market -->|orderbook| Orderbook
  Market -->|trades| Trade
```

## Example (Red Sox vs Yankees)

**[Event](#event-singleeventresponse)**: “Will the Boston Red Sox win the World Series?”\
**[Market](#market-singlemarketresponse)**: A single YES/NO market under that event.\
**[Orderbook](#orderbook)**: The current bid/ask ladders for that market.\
**[Trade](#trade-singletraderesponse)**: Executed trades for that market ticker.

In practice:

* You discover the **event** and its **markets**.
* You look up **market accounts** (yes/no mints, ledger).
* You pull **orderbook** and **trade** history by market ticker or mint.

## Trading Flow (Spot → Outcome Token)

The Trade API [`/order`](/resources/trading-api/order/order) endpoint can trade
from any spot token to a prediction market outcome token. The transaction
always routes through the settlement mint as an intermediate step:

1. **Input Token → Settlement Mint**
2. **Settlement Mint → Outcome Token**

The `/order` response returns a single transaction that executes both swaps.

### Market Initialization Behavior

The Trading API automatically detects whether the market is initialized:

* **Initialized markets**: the two-step swap path executes directly.
* **Uninitialized markets**: the transaction includes on-demand market
  tokenization before executing the swap path.

<Note>
  On-demand market tokenization incurs a small fee, which is included in the
  transaction when trading into an uninitialized market.
</Note>

### Checking Initialization Status (Optional)

You can check `isInitialized` in the market response from the
[Markets API](/resources/metadata-api/markets/markets), but you
do not need to do this ahead of time, because the Trading API handles it automatically.

<Warning>
  The `isInitialized` query parameter on the
  [Events](/resources/metadata-api/events/events),
  [Markets](/resources/metadata-api/markets/markets), and
  [Series](/resources/metadata-api/series/series) listing endpoints filters results
  to markets that have already been tokenized through a DFlow trade. Markets that
  are active on Kalshi but have not yet been traded through DFlow will have
  `isInitialized = false` and will be excluded when you pass
  `isInitialized=true`.

  This is especially common with **short-duration markets** (e.g., 15-minute
  crypto price markets) where initialization resets with each new market. If you
  need to display all active markets, omit the `isInitialized` parameter.
</Warning>

## Entity Reference

### Event (SingleEventResponse)

| Field               | Type            | Notes                          |
| ------------------- | --------------- | ------------------------------ |
| `ticker`            | string          | Event ticker                   |
| `seriesTicker`      | string          | Series identifier              |
| `title`             | string          | Event title                    |
| `subtitle`          | string          | Event subtitle                 |
| `competition`       | string \| null  | Competition name               |
| `competitionScope`  | string \| null  | Scope of competition           |
| `imageUrl`          | string \| null  | Image URL                      |
| `liquidity`         | integer \| null | Aggregate liquidity            |
| `openInterest`      | integer \| null | Aggregate open interest        |
| `volume`            | integer \| null | Total volume                   |
| `volume24h`         | integer \| null | 24h volume                     |
| `strikeDate`        | integer \| null | Unix timestamp                 |
| `strikePeriod`      | string \| null  | Strike period label            |
| `settlementSources` | array \| null   | Settlement sources             |
| `markets`           | array \| null   | Array of markets (if included) |

SettlementSource fields:

| Field  | Type   | Notes       |
| ------ | ------ | ----------- |
| `name` | string | Source name |
| `url`  | string | Source URL  |

### Market (SingleMarketResponse)

| Field                 | Type           | Notes                 |
| --------------------- | -------------- | --------------------- |
| `ticker`              | string         | Market ticker         |
| `eventTicker`         | string         | Parent event ticker   |
| `marketType`          | string         | Market type           |
| `title`               | string         | Market title          |
| `subtitle`            | string         | Market subtitle       |
| `yesSubTitle`         | string         | YES outcome label     |
| `noSubTitle`          | string         | NO outcome label      |
| `openTime`            | integer        | Unix timestamp        |
| `closeTime`           | integer        | Unix timestamp        |
| `expirationTime`      | integer        | Unix timestamp        |
| `status`              | string         | Market status         |
| `result`              | string         | Resolution outcome    |
| `volume`              | integer        | Market volume         |
| `openInterest`        | integer        | Market open interest  |
| `canCloseEarly`       | boolean        | Early close enabled   |
| `earlyCloseCondition` | string \| null | Early close condition |
| `rulesPrimary`        | string         | Primary rules         |
| `rulesSecondary`      | string \| null | Secondary rules       |
| `yesBid`              | string \| null | Best bid (YES)        |
| `yesAsk`              | string \| null | Best ask (YES)        |
| `noBid`               | string \| null | Best bid (NO)         |
| `noAsk`               | string \| null | Best ask (NO)         |
| `accounts`            | object         | Map of account info   |

MarketAccountInfo fields:

| Field              | Type            | Notes               |
| ------------------ | --------------- | ------------------- |
| `marketLedger`     | string          | Market ledger mint  |
| `yesMint`          | string          | YES outcome mint    |
| `noMint`           | string          | NO outcome mint     |
| `isInitialized`    | boolean         | Account initialized |
| `redemptionStatus` | string \| null  | Redemption state    |
| `scalarOutcomePct` | integer \| null | Scalar outcome %    |

### Trade (SingleTradeResponse)

| Field             | Type    | Notes                 |
| ----------------- | ------- | --------------------- |
| `tradeId`         | string  | Trade identifier      |
| `ticker`          | string  | Market ticker         |
| `price`           | integer | Price (0-10000 scale) |
| `count`           | integer | Quantity              |
| `yesPrice`        | integer | YES price             |
| `noPrice`         | integer | NO price              |
| `yesPriceDollars` | string  | YES price in dollars  |
| `noPriceDollars`  | string  | NO price in dollars   |
| `takerSide`       | string  | Buyer/seller side     |
| `createdTime`     | integer | Unix timestamp        |

### Orderbook

Orderbook responses include a sequence number and bid ladders for YES and NO.
Each ladder is a map of **price strings** (4‑decimal probability) to **size
integers**.

| Field      | Type    | Notes                 |
| ---------- | ------- | --------------------- |
| `sequence` | integer | Monotonic sequence id |
| `yes_bids` | object  | Map of price → size   |
| `no_bids`  | object  | Map of price → size   |

Example:

```json theme={null}
{
  "no_bids": {
    "0.0100": 2892941,
    "0.0200": 9478,
    "0.0300": 349205
  },
  "sequence": 4169465,
  "yes_bids": {}
}
```

Use:

* `GET /api/v1/orderbook/{market_ticker}`
* `GET /api/v1/orderbook/by-mint/{mint_address}`

See the endpoint docs:

* [Orderbook by ticker](/resources/metadata-api/orderbook/orderbook-by-ticker)
* [Orderbook by mint](/resources/metadata-api/orderbook/orderbook-by-mint)