> For the complete documentation index, see [llms.txt](https://docs.pretoke.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pretoke.xyz/api-reference/events-and-markets.md).

# Events & Markets

Read-only endpoints for browsing the event/market catalog.

{% hint style="success" %}
All endpoints in this section are **public** — no authentication required.
{% endhint %}

***

## GET /events

List events, optionally filtered by category, paginated.

### Query parameters

| Param      | Type   | Default | Description                                                                                  |
| ---------- | ------ | ------- | -------------------------------------------------------------------------------------------- |
| `category` | string | `all`   | One of: `Sports`, `Crypto`, `Politics`, `E-sports`, `Culture`, `Economics`, `Tech`, or `all` |
| `page`     | number | `1`     | Page number, ≥ 1                                                                             |
| `pageSize` | number | 20      | Items per page, 1–100                                                                        |
| `search`   | string | —       | Optional free-text filter                                                                    |

### Code examples

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://predict.pretoke.xyz/api/v1/events?category=Crypto&page=1&pageSize=10" \
  -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(
  'https://predict.pretoke.xyz/api/v1/events?category=Crypto&page=1&pageSize=10'
);
const { data, pagination } = await response.json();

data.forEach(event => {
  console.log(`${event.title} — Volume: $${event.volumeUsd}`);
});
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.get(
    "https://predict.pretoke.xyz/api/v1/events",
    params={"category": "Crypto", "page": 1, "pageSize": 10}
)

result = response.json()
for event in result["data"]:
    print(f"{event['title']} — Volume: ${event['volumeUsd']}")
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const axios = require('axios');

const { data: result } = await axios.get('https://predict.pretoke.xyz/api/v1/events', {
  params: { category: 'Crypto', page: 1, pageSize: 10 }
});

result.data.forEach(event => {
  console.log(`${event.title} — Volume: $${event.volumeUsd}`);
});
```

{% endtab %}
{% endtabs %}

### Response `200 OK`

```json
{
  "data": [
    {
      "id": "evt_01hz...",
      "externalEventId": "12345",
      "title": "Will Bitcoin close above $100k this week?",
      "subtitle": "BTC price milestone",
      "category": "Crypto",
      "subcategory": "Bitcoin",
      "imageUrl": "https://.../image.png",
      "volumeUsd": "184230.55",
      "isActive": true,
      "isLive": false,
      "beginAt": "2026-07-10T18:00:00Z",
      "tags": ["bitcoin", "crypto", "price"],
      "markets": []
    }
  ],
  "requestId": "...",
  "pagination": { "total": 128, "page": 1, "pageSize": 10, "hasNext": true }
}
```

{% hint style="info" %}
List responses do **not** include live buy/sell prices on nested markets — fetch `GET /events/:id` or `GET /markets/:id` for live prices.
{% endhint %}

***

## GET /events/search

Free-text search across events.

### Query parameters

| Param | Type   | Required | Description                    |
| ----- | ------ | -------- | ------------------------------ |
| `q`   | string | yes      | Search query, 1–200 characters |

### Code examples

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://predict.pretoke.xyz/api/v1/events/search?q=bitcoin" \
  -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(
  'https://predict.pretoke.xyz/api/v1/events/search?q=bitcoin'
);
const { data } = await response.json();
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get(
    "https://predict.pretoke.xyz/api/v1/events/search",
    params={"q": "bitcoin"}
)
events = response.json()["data"]
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const { data: result } = await axios.get(
  'https://predict.pretoke.xyz/api/v1/events/search',
  { params: { q: 'bitcoin' } }
);
```

{% endtab %}
{% endtabs %}

### Response

Same shape as `GET /events` (an `EventItem[]`).

***

## GET /events/:id

Fetch a single event with its markets enriched with **live** order-book prices.

### Code examples

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://predict.pretoke.xyz/api/v1/events/evt_01hz..."
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch('https://predict.pretoke.xyz/api/v1/events/evt_01hz...');
const { data: event } = await response.json();

event.markets.forEach(market => {
  console.log(`${market.title}: YES=${market.buyYesPrice} NO=${market.buyNoPrice}`);
});
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get("https://predict.pretoke.xyz/api/v1/events/evt_01hz...")
event = response.json()["data"]

for market in event["markets"]:
    print(f"{market['title']}: YES={market['buyYesPrice']} NO={market['buyNoPrice']}")
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const { data: result } = await axios.get('https://predict.pretoke.xyz/api/v1/events/evt_01hz...');
const event = result.data;
```

{% endtab %}
{% endtabs %}

### Response `200 OK`

```json
{
  "data": {
    "id": "evt_01hz...",
    "title": "Will the Fed cut rates in July?",
    "category": "Economics",
    "markets": [
      {
        "id": "mkt_01hz...",
        "title": "Fed cuts rates by 25bps",
        "status": "open",
        "result": null,
        "outcomes": ["YES", "NO"],
        "buyYesPrice": "0.63",
        "buyNoPrice": "0.39",
        "sellYesPrice": "0.61",
        "sellNoPrice": "0.37",
        "volume": "52310.00"
      }
    ]
  },
  "requestId": "..."
}
```

`market.status` is one of: `open`, `closed`, `resolved`, `resolution_failed`, `cancelled`.

***

## GET /markets/:id

Fetch a single market with live prices (same `MarketItem` shape as above, without the parent event wrapper). Cached for 5 seconds.

### Code examples

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://predict.pretoke.xyz/api/v1/markets/mkt_01hz..."
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch('https://predict.pretoke.xyz/api/v1/markets/mkt_01hz...');
const { data: market } = await response.json();
console.log(`YES: ${market.buyYesPrice}, NO: ${market.buyNoPrice}`);
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get("https://predict.pretoke.xyz/api/v1/markets/mkt_01hz...")
market = response.json()["data"]
print(f"YES: {market['buyYesPrice']}, NO: {market['buyNoPrice']}")
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const { data: result } = await axios.get('https://predict.pretoke.xyz/api/v1/markets/mkt_01hz...');
const market = result.data;
```

{% endtab %}
{% endtabs %}

***

## GET /markets/:id/orderbook

Order book snapshot (top 10 levels).

### Query parameters

| Param     | Type          | Default | Description                   |
| --------- | ------------- | ------- | ----------------------------- |
| `outcome` | `YES` \| `NO` | `YES`   | Which outcome's book to fetch |

### Code examples

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://predict.pretoke.xyz/api/v1/markets/mkt_01hz.../orderbook?outcome=YES"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(
  'https://predict.pretoke.xyz/api/v1/markets/mkt_01hz.../orderbook?outcome=YES'
);
const { data: book } = await response.json();
console.log('Best bid:', book.bids[0]);
console.log('Best ask:', book.asks[0]);
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get(
    "https://predict.pretoke.xyz/api/v1/markets/mkt_01hz.../orderbook",
    params={"outcome": "YES"}
)
book = response.json()["data"]
print(f"Best bid: {book['bids'][0]}")
print(f"Best ask: {book['asks'][0]}")
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const { data: result } = await axios.get(
  'https://predict.pretoke.xyz/api/v1/markets/mkt_01hz.../orderbook',
  { params: { outcome: 'YES' } }
);
const { bids, asks } = result.data;
```

{% endtab %}
{% endtabs %}

### Response `200 OK`

```json
{
  "data": {
    "bids": [{ "price": "0.62", "quantity": "150000000", "numOrders": 3 }],
    "asks": [{ "price": "0.64", "quantity": "80000000", "numOrders": 2 }]
  },
  "requestId": "..."
}
```

`price` is a 2-decimal string. `quantity` is micro-units (aggregated). `numOrders` is the count at that level.

***

## GET /markets/:id/price-history

OHLC candle data for charting.

### Query parameters

| Param      | Type                                  | Default | Description            |
| ---------- | ------------------------------------- | ------- | ---------------------- |
| `outcome`  | `YES` \| `NO`                         | `YES`   | Which outcome to chart |
| `interval` | `1H` \| `1D` \| `1W` \| `1M` \| `MAX` | `1D`    | Chart time range       |

### Code examples

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://predict.pretoke.xyz/api/v1/markets/mkt_01hz.../price-history?outcome=YES&interval=1D"
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get(
    "https://predict.pretoke.xyz/api/v1/markets/mkt_01hz.../price-history",
    params={"outcome": "YES", "interval": "1D"}
)
history = response.json()["data"]
print(f"Current price: {history['currentPrice']}")
print(f"24h change: {history['priceChangePercent']}%")
```

{% endtab %}
{% endtabs %}

### Response `200 OK`

```json
{
  "data": {
    "marketId": "mkt_01hz...",
    "outcome": "YES",
    "interval": "1D",
    "candles": [
      { "timestamp": "2026-07-05T00:00:00Z", "open": 0.58, "high": 0.65, "low": 0.55, "close": 0.63, "volume": 12000 }
    ],
    "currentPrice": 0.63,
    "priceChange": 0.05,
    "priceChangePercent": 8.6,
    "volume24h": 52310
  },
  "requestId": "..."
}
```

***

## POST /markets/:id/quote

{% hint style="warning" %}
**Auth required:** Yes
{% endhint %}

Get a price quote for a hypothetical trade without executing it.

### Request body

```json
{ "side": "BUY", "outcome": "YES", "quantity": "50000000" }
```

### Code examples

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST "https://predict.pretoke.xyz/api/v1/markets/mkt_01hz.../quote" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "side": "BUY", "outcome": "YES", "quantity": "50000000" }'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch('https://predict.pretoke.xyz/api/v1/markets/mkt_01hz.../quote', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ side: 'BUY', outcome: 'YES', quantity: '50000000' })
});
const { data: quote } = await response.json();
console.log(`Estimated cost: ${quote.estimatedCost}, Source: ${quote.source}`);
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.post(
    "https://predict.pretoke.xyz/api/v1/markets/mkt_01hz.../quote",
    headers={"Authorization": f"Bearer {access_token}"},
    json={"side": "BUY", "outcome": "YES", "quantity": "50000000"}
)
quote = response.json()["data"]
print(f"Cost: {quote['estimatedCost']}, Source: {quote['source']}")
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const { data: result } = await axios.post(
  'https://predict.pretoke.xyz/api/v1/markets/mkt_01hz.../quote',
  { side: 'BUY', outcome: 'YES', quantity: '50000000' },
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
console.log(result.data);
```

{% endtab %}
{% endtabs %}

### Response `200 OK`

```json
{
  "data": {
    "estimatedPrice": "0.635",
    "estimatedCost": "31750000",
    "source": "HYBRID",
    "fee": "158750"
  },
  "requestId": "..."
}
```

`source`: `AMM`, `CLOB`, or `HYBRID`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.pretoke.xyz/api-reference/events-and-markets.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.