Skip to main content
GET
/
api
/
events
List Markets (Events)
curl --request GET \
  --url https://api.example.com/api/events
{
  "events": [
    {
      "id": "<string>",
      "slug": "<string>",
      "title": "<string>",
      "icon_url": "<string>",
      "status": "<string>",
      "volume": 123,
      "created_at": "<string>",
      "end_date": "<string>",
      "markets": [
        {
          "condition_id": "<string>",
          "title": "<string>",
          "probability": 123,
          "price": 123,
          "volume": 123,
          "volume_24h": 123,
          "outcomes": [
            {
              "token_id": "<string>",
              "outcome_text": "<string>",
              "outcome_index": 123,
              "buy_price": 123,
              "sell_price": 123
            }
          ]
        }
      ],
      "tags": [
        {
          "id": 123,
          "name": "<string>",
          "slug": "<string>"
        }
      ],
      "is_bookmarked": true,
      "is_trending": true
    }
  ]
}

​
Overview

The /api/events endpoint returns a paginated list of prediction markets (events) with comprehensive filtering capabilities. Each event contains one or more markets with real-time pricing data, outcomes, and metadata.

​
Request

​
Query Parameters

​
tag
string
default:"trending"
Filter markets by category tag. Special tags include:
  • trending - Markets sorted by recent volume or recently updated
  • new - Recently created markets
  • Other tag slugs like crypto, sports, politics, etc.
​
search
string
Search term to filter markets by title. Supports multiple space-separated terms.
​
status
string
default:"active"
Filter by market status:
  • active - Currently open markets
  • resolved - Closed and settled markets
​
frequency
string
default:"all"
Filter by recurrence type:
  • all - All markets
  • daily - Daily recurring markets
  • weekly - Weekly recurring markets
  • monthly - Monthly recurring markets
​
bookmarked
boolean
default:"false"
Return only bookmarked markets (requires authentication).
​
sportsSportSlug
string
Filter by sports category slug (e.g., nfl, nba, soccer).
​
sportsSection
string
Filter sports markets by section:
  • games - Full game markets
  • props - Proposition bets
​
locale
string
default:"en"
Locale for internationalized content (e.g., en, es, fr).
​
offset
integer
default:"0"
Pagination offset for results. Returns up to 40 markets per request.

​
Response

​
events
array
Array of event objects, each containing one or more markets.
​
id
string
Unique event identifier (ULID format).
​
slug
string
URL-friendly event identifier.
​
title
string
Event title (localized if locale parameter provided).
​
icon_url
string
Full URL to the event icon image.
​
status
string
Event status: draft, active, resolved, or archived.
​
volume
number
Total trading volume across all markets in USDC.
​
created_at
string
ISO 8601 timestamp of event creation.
​
end_date
string
ISO 8601 timestamp when the event ends.
​
markets
array
Array of market objects within this event.
​
condition_id
string
Unique market identifier (blockchain condition ID).
​
title
string
Market question or title.
​
probability
number
Current probability percentage (0-100) for the primary outcome.
​
price
number
Current mid-price (0-1) for the primary outcome.
​
volume
number
Total trading volume for this market in USDC.
​
volume_24h
number
Trading volume in the last 24 hours in USDC.
​
outcomes
array
Array of possible outcomes for this market.
​
token_id
string
Unique token identifier for this outcome.
​
outcome_text
string
Outcome label (e.g., “Yes”, “No”).
​
outcome_index
number
Index of the outcome (0 for Yes, 1 for No in binary markets).
​
buy_price
number
Current buy price (0-1) from the order book.
​
sell_price
number
Current sell price (0-1) from the order book.
​
tags
array
Array of category tags associated with this event.
​
id
number
Tag identifier.
​
name
string
Tag display name (localized).
​
slug
string
Tag slug for filtering.
​
is_bookmarked
boolean
Whether the authenticated user has bookmarked this event.
​
is_trending
boolean
Whether the event has recent trading activity.

​
Example Request

cURL
curl --request GET \
  --url 'https://api.kuest.com/api/events?tag=crypto&status=active&offset=0' \
  --header 'Accept: application/json'
```bash

## Example Response

```json
[
  {
    "id": "01JBCDEFGHIJKLMNOPQRS",
    "slug": "bitcoin-price-above-100k",
    "title": "Will Bitcoin reach $100,000 by end of 2024?",
    "icon_url": "https://storage.kuest.com/icons/bitcoin.png",
    "status": "active",
    "volume": 125430.50,
    "created_at": "2024-01-15T10:30:00.000Z",
    "end_date": "2024-12-31T23:59:59.000Z",
    "markets": [
      {
        "condition_id": "0xabc123...",
        "title": "Bitcoin > $100k by EOY 2024",
        "probability": 65.5,
        "price": 0.655,
        "volume": 125430.50,
        "volume_24h": 8920.25,
        "outcomes": [
          {
            "token_id": "0xdef456...",
            "outcome_text": "Yes",
            "outcome_index": 0,
            "buy_price": 0.655,
            "sell_price": 0.650
          },
          {
            "token_id": "0xghi789...",
            "outcome_text": "No",
            "outcome_index": 1,
            "buy_price": 0.345,
            "sell_price": 0.340
          }
        ]
      }
    ],
    "tags": [
      {
        "id": 5,
        "name": "Crypto",
        "slug": "crypto"
      }
    ],
    "is_bookmarked": false,
    "is_trending": true
  }
]
```bash

## Error Responses

<ResponseField name="error" type="string">
  Error message describing what went wrong.
</ResponseField>

### 400 Bad Request

```json
{
  "error": "Invalid status filter."
}
```bash

Returned when:
- `status` is not `active` or `resolved`
- `frequency` is not one of: `all`, `daily`, `weekly`, `monthly`
- `sportsSection` is not `games`, `props`, or empty

### 500 Internal Server Error

```json
{
  "error": "An unexpected error occurred. Please try again later."
}
```bash

Returned when the server encounters an unexpected error.

## Notes

- The endpoint returns up to 40 markets per request. Use the `offset` parameter for pagination.
- Markets are sorted by volume and recency when using the `trending` tag.
- For the `new` tag, markets tagged with internal hide flags are automatically filtered out.
- Sports markets aggregate volume by game when multiple markets exist for the same game.
- Real-time prices are fetched from the CLOB (Central Limit Order Book) for all active markets.
- The `locale` parameter affects both event titles and tag names if translations are available.

Build docs developers (and LLMs) love

Get started for freeTalk to us