List Markets (Events)

Retrieve a list of prediction markets with filtering, search, and categorization options

GET /api/events

List Markets (Events)

cURL

curl --request GET \
  --url https://api.example.com/api/events

200

{
  "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.