Skip to main content

​
Overview

The Kuest API provides programmatic access to prediction market data, trading operations, and user management. Built on Next.js API routes, it offers a RESTful interface for interacting with markets, placing orders, and managing positions.

​
Base URL

All API requests are made to: 
https://your-domain.com/api
For local development: 
http://localhost:3000/api

​
Available Endpoints

The API is organized into several categories:

​
Markets & Events

  • GET /api/events - List prediction markets and events
  • GET /api/events/[slug]/related - Get related events
  • GET /api/events/[slug]/market-metadata - Get market metadata
  • GET /api/markets/status - Check market resolution status
  • POST /api/markets/status - Batch check market status

​
Trading & Orders

  • GET /api/open-orders - Get user’s open orders
  • GET /api/event-activity - Get trading activity for a market
  • GET /api/holders - Get top position holders

​
User Management

  • GET /api/users - Search for users
  • GET /api/notifications - Get user notifications
  • PUT /api/notifications/[id] - Update notification status
  • GET /api/affiliate-info - Get affiliate information

​
Market Data

  • GET /api/price-reference/live-series - Get live price data
  • GET /api/sync/volume - Sync volume data
  • GET /api/sync/events - Sync event data

​
Response Format

All API responses return JSON with a consistent structure.

​
Success Response

{
  "data": [...],
  "next_cursor": "LTE="
}
Or simply the data array: 
[
  {
    "id": "event-123",
    "title": "Will Bitcoin reach $100k in 2026?",
    "status": "active"
  }
]

​
Error Response

{
  "error": "Error message describing what went wrong"
}
HTTP status codes indicate the type of error:
  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (authentication required)
  • 404 - Not Found
  • 500 - Internal Server Error

​
Rate Limits

API requests are subject to the following limits:
  • Public endpoints: No authentication required, general rate limiting applies
  • Authenticated endpoints: Require valid authentication headers
  • Batch endpoints: Limited to specific batch sizes (e.g., 500 condition IDs)
Rate limits are enforced at the infrastructure level. If you need higher limits for production use, contact support.

​
Pagination

Many list endpoints support pagination using offset-based pagination: 
GET /api/events?offset=0&limit=20
Parameters:
  • offset - Number of items to skip (default: 0)
  • limit - Maximum items to return (varies by endpoint, typically 10-50)
Some endpoints return a next_cursor for pagination: 
{
  "data": [...],
  "next_cursor": "eyJpZCI6MTIzfQ=="
}
Endpoints support various query parameters for filtering: 
GET /api/events?tag=politics&status=active

​
Common Parameters

ParameterTypeDescription
localestringLanguage code (e.g., en, es, default: en)
offsetintegerPagination offset (default: 0)
limitintegerResults per page (default varies by endpoint)
searchstringSearch query string
statusstringFilter by status: active, resolved

​
Error Codes

The API uses standard HTTP status codes:
CodeMeaningDescription
200OKRequest succeeded
400Bad RequestInvalid parameters or request format
401UnauthorizedAuthentication required or invalid
404Not FoundResource does not exist
500Internal Server ErrorServer error occurred

​
Common Error Messages

Bad Request
{
  "error": "Invalid status filter."
}
Unauthorized
{
  "error": "Unauthenticated."
}
Server Error
{
  "error": "Internal server error. Try again in a few moments."
}

​
Data Types

​
Micro Units

Monetary amounts and share quantities are represented in micro units (1/1,000,000): 
const MICRO_UNIT = 1_000_000

// $10.50 USDC
const amount = 10.5 * MICRO_UNIT // 10,500,000

// 100 shares
const shares = 100 * MICRO_UNIT // 100,000,000

​
Prices

Market prices are represented as decimals between 0 and 1:
  • 0.75 = 75% probability / 75¢ per share
  • 0.25 = 25% probability / 25¢ per share

​
Timestamps

All timestamps are ISO 8601 formatted strings: 
{
  "created_at": "2026-03-03T10:30:00.000Z",
  "updated_at": "2026-03-03T15:45:30.000Z"
}

​
Environment Variables

The API relies on several environment variables: 
# API Service URLs
CLOB_URL=https://clob.kuest.com
DATA_URL=https://data.kuest.com

# Authentication
BETTER_AUTH_SECRET=your-secret-key

# Trading Credentials
KUEST_ADDRESS=0x...
KUEST_API_KEY=your-api-key
KUEST_API_SECRET=your-api-secret
KUEST_PASSPHRASE=your-passphrase
See the Environment Variables guide for complete setup.

​
Next Steps

Authentication

Learn how to authenticate API requests

Markets API

Start querying market data

Trading API

Place and manage orders

Integration Guide

Build trading bots and integrations

Build docs developers (and LLMs) love

Get started for freeTalk to us