Markets

Get Markets List

Retrieve a paginated list of markets with filtering options.

Endpoint: GET /api/v1/markets

Query Parameters:

Parameter	Type	Description
status	string	Filter by market status (live, active, closed, disputing, resolved, resolution_proposed)
page	number	Page number for pagination
pageSize	number	Number of results per page

Get Market Detail

Retrieve detailed information about a specific market by its ID.

Endpoint: GET /api/v1/markets/{marketId}

Path Parameters:

Parameter	Type	Description
marketId	string	The unique market identifier

Market Status

Markets can have the following statuses:

Status	Description
live	Market is open for trading
active	Market is active but may have trading restrictions
closed	Market is closed for trading
disputing	Market resolution is being disputed
resolved	Market has been resolved
resolution_proposed	Resolution has been proposed, awaiting confirmation

Code Examples

Fetch Active Markets

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://engine.xmarket.app/api/v1';

async function getActiveMarkets() {
  const response = await fetch(
    `${BASE_URL}/markets?status=live&pageSize=50`,
    {
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  const data = await response.json();
  return data.items;
}

Get Market Detail

async function getMarketDetail(marketId) {
  const response = await fetch(
    `${BASE_URL}/markets/${marketId}`,
    {
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  if (!response.ok) {
    throw new Error(`Market not found: ${response.status}`);
  }

  const market = await response.json();
  console.log(`Market: ${market.name}`);
  console.log(`Status: ${market.status}`);
  console.log(`Outcomes: ${market.outcomes.length}`);
  return market;
}

// Example usage
const market = await getMarketDetail('market-uuid-here');

Filter Markets by Status

async function getMarketsByStatus(status) {
  const response = await fetch(
    `${BASE_URL}/markets?status=${status}&page=1&pageSize=100`,
    {
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  const data = await response.json();
  console.log(`Found ${data.total} ${status} markets`);
  return data.items;
}

// Get all resolved markets
const resolvedMarkets = await getMarketsByStatus('resolved');

// Get markets in dispute
const disputingMarkets = await getMarketsByStatus('disputing');

Best Practices

1. Caching: Cache market data appropriately as metadata doesn't change frequently
2. Pagination: Use pagination for large result sets to improve performance
3. Error Handling: Implement retry logic for transient network errors
4. Rate Limiting: Respect API rate limits (100 req/min, 20 req/sec burst)
5. Data Validation: Always validate market and outcome IDs before using them

Related Documentation

• Quick Start - Get started with the API
• Orderbook API - Get orderbook data for markets
• Orders API - Create and manage orders
• Positions API - Track your trading positions