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

# Prediction Markets APIs

> Trade prediction markets programmatically with a unified API. Access market data, execute orders, and stream real-time prices across platforms like Polymarket.

<Warning>
  **Alpha** — Prediction Markets APIs are in early access. Endpoints, response formats, and WebSocket events may change without notice. Not recommended for production use yet.
</Warning>

## Overview

Mobula's Prediction Markets APIs provide a complete interface to interact with prediction markets (currently supporting Polymarket on Polygon):

<CardGroup cols={3}>
  <Card title="Market Data" icon="chart-bar" color="#5C7DF9">
    **Read Markets**

    * Market details & prices
    * OHLCV candlesticks
    * Order book depth
    * Trade history
    * Live short-duration markets
  </Card>

  <Card title="Search & Discovery" icon="magnifying-glass" color="#10B981">
    **Find Markets**

    * Full-text search
    * Trending markets
    * Category browsing
    * Volume/liquidity filters
  </Card>

  <Card title="Execution" icon="bolt" color="#F59E0B">
    **Trade Markets**

    * Account setup & auth
    * Order building & signing
    * Order submission
    * Deposits, withdrawals & redemptions
  </Card>
</CardGroup>

## How It Works

Prediction markets let users trade on the outcome of real-world events. Each market has **outcomes** (e.g., "Yes" / "No") represented as conditional tokens priced between $0 and $1. If your predicted outcome occurs, your tokens are redeemable for \$1 each.

### Architecture

```
Your App → Mobula PM API → Polymarket CLOB (Polygon)
```

Mobula abstracts the complexity of interacting with Polymarket's Central Limit Order Book (CLOB):

* **EIP-712 typed data** is built server-side — you only need to sign
* **Account deployment** (Safe wallet) is handled via simple build/submit endpoints
* **Token approvals** are pre-built as ready-to-send calldata
* **Order matching** goes through Polymarket's CLOB for best execution

### Trading Flow

<Steps>
  <Step title="Setup Account">
    Check if your wallet has a deployed Safe account via `GET /api/2/wallet/pm/status`. If not, deploy one using the `/api/2/pm/deploy/build` and `/api/2/pm/deploy/submit` endpoints.
  </Step>

  <Step title="Authenticate">
    Build auth typed data via `POST /api/2/pm/auth/build`, sign it with your wallet, then derive CLOB API credentials via `POST /api/2/pm/auth/derive`.
  </Step>

  <Step title="Approve Tokens">
    Build approval transactions via `POST /api/2/pm/approval/build` and submit them on-chain. This allows the exchange contracts to transfer your USDC and conditional tokens.
  </Step>

  <Step title="Place Orders">
    Build an order via `POST /api/2/pm/order/build`, sign the returned EIP-712 typed data, then submit via `POST /api/2/pm/order/submit`.
  </Step>
</Steps>

### Data Conventions

* **Dates** (creation, end, resolution): ISO 8601 strings with `Z` suffix (e.g., `"2026-03-15T10:30:00.000Z"`)
* **Timestamps** (trade events, price snapshots, candles): Unix milliseconds as `number` (e.g., `1709913600000`)
* **Monetary values**: Always suffixed with `USD` (e.g., `volume24hUSD`, `liquidityUSD`, `amountUSD`)
* **Probabilities**: `priceUSD` field, range 0 to 1 (consistent USD suffix convention)

## Supported Platforms

| Platform   | Chain         | Status |
| ---------- | ------------- | ------ |
| Polymarket | Polygon (137) | Live   |

## API Endpoints

<CardGroup cols={2}>
  <Card title="Market Details" icon="circle-info" href="/rest-api-reference/endpoint/pm-market-details">
    Get full details for a specific market.
  </Card>

  <Card title="Search Markets" icon="magnifying-glass" href="/rest-api-reference/endpoint/pm-search">
    Search and filter prediction markets.
  </Card>

  <Card title="Market OHLCV" icon="chart-candlestick" href="/rest-api-reference/endpoint/pm-market-ohlcv">
    Get candlestick price data for an outcome.
  </Card>

  <Card title="Order Build" icon="hammer" href="/rest-api-reference/endpoint/pm-order-build">
    Build an order for signing.
  </Card>
</CardGroup>

<Note>
  **Getting Started**: You can query market data endpoints using **demo-api.mobula.io** without signup. For execution endpoints, [generate a free API key](https://admin.mobula.io) to use **api.mobula.io**.
</Note>

<Tip>
  PM endpoints follow the same conventions as the spot API: [authentication](/rest-api-reference/authentification), rate limiting, and `data` response envelope. WebSocket streams require a Growth or Enterprise plan.
</Tip>

## Error Responses

All PM endpoints return errors in the standard NestJS format:

| Status Code | Meaning                                                                |
| ----------- | ---------------------------------------------------------------------- |
| `400`       | Bad Request — invalid or missing parameters                            |
| `401`       | Unauthorized — missing or invalid API key                              |
| `404`       | Not Found — market or resource does not exist                          |
| `429`       | Too Many Requests — rate limit exceeded                                |
| `500`       | Internal Server Error                                                  |
| `502`       | Bad Gateway — upstream platform (e.g., Polymarket CLOB) is unavailable |

Error response body:

```json theme={null}
{
  "error": "Missing required parameter: marketId",
  "statusCode": 400
}
```