Prediction Hunt API

https://www.predictionhunt.com/api/docs
Admin
Prediction Hunt API unifies fragmented prediction markets by providing standardized market data from...
Tokens:30,572
Snippets:237
Trust Score:5.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Quick Start Example

Source: https://www.predictionhunt.com/api/docs/websocket

Connect to the WebSocket API, authenticate with an API key, and subscribe to price updates for specific market IDs.

```APIDOC
## Quick Start
Connect with your API key (query string or first-frame auth), then send `subscribe` messages for the channels you need. Messages arrive as JSON with a consistent envelope.

```python
import asyncio, json, websockets, os

async def main():
    uri = "wss://ws.predictionhunt.com?api_key=" + os.environ["PREDICTION_HUNT_API_KEY"]
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "action": "subscribe",
            "channel": "prices",
            "market_ids": ["12345", "67890"]
        }))
        async for message in ws:
            data = json.loads(message)
            print(data.get("channel"), data.get("type"), data)

asyncio.run(main())
```
```

--------------------------------

### GET /v2/arb Request Example

Source: https://www.predictionhunt.com/api/docs/v2/arb

Example cURL request to the arbitrage endpoint. Includes parameters for minimum ROI and limit, and specifies the API key header.

```bash
curl --request GET \
  --url 'https://www.predictionhunt.com/api/v2/arb?min_roi=0.5&limit=3' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_API_KEY'
```

--------------------------------

### Fade Finder Update Example

Source: https://www.predictionhunt.com/api/docs/websocket/channels/fade-finder

Example of a fade_finder_update message received from the server. This message includes details about profitable and losing wallet activity, market information, and signal payload.

```json
{
  "channel": "fade_finder",
  "type": "fade_finder_update",
  "ts": 1712847605.5,
  "data": {
    "type": "fade_finder_update",
    "version": 1,
    "event_id": 12,
    "group_id": 101,
    "market_slug": "example-market",
    "title": "Election market title",
    "description": "Profitable wallet ($180.0K) bets YES while losing wallet (-$75.0K) bets NO",
    "created_at": "2026-04-24T18:21:11.000000+00:00",
    "data": {
      "marketSlug": "example-market",
      "profitable_wallet_count": 3,
      "time_delta_min": 6.3,
      "resolution_date": "2026-11-05",
      "profitable_wallet": {
        "userAddr": "0xwallet...",
        "pnl_to_date": 180000.0,
        "outcome": "YES",
        "side": "BUY",
        "price": 0.47,
        "amount": 1800.0
      },
      "losing_wallet": {
        "userAddr": "0xloser...",
        "pnl_to_date": -75000.0,
        "outcome": "NO",
        "side": "BUY",
        "price": 0.53,
        "amount": 1000.0
      }
    }
  }
}
```

--------------------------------

### Subscribed Message Example

Source: https://www.predictionhunt.com/api/docs/websocket

Example of a server response confirming a successful subscription to a channel.

```APIDOC
subscribed
```json
{
  "type": "subscribed",
  "channel": "prices",
  "market_ids": ["12345"],
  "group_ids": null
}
```
```

--------------------------------

### API Response Example for Events

Source: https://www.predictionhunt.com/api/docs/quickstart

This is an example of the JSON response structure for the `/v2/events` endpoint, showing details of a prediction market event. Use `next_cursor` for pagination and `group_count` to see cross-platform matches.

```json
{
"events": [
{
"id": "evt_pres_2028",
"event_name": "2028 Presidential Election Winner",
"event_type": "politics",
"event_date": "2028-11-07",
"status": "active",
"group_count": 5,
"platforms": ["kalshi", "polymarket", "predictit"]
}
{
...
}
],
"next_cursor": "eyJpZCI6MTIzfQ==",
"total_count": 1847
}
```

--------------------------------

### GET /v2/matching-markets cURL Request

Source: https://www.predictionhunt.com/api/docs/v2/matching-markets

Example cURL request to the Matching Markets API using a free-text query and an API key. Ensure to replace 'YOUR_API_KEY' with your actual key.

```curl
curl --request GET \
  --url 'https://www.predictionhunt.com/api/v2/matching-markets?q=federal+reserve' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_API_KEY'
```

--------------------------------

### Error Message Example

Source: https://www.predictionhunt.com/api/docs/websocket

Example of an error message returned by the server, indicating a subscription issue.

```APIDOC
error
```json
{
  "type": "error",
  "code": "CHANNEL_FORBIDDEN",
  "message": "Your tier does not have access to the arb channel.",
  "channel": "arb"
}
```
```

--------------------------------

### GET /v2/matching-markets/url

Source: https://www.predictionhunt.com/api/docs/v2/matching-markets-url

Retrieves matching markets based on a provided URL. The platform is auto-detected from the URL hostname.

```APIDOC
## GET /v2/matching-markets/url

### Description
Find matching markets by providing a URL from any supported platform. The platform is auto-detected from the URL hostname.

### Method
GET

### Endpoint
`/v2/matching-markets/url`

### Parameters
#### Query Parameters
- **url** (string) - Required - Full URL from any supported platform (Polymarket, Kalshi, PredictIt, ProphetX, Opinion, Predict.fun).

### Request Example
```curl
curl --request GET \
  --url 'https://www.predictionhunt.com/api/v2/matching-markets/url?url=https%3A%2F%2Fpolymarket.com%2Fmarket%2Fwill-the-next-prime-minister-of-hungary-be-pter-magyar' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### Response
#### Success Response (200)
- **success** (boolean) - Whether matching events were found.
- **count** (integer) - Number of matching events returned.
- **events** (object[]) - Matched events with cross-platform market groups.
  - **title** (string) - Event name.
  - **event_type** (string) - Category: economics, sports, election, etc.
  - **event_date** (string) - Date of the event.
  - **confidence** (string) - Match confidence: "high" or "medium".
  - **groups** (object[]) - Market groups within this event.
    - **title** (string) - Group title.
    - **markets** (object[]) - Matched markets: source, source_url, id.

```

--------------------------------

### Python WebSocket Connection with API Key

Source: https://www.predictionhunt.com/api/docs/websocket/authentication

Example of establishing a WebSocket connection in Python, including the API key in the connection URL for authentication.

```python
import websockets

async with websockets.connect(
    "wss://ws.predictionhunt.com?api_key=" + api_key
) as ws:
    # authenticated — send subscribe messages
    ...
```

--------------------------------

### List All Events

Source: https://www.predictionhunt.com/api/docs

Retrieve a list of all available events by making a GET request to the /api/v2/events endpoint. Authentication is handled via the X-API-Key header.

```bash
curl -H "X-API-Key: YOUR_API_KEY" https://www.predictionhunt.com/api/v2/events
```

--------------------------------

### Receive Price Update

Source: https://www.predictionhunt.com/api/docs/websocket/channels/prices

Example of a price update message received from the server. Includes market details, bid/ask prices, last trade, and volume.

```json
{
  "channel": "prices",
  "type": "price_update",
  "ts": 1712847600.123,
  "data": {
    "type": "price_update",
    "market_id": "12345",
    "source": "kalshi",
    "group_id": 101,
    "yes_bid": 0.65,
    "yes_ask": 0.67,
    "no_bid": 0.33,
    "no_ask": 0.35,
    "last_price": 0.66,
    "volume": 15000,
    "ts": 1712847600.123
  }
}
```

--------------------------------

### Receive Orderbook Update

Source: https://www.predictionhunt.com/api/docs/websocket/channels/orderbook

Example of an orderbook update message received from the server. This includes market details, source, and bid/ask prices.

```json
{
  "channel": "orderbook",
  "type": "orderbook_update",
  "ts": 1712847603.0,
  "data": {
    "type": "orderbook_update",
    "market_id": "12345",
    "source": "kalshi",
    "yes": { "bid": 0.64, "ask": 0.66 },
    "no": { "bid": 0.34, "ask": 0.36 }
  }
}
```

--------------------------------

### API Key Format

Source: https://www.predictionhunt.com/api/docs/authentication

API keys are prefixed with `pmx_` and tied to your account and plan tier. Get a free key instantly on the API docs landing page.

```text
pmx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

--------------------------------

### Find Markets by URL using cURL

Source: https://www.predictionhunt.com/api/docs/v2/matching-markets-url

Use this cURL command to make a GET request to the matching markets endpoint. Include your API key in the X-API-Key header for secure authentication. The 'url' parameter should be the full URL of the market you want to find matches for.

```curl
curl --request GET \
  --url 'https://www.predictionhunt.com/api/v2/matching-markets/url?url=https%3A%2F%2Fpolymarket.com%2Fmarket%2Fwill-the-next-prime-minister-of-hungary-be-pter-magyar' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_API_KEY'
```

--------------------------------

### Receive Arbitrage Update

Source: https://www.predictionhunt.com/api/docs/websocket/channels/arb

Example of a server-sent message for an arbitrage update. Includes details like group ID, profit percentage, and leg prices.

```json
{
  "channel": "arb",
  "type": "arb_update",
  "ts": 1712847601.842,
  "data": {
    "type": "arb_update",
    "group_id": 101,
    "profit_pct": 3.42,
    "yes_price": 0.61,
    "no_price": 0.36,
    "yes_src": "kalshi",
    "no_src": "polymarket"
  }
}
```

--------------------------------

### Subscribed Confirmation Message

Source: https://www.predictionhunt.com/api/docs/websocket

Example of a server response confirming a successful subscription to a channel.

```json
{
  "type": "subscribed",
  "channel": "prices",
  "market_ids": ["12345"],
  "group_ids": null
}
```

--------------------------------

### Arbitrage Signals

Source: https://www.predictionhunt.com/api/docs/quickstart

Get live arbitrage opportunities across all matched platforms. Available for Dev/Pro tiers.

```APIDOC
## GET /v2/arb

### Description
Provides real-time arbitrage opportunities identified across matched prediction markets on various platforms. This endpoint is typically available for Developer and Professional API tiers.

### Method
GET

### Endpoint
/v2/arb

### Parameters
(Specific parameters for this endpoint are not detailed in the provided text.)
```

--------------------------------

### Unified Orderbook Request Example

Source: https://www.predictionhunt.com/api/docs/v2/unified-orderbook

This cURL command demonstrates how to fetch the unified orderbook for a specific market match group. Ensure you replace 'YOUR_API_KEY' with your actual Prediction Hunt API key and '726' with the desired group ID.

```bash
curl --request GET \
  --url 'https://www.predictionhunt.com/api/v2/unified-orderbook?group_id=726' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_API_KEY'
```

--------------------------------

### Exponential Backoff for 429 Responses (Python)

Source: https://www.predictionhunt.com/api/docs/rate-limits

Implement exponential backoff when a 429 'Too Many Requests' error is received. This example uses the `requests` library and respects the `Retry-After` header.

```python
import time, requests

def call_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        resp = requests.get(url, headers=headers)
        if resp.status_code == 429:
            wait = int(resp.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait)
            continue
        resp.raise_for_status()
        return resp.json()
    raise Exception("Max retries exceeded")
```

--------------------------------

### Receive Arbitrage Updates

Source: https://www.predictionhunt.com/api/docs/websocket/channels/arb

This snippet shows an example of a message received from the Arbitrage WebSocket channel. It includes the channel, type, timestamp, and detailed data about the arbitrage opportunity.

```APIDOC
## Receive

### Description
Example of a message received from the arbitrage channel, indicating an update to an arbitrage opportunity.

### Data fields (inside data)
Field| Type| Description
---|---|---
**type** (string) - arb_update or arb_expired.
**group_id** (number) - Match group id.
**profit_pct / roi** (number?) - When present on updates from the worker.
**yes_price / no_price** (number?) - Leg prices when present.
**yes_src / no_src** (string?) - Venues for each leg when present.

### Response Example
```json
{
  "channel": "arb",
  "type": "arb_update",
  "ts": 1712847601.842,
  "data": {
    "type": "arb_update",
    "group_id": 101,
    "profit_pct": 3.42,
    "yes_price": 0.61,
    "no_price": 0.36,
    "yes_src": "kalshi",
    "no_src": "polymarket"
  }
}
```
```

--------------------------------

### Get Orderbook Data

Source: https://www.predictionhunt.com/api/docs/v2/orderbook

Retrieves the full bid and ask orderbook for a specified market on a supported platform. Returns 404 if no orderbook data is available.

```APIDOC
## GET /v2/orderbook

### Description
Retrieves the full bid and ask orderbook for a specified market on a supported platform. Returns 404 if no orderbook data is available.

### Method
GET

### Endpoint
`/v2/orderbook`

### Parameters
#### Query Parameters
- **platform** (string) - Required - The platform to retrieve orderbook data from. Supported values: `polymarket`, `kalshi`, `opinion`.
- **market_id** (string) - Required - The platform-native market ID.

### Request Example
```json
{
  "example": "curl --request GET \n  --url 'https://www.predictionhunt.com/api/v2/orderbook?platform=kalshi&market_id=KXPRESPERSON-28-GNEWS' \n  --header 'Accept: application/json' \n  --header 'X-API-Key: YOUR_API_KEY'"
}
```

### Response
#### Success Response (200)
- **market_id** (string) - Platform-native market ID.
- **platform** (string) - Platform name.
- **timestamp** (string) - Timestamp of the orderbook snapshot (ISO 8601).
- **yes** (object) - YES outcome orderbook.
  - **bids** (object[]) - Bid levels.
    - **price** (number) - Price level.
    - **size** (number) - Size/quantity at this level.
  - **asks** (object[]) - Ask levels.
    - **price** (number) - Price level.
    - **size** (number) - Size/quantity at this level.
- **no** (object) - NO outcome orderbook.
  - **bids** (object[]) - Bid levels.
    - **price** (number) - Price level.
    - **size** (number) - Size/quantity at this level.
  - **asks** (object[]) - Ask levels.
    - **price** (number) - Price level.
    - **size** (number) - Size/quantity at this level.

#### Response Example
```json
{
  "example": "{\"market_id\": \"KXPRESPERSON-28-GNEWS\", \"platform\": \"kalshi\", \"timestamp\": \"2023-10-27T10:00:00Z\", \"yes\": { \"bids\": [ { \"price\": 0.85, \"size\": 100 } ], \"asks\": [ { \"price\": 0.90, \"size\": 50 } ] }, \"no\": { \"bids\": [ { \"price\": 0.10, \"size\": 75 } ], \"asks\": [ { \"price\": 0.15, \"size\": 120 } ] }}"
}
```
```

--------------------------------

### GET /v2/markets

Source: https://www.predictionhunt.com/api/docs/v2/markets

Retrieves a paginated list of markets with optional filtering. The response includes market details, latest price data, and a cursor for subsequent pagination. API key authentication is recommended via the `X-API-Key` header.

```APIDOC
## GET /v2/markets

### Description
Browse and search all markets across platforms. Paginated by internal market id (stable order). Each market includes its latest price data. Pagination cursors are tied to the exact filter set: reuse next_cursor only with the same platform, status, category, and q parameters.

### Method
GET

### Endpoint
`/v2/markets`

### Parameters
#### Query Parameters
- **platform** (string) - Optional - Filter by platform: polymarket, kalshi, predictit, prophetx, opinion, predictfun (lowercase).
- **status** (string) - Optional - Market status: active, closed, or all. Default: active.
- **category** (string) - Optional - Category filter (e.g. 'sports', 'politics', 'economics').
- **q** (string) - Optional - Full-text search on market title.
- **limit** (integer) - Optional - Results per page. Default: 50, max: 500.
- **cursor** (string) - Optional - Opaque cursor from a previous response. Must match the same filters (platform, status, category, q) as that response; otherwise the API returns 400.

### Response
#### Success Response (200)
- **markets** (object[]) - List of markets matching the filters.
  - **id** (integer) - Internal market ID.
  - **market_id** (string) - Platform-native market identifier.
  - **platform** (string) - Source platform (polymarket, kalshi, etc.).
  - **title** (string) - Market title / question.
  - **category** (string) - Market category (sports, politics, economics, etc.).
  - **status** (string) - Market status (active, closed).
  - **expiration_date** (string) - ISO 8601 expiration timestamp.
  - **source_url** (string) - Direct link to the market on the platform.
  - **price** (object) - Latest price snapshot for this market.
    - **yes_bid** (number) - Best bid for YES.
    - **yes_ask** (number) - Best ask for YES.
    - **no_bid** (number) - Best bid for NO.
    - **no_ask** (number) - Best ask for NO.
    - **last_price** (number) - Last traded price.
    - **volume** (integer) - Trading volume.
    - **liquidity** (number) - Current liquidity (USD).
  - **next_cursor** (string | null) - Opaque cursor for the next page (null if none). Must be reused only with the same platform, status, category, and search query as the request that produced it; changing filters requires omitting the cursor and starting from the first page.
  - **total_count** (integer | null) - Total number of markets matching the filters (across all pages). Null when no platform, category, or search query is applied (unfiltered count is omitted to avoid expensive full-table scans).

### Request Example
```json
{
  "example": "curl --request GET \n  --url 'https://www.predictionhunt.com/api/v2/markets?platform=polymarket&status=active&limit=5' \n  --header 'Accept: application/json' \n  --header 'X-API-Key: YOUR_API_KEY'"
}
```

### Response Example
```json
{
  "example": "{\n  \"markets\": [\n    {\n      \"id\": 123,\n      \"market_id\": \"poly_abc123\",\n      \"platform\": \"polymarket\",\n      \"title\": \"Will the US stock market reach a new all-time high in 2024?\",\n      \"category\": \"finance\",\n      \"status\": \"active\",\n      \"expiration_date\": \"2025-01-01T00:00:00Z\",\n      \"source_url\": \"https://polymarket.com/market/example-market\",\n      \"price\": {\n        \"yes_bid\": 0.65,\n        \"yes_ask\": 0.67,\n        \"no_bid\": 0.33,\n        \"no_ask\": 0.35,\n        \"last_price\": 0.66,\n        \"volume\": 15000,\n        \"liquidity\": 9750\n      },\n      \"next_cursor\": \"some_opaque_cursor_string\",\n      \"total_count\": 500\n    }\n  ]\n}"
}
```

### API Key
To secure your requests, we strongly recommend passing your API key via the `X-API-Key` header. This prevents sensitive keys from being exposed in access logs or browser history.
Request Header`X-API-Key: pmx_test_5e8f...`

### Rate Limits
API rate limits are enforced based on the tier associated with your API key. Limits are tracked on two dimensions: **requests per second** and **requests per month**. Each completed request counts toward the **global** monthly quota.
Usage is returned on responses via headers such as:
Response Headers (global)`X-RateLimit-Limit-Second: 10``X-RateLimit-Remaining-Second: 9``X-RateLimit-Limit-Month: 1000``X-RateLimit-Remaining-Month: 842`
If you exceed a rate limit, the API returns a `429` status with a `Retry-After` header indicating when you can resume.
```

--------------------------------

### GET /v2/matching-markets

Source: https://www.predictionhunt.com/api/docs/v2/matching-markets

Retrieves a list of matching prediction markets based on a provided query. You can search using a free-text query, a Polymarket slug, or a Kalshi ticker. Ensure you provide only one of these search parameters.

```APIDOC
## GET /v2/matching-markets

### Description
Find equivalent markets across all supported prediction market platforms using a free-text query, Polymarket slug, or Kalshi ticker.

### Method
GET

### Endpoint
`/v2/matching-markets`

### Parameters
#### Query Parameters
- **q** (string) - Required - Free-text search query (e.g. 'federal reserve rate'). Provide exactly one of q, polymarket_key, or kalshi_key.
- **polymarket_key** (string) - Required - Polymarket slug or identifier. Provide exactly one of q, polymarket_key, or kalshi_key.
- **kalshi_key** (string) - Required - Kalshi ticker. Provide exactly one of q, polymarket_key, or kalshi_key.

### Response
#### Success Response (200)
- **success** (boolean) - Whether matching events were found.
- **count** (integer) - Number of matching events returned.
- **events** (object[]) - Matched events with cross-platform market groups.
  - **title** (string) - Event name (e.g. "Will the Fed cut rates in March 2026?").
  - **event_type** (string) - Category: economics, sports, election, etc.
  - **event_date** (string) - Date of the event.
  - **confidence** (string) - Match confidence: "high" or "medium". Low-confidence events are excluded.
  - **groups** (object[]) - Market groups within this event.
    - **title** (string) - Group title (e.g. the specific proposition).
    - **markets** (object[]) - Matched markets across platforms.
      - **source** (string) - Platform (polymarket, kalshi, etc.).
      - **source_url** (string) - Direct link to the market.
      - **id** (string) - Platform-specific market identifier.

### Request Example
```curl
curl --request GET \
  --url 'https://www.predictionhunt.com/api/v2/matching-markets?q=federal+reserve' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### API Key
To secure your requests, we strongly recommend passing your API key via the `X-API-Key` header. This prevents sensitive keys from being exposed in access logs or browser history.
Request Header
`X-API-Key: pmx_test_5e8f...`

### Rate Limits
API rate limits are enforced based on the tier associated with your API key. Limits are tracked on two dimensions: **requests per second** and **requests per month**. Each completed request counts toward the **global** monthly quota.
Usage is returned on responses via headers such as:
Response Headers (global)
`X-RateLimit-Limit-Second: 10`
`X-RateLimit-Remaining-Second: 9`
`X-RateLimit-Limit-Month: 1000`
`X-RateLimit-Remaining-Month: 842`
If you exceed a rate limit, the API returns a `429` status with a `Retry-After` header indicating when you can resume.
```

--------------------------------

### Smart Money Update Data Structure

Source: https://www.predictionhunt.com/api/docs/websocket/channels/smart-money

Example of a smart_money_update message received from the server. This message contains details about whale activity, including transaction hash, amount, price, PnL, and outcome.

```json
{
  "channel": "smart_money",
  "type": "smart_money_update",
  "ts": 1712847604.5,
  "data": {
    "type": "smart_money_update",
    "version": 1,
    "subtype": "basic",
    "event_id": 12,
    "group_id": 101,
    "market_slug": "example-market",
    "title": "Election market title",
    "description": "BUY YES at 48.20¢ by wallet with $120.0K PnL",
    "created_at": "2026-04-24T18:20:31.000000+00:00",
    "data": {
      "txHash": "0xabc123...",
      "amount": 2400.25,
      "price": 0.482,
      "pnl_to_date": 120000.0,
      "userAddr": "0xwallet...",
      "outcome": "YES",
      "side": "BUY",
      "marketSlug": "example-market"
    }
  }
}
```

--------------------------------

### WebSocket Connection and Subscription Flow

Source: https://www.predictionhunt.com/api/docs/websocket/playground

This sequence demonstrates the command-line steps to open a WebSocket connection and send a subscription payload. Ensure you replace 'pmx_your_api_key_here' with your actual API key.

```bash
$ open websocket wss://ws.predictionhunt.com?api_key=pmx_your_api_key_here
← connected
$ send {"action":"subscribe","channel":"prices","market_ids":["KXCORPTAXCUT-27JAN01-21","KXBILLS-FISA"],"group_ids":[6149,17542]}
← subscribed
← streaming...
```

--------------------------------

### Search for Markets (DEMO)

Source: https://www.predictionhunt.com/api/docs

Use the /api/v2/search endpoint to find markets. The 'q' parameter accepts search terms. Live data is available on all tiers.

```bash
GET /api/v2/search?q=presidential election
```

--------------------------------

### Set Up Environment Variables

Source: https://www.predictionhunt.com/api/docs/quickstart

Store your API key and the Prediction Hunt API URL in environment variables to avoid hardcoding sensitive information in your source code.

```shell
PREDICTION_HUNT_API_KEY=your_api_key_here
PREDICTION_HUNT_API_URL=https://www.predictionhunt.com/api/v2
```

--------------------------------

### Header Authentication (Recommended)

Source: https://www.predictionhunt.com/api/docs/authentication

Pass your key in the `X-API-Key` request header. This is the recommended approach as the key never appears in server logs or browser history.

```bash
curl -H "X-API-Key: YOUR_API_KEY" \
  https://www.predictionhunt.com/api/v2/events
```

--------------------------------

### Connect and Subscribe to Prices (Python)

Source: https://www.predictionhunt.com/api/docs/websocket

Connects to the WebSocket API, authenticates using an API key, and subscribes to price updates for specified market IDs. Handles incoming messages and prints their content.

```python
import asyncio, json, websockets, os

async def main():
    uri = "wss://ws.predictionhunt.com?api_key=" + os.environ["PREDICTION_HUNT_API_KEY"]
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "action": "subscribe",
            "channel": "prices",
            "market_ids": ["12345", "67890"]
        }))
        async for message in ws:
            data = json.loads(message)
            print(data.get("channel"), data.get("type"), data)

asyncio.run(main())
```

--------------------------------

### GET /v2/matching-markets/sports

Source: https://www.predictionhunt.com/api/docs/v2/matching-markets-sports

Retrieves matched game markets for a specified sport and date. You can filter results by platform.

```APIDOC
## GET /v2/matching-markets/sports

### Description
Query matched game markets by sport and date. Returns all matched pairs for each game across all available platforms.

### Method
GET

### Endpoint
`/v2/matching-markets/sports`

### Parameters
#### Query Parameters
- **sport** (string) - Required - Sport code: nba, nhl, mlb, nfl, cfb, cbb, epl, ucl, laliga, bundesliga, ligue1, seriea, mls, ligamx, atp, wta, pga, and more. Use league codes for soccer (epl, mls, etc.), not 'soccer'. The alias football maps to nfl.
- **date** (string) - Optional - Date in YYYY-MM-DD format. Defaults to today.
- **platforms** (string) - Optional - Comma-separated list of platforms. Only return groups matching all listed platforms.

### Request Example
```json
{
  "example": "curl --request GET \n  --url 'https://www.predictionhunt.com/api/v2/matching-markets/sports?sport=nba' \n  --header 'Accept: application/json' \n  --header 'X-API-Key: YOUR_API_KEY'"
}
```

### Response
#### Success Response (200)
- **sport** (string) - The sport code that was queried.
- **date** (string) - The date that was queried (YYYY-MM-DD).
- **games** (object[]) - Matched games for the given sport and date.
  - **group_id** (integer) - Internal match group ID.
  - **game_title** (string) - Game title (e.g. "Lakers vs Celtics").
  - **event_date** (string) - Date of the game (YYYY-MM-DD).
  - **markets** (object[]) - Markets from each platform for this game.
    - **platform** (string) - Platform name (polymarket, kalshi, etc.).
    - **market_id** (string) - Platform-native market ID.
    - **source_url** (string) - Direct link to the market on the platform.
    - **yes_bid** (number) - Current best bid price for YES.
    - **yes_ask** (number) - Current best ask price for YES.
    - **last_price** (number) - Last traded price.

#### Response Example
```json
{
  "example": "{\"sport\":\"nba\",\"date\":\"2023-10-27\",\"games\":[{\"group_id\":123,\"game_title\":\"Lakers vs Celtics\",\"event_date\":\"2023-10-27\",\"markets\":[{\"platform\":\"polymarket\",\"market_id\":\"abc123xyz\",\"source_url\":\"https://www.polymarket.com/market/lakers-vs-celtics-next-game\",\"yes_bid\":0.75,\"yes_ask\":0.80,\"last_price\":0.78}]}]}"}
```

### API Key
To secure your requests, we strongly recommend passing your API key via the `X-API-Key` header. This prevents sensitive keys from being exposed in access logs or browser history.

Request Header
`X-API-Key: pmx_test_5e8f...`

### Rate Limits
API rate limits are enforced based on the tier associated with your API key. Limits are tracked on two dimensions: **requests per second** and **requests per month**. Each completed request counts toward the **global** monthly quota.

Usage is returned on responses via headers such as:

Response Headers (global)
`X-RateLimit-Limit-Second: 10`
`X-RateLimit-Remaining-Second: 9`
`X-RateLimit-Limit-Month: 1000`
`X-RateLimit-Remaining-Month: 842`

If you exceed a rate limit, the API returns a `429` status with a `Retry-After` header indicating when you can resume.
```

--------------------------------

### Fetch Bulk Market Prices with cURL

Source: https://www.predictionhunt.com/api/docs/v2/prices-bulk

Use this cURL command to request prices for multiple markets. Ensure you replace 'YOUR_API_KEY' with your actual API key and format the market IDs correctly.

```bash
curl --request GET \
  --url 'https://www.predictionhunt.com/api/v2/prices/bulk?ids=polymarket%3A32224%2Cpolymarket%3A32225%2Cpolymarket%3A561263' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_API_KEY'
```

--------------------------------

### Query Parameter Authentication (Alternative)

Source: https://www.predictionhunt.com/api/docs/authentication

Query parameters are convenient for quick browser tests but must not be used in production. The key appears in server access logs, proxy logs, and the browser's `Referer` header. Always use the `X-API-Key` header in any code that ships.

```bash
curl "https://www.predictionhunt.com/api/v2/events?api_key=YOUR_API_KEY"
```

--------------------------------

### Error Message for Forbidden Channel

Source: https://www.predictionhunt.com/api/docs/websocket

Example of a server response indicating that the subscribed channel is not accessible due to tier limitations.

```json
{
  "type": "error",
  "code": "CHANNEL_FORBIDDEN",
  "message": "Your tier does not have access to the arb channel.",
  "channel": "arb"
}
```

--------------------------------

### Get Arbitrage Opportunities

Source: https://www.predictionhunt.com/api/docs/v2/arb

Retrieves a list of arbitrage opportunities based on specified filters. Requires a Dev or Pro tier subscription.

```APIDOC
## GET /v2/arb

### Description
Retrieves cross-platform arbitrage opportunities. API response will include a 15-second signal delay. This endpoint is not available on the Free tier.

### Method
GET

### Endpoint
/v2/arb

### Parameters
#### Query Parameters
- **min_roi** (float) - Optional - Minimum ROI percentage to include. Default: 0.5.
- **platforms** (string) - Optional - Filter to specific platform pair, e.g. polymarket,kalshi.
- **limit** (integer) - Optional - Default: 20, max: 100.

### Response
#### Success Response (200)
- **as_of** (string) - Server timestamp of the response (ISO 8601).
- **delay_seconds** (integer) - Signal delay in seconds applied to the response.
- **count** (integer) - Number of opportunities returned.
- **opportunities** (object[]) - Current arbitrage opportunities.
  - **group_id** (integer) - Match group ID.
  - **group_title** (string) - Human-readable group title.
  - **event_date** (string) - Event date.
  - **event_type** (string) - Event category.
  - **roi_pct** (number) - Return on investment percentage.
  - **total_cost** (number) - Total cost to execute (YES price + NO price).
  - **detected_at** (string) - When this opportunity was detected (ISO 8601).
  - **legs** (object[]) - The two legs of the arbitrage trade.
    - **side** (string) - "yes" or "no".
    - **platform** (string) - Platform for this leg.
    - **market_id** (string) - Market ID on the platform.
    - **source_url** (string) - Direct link to the market.
    - **price** (number) - Price for this leg.
    - **liquidity_usd** (number) - Available liquidity in USD.

### Request Example
```json
{
  "example": "curl --request GET \n  --url 'https://www.predictionhunt.com/api/v2/arb?min_roi=0.5&limit=3' \n  --header 'Accept: application/json' \n  --header 'X-API-Key: YOUR_API_KEY'"
}
```

### API Key
To secure your requests, we strongly recommend passing your API key via the `X-API-Key` header. This prevents sensitive keys from being exposed in access logs or browser history.

### Rate Limits
API rate limits are enforced based on the tier associated with your API key. Limits are tracked on two dimensions: **requests per second** and **requests per month**. Each completed request counts toward the **global** monthly quota. Usage is returned on responses via headers such as:

Response Headers (global)
`X-RateLimit-Limit-Second: 10`
`X-RateLimit-Remaining-Second: 9`
`X-RateLimit-Limit-Month: 1000`
`X-RateLimit-Remaining-Month: 842`

If you exceed a rate limit, the API returns a `429` status with a `Retry-After` header indicating when you can resume.
```

--------------------------------

### Receive Market Resolved Event

Source: https://www.predictionhunt.com/api/docs/websocket/channels/lifecycle

Example of a data message received from the server when a market is resolved. Includes market details and resolution status.

```json
{
  "channel": "market_lifecycle",
  "type": "market_resolved",
  "ts": 1712847604.0,
  "data": {
    "type": "market_resolved",
    "market_id": "12345",
    "source": "kalshi",
    "resolution": "yes",
    "group_id": 101
  }
}
```

--------------------------------

### Get Unified Orderbook

Source: https://www.predictionhunt.com/api/docs/v2/unified-orderbook

Retrieves the unified orderbook for a specified market match group. The group_id is essential and can be obtained from other endpoints like /v2/matching-markets or /v2/events.

```APIDOC
## GET /v2/unified-orderbook

### Description
Retrieves the live unified orderbook for a market match group across all platforms. Aggregates bid/ask depth from Kalshi, Polymarket, and Opinion into a single combined view.

### Method
GET

### Endpoint
`/v2/unified-orderbook`

### Parameters
#### Query Parameters
- **group_id** (integer) - Required - Market match group ID. Get this from /v2/matching-markets, /v2/events, or /v2/search.
- **event_name** (string) - Optional - Event name for the matched group.
- **candidate** (string) - Optional - Candidate / group title.

### Request Header
- **X-API-Key** (string) - Required - Your API key for authentication.

### Request Example
```bash
curl --request GET \
  --url 'https://www.predictionhunt.com/api/v2/unified-orderbook?group_id=726' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### Response
#### Success Response (200)
- **platforms** (object) - Per-platform orderbook data.
  - **kalshi** (object) - Kalshi orderbook (if available).
    - **ticker / token_id** (string) - Platform-native identifier.
    - **market_id** (string) - Platform market ID.
    - **timestamp** (number) - Unix timestamp in milliseconds.
    - **bids** (array) - Bid levels [price, size], sorted descending.
      - **[0]** (number) - Price in cents (0-10000).
      - **[1]** (number) - Size (contracts) at this level.
    - **asks** (array) - Ask levels [price, size], sorted ascending.
      - **[0]** (number) - Price in cents (0-10000).
      - **[1]** (number) - Size (contracts) at this level.
  - **polymarket** (object) - Polymarket orderbook (if available).
    - **ticker / token_id** (string) - Platform-native identifier.
    - **market_id** (string) - Platform market ID.
    - **timestamp** (number) - Unix timestamp in milliseconds.
    - **bids** (array) - Bid levels [price, size], sorted descending.
      - **[0]** (number) - Price in cents (0-10000).
      - **[1]** (number) - Size (contracts) at this level.
    - **asks** (array) - Ask levels [price, size], sorted ascending.
      - **[0]** (number) - Price in cents (0-10000).
      - **[1]** (number) - Size (contracts) at this level.
  - **opinion** (object) - Opinion orderbook (if available).
    - **ticker / token_id** (string) - Platform-native identifier.
    - **market_id** (string) - Platform market ID.
    - **timestamp** (number) - Unix timestamp in milliseconds.
    - **bids** (array) - Bid levels [price, size], sorted descending.
      - **[0]** (number) - Price in cents (0-10000).
      - **[1]** (number) - Size (contracts) at this level.
    - **asks** (array) - Ask levels [price, size], sorted ascending.
      - **[0]** (number) - Price in cents (0-10000).
      - **[1]** (number) - Size (contracts) at this level.
- **combined** (object) - Unified orderbook aggregated across all platforms.
  - **bids** (array) - Aggregated bid levels across all platforms.
    - **[0]** (number) - Price in cents (0-10000).
    - **[1]** (number) - Size (contracts) at this level.
  - **asks** (array) - Aggregated ask levels across all platforms.
    - **[0]** (number) - Price in cents (0-10000).
    - **[1]** (number) - Size (contracts) at this level.

### Rate Limits
API rate limits are enforced based on the tier associated with your API key. Limits are tracked on two dimensions: **requests per second** and **requests per month**. Each completed request counts toward the **global** monthly quota.

Response Headers (global):
- **X-RateLimit-Limit-Second**: 10
- **X-RateLimit-Remaining-Second**: 9
- **X-RateLimit-Limit-Month**: 1000
- **X-RateLimit-Remaining-Month**: 842

If you exceed a rate limit, the API returns a `429` status with a `Retry-After` header indicating when you can resume.
```

--------------------------------

### API Key Format

Source: https://www.predictionhunt.com/api/docs/authentication

API keys are prefixed with `pmx_` and are tied to your account and plan tier. You can obtain a free key from the API docs landing page.

```APIDOC
## API Keys
Keys are prefixed with `pmx_` and tied to your account and plan tier. Get a free key instantly on the API docs landing page.
example key format
text
```
pmx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
```

--------------------------------

### Key Security Best Practices

Source: https://www.predictionhunt.com/api/docs/authentication

Essential guidelines for securely managing your API keys to prevent exposure and unauthorized access.

```APIDOC
## Key Security
  * Never embed your API key in client-side JavaScript — it will be visible in the browser.
  * Store it in an environment variable (e.g. PREDICTION_HUNT_API_KEY) and inject server-side.
  * Rotate immediately if you suspect it has been exposed.
  * Scope keys to the minimum required tier — don't use a Pro key for a Free-tier use case.
```

--------------------------------

### Get API Status

Source: https://www.predictionhunt.com/api/docs/v2/status

This endpoint returns the overall API status and detailed ingestion health for each platform. It is unauthenticated and provides real-time insights into data freshness.

```APIDOC
## GET /v2/status

### Description
Returns API status, ingestion health, and last-updated timestamps per platform.

### Method
GET

### Endpoint
/v2/status

### Parameters
#### Request Header
- **X-API-Key** (string) - Required - Your API key for authentication.

### Response
#### Success Response (200)
- **status** (string) - Overall API status ("ok").
- **platforms** (object) - Per-platform ingestion health.
  - **status** (string) - "ok" if updated within 30 minutes, "stale" otherwise.
  - **last_updated** (string) - Timestamp of the last successful data ingestion (ISO 8601).
  - **active_markets** (integer) - Number of active markets on this platform.

### Request Example
```curl
curl --request GET \
  --url https://www.predictionhunt.com/api/v2/status \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### Response Example
```json
{
  "status": "ok",
  "platforms": {
    "platform1": {
      "status": "ok",
      "last_updated": "2023-10-27T10:00:00Z",
      "active_markets": 150
    },
    "platform2": {
      "status": "stale",
      "last_updated": "2023-10-26T08:00:00Z",
      "active_markets": 120
    }
  }
}
```
```
Tokens:
Raw