Markets

The Markets API provides access to prediction market data, including market listings with filtering and pagination options.

Get Markets List

Retrieve a paginated list of markets with filtering options.

Get list of markets (paginated, status=live, sorted by createdAt, supports partial name search via ?search=)

get

Query parameters

contractAddressstringOptional

Filter by contract address

Example: 0x1, 0x2

pagestringOptional

Page number

Default: 1Example: 1Pattern: ^\d+$

pageSizestringOptional

Page size

Default: 20Example: 20Pattern: ^\d+$

sortstring · enumOptional

Sort by createdAt

Default: descExample: descPossible values:

statusstringOptional

Comma-separated list of statuses (e.g. live,approved,closed)

Default: live,approvedExample: live,approved

searchstring · min: 1 · max: 100Optional

Partial name search for market (case-insensitive, matches any part of the name)

Responses

200

List of markets

application/json

Paginated list of markets

totalnumberRequiredExample: 100

pagenumberRequiredExample: 1

pageSizenumberRequiredExample: 20

400

Bad request

application/json

500

Internal server error

application/json

get

/api/v1/markets

HTTPcURLJavaScriptPython

GET /api/v1/markets HTTP/1.1
Accept: */*

{
  "items": [
    {
      "id": "market-uuid",
      "name": "Market Name",
      "slug": "market-name",
      "categoryId": "text",
      "type": "text",
      "rules": "text",
      "status": "text",
      "tradingStatus": "text",
      "expiresAt": "2024-08-05T12:00:00Z",
      "contractAddress": "text",
      "volume": "text",
      "views": "text",
      "coverImageUrl": "text",
      "createdAt": "2024-08-05T12:00:00Z",
      "fillPrice": "text",
      "isDeleted": false,
      "isPauseOrder": false,
      "outcomes": [
        {
          "id": "outcome-uuid",
          "name": "Yes",
          "volume": 1,
          "lastPrice": 1,
          "positionId": "text",
          "fillPrice": 1
        }
      ]
    }
  ],
  "total": 100,
  "page": 1,
  "pageSize": 20
}

Get Market Detail

Retrieve detailed information about a specific market by its ID.

Get market detail by marketId

get

Path parameters

marketIdstringRequired

Market ID

Example: market-uuid

Query parameters

contractAddressstringOptional

Filter by contract address

Example: 0x1, 0x2

Responses

200

Market detail

application/json

Market detail

idstringRequiredExample: market-uuid

namestringRequiredExample: Market Name

slugstringRequiredExample: market-name

categoryIdstring · nullableOptional

typestringRequired

rulesstringRequired

statusstringRequired

tradingStatusstring · nullableOptional

expiresAtstringRequiredExample: 2024-08-05T12:00:00Z

contractAddressstring · nullableOptional

volumestring · nullableOptional

viewsstring · nullableOptional

coverImageUrlstring · nullableOptional

createdAtstringRequiredExample: 2024-08-05T12:00:00Z

fillPricestring · nullableOptional

isDeletedboolean · nullableOptionalExample: false

isPauseOrderboolean · nullableOptionalExample: false

400

Bad request

application/json

404

Market not found

application/json

500

Internal server error

application/json

get

/api/v1/markets/{marketId}

HTTPcURLJavaScriptPython

GET /api/v1/markets/{marketId} HTTP/1.1
Accept: */*

{
  "id": "market-uuid",
  "name": "Market Name",
  "slug": "market-name",
  "categoryId": "text",
  "type": "text",
  "rules": "text",
  "status": "text",
  "tradingStatus": "text",
  "expiresAt": "2024-08-05T12:00:00Z",
  "contractAddress": "text",
  "volume": "text",
  "views": "text",
  "coverImageUrl": "text",
  "createdAt": "2024-08-05T12:00:00Z",
  "fillPrice": "text",
  "isDeleted": false,
  "isPauseOrder": false,
  "outcomes": [
    {
      "id": "outcome-uuid",
      "name": "Yes",
      "volume": 1,
      "lastPrice": 1,
      "positionId": "text",
      "fillPrice": 1
    }
  ]
}

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