마켓들

Markets API는 필터링 및 페이지네이션 옵션을 포함한 예측 마켓 데이터, 마켓 목록에 대한 접근을 제공합니다.

마켓 목록 가져오기

필터 옵션을 사용하여 페이지네이션된 마켓 목록을 조회합니다.

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
}

마켓 상세 정보 가져오기

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
    }
  ]
}

마켓 상태

마켓은 다음과 같은 상태를 가질 수 있습니다:

상태	설명
라이브	마켓이 거래에 열려 있습니다
활성	마켓이 활성화되어 있지만 거래 제한이 있을 수 있습니다
마감됨	마켓이 거래에 대해 마감되었습니다
결과 처리 중	마켓 결과 처리가 이의 제기되고 있습니다
결과 처리 완료됨	마켓의 결과 처리가 완료되었습니다
결과 처리 제안됨	결과 처리가 제안되었으며 확인을 기다리고 있습니다

코드 예제

활성 마켓 가져오기

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;
}

마켓 상세 정보 가져오기

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;
}

// 사용 예시
const market = await getMarketDetail('market-uuid-here');

상태별 마켓 필터링

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;
}

// 모든 결과 처리 완료된 마켓 가져오기
const resolvedMarkets = await getMarketsByStatus('resolved');

// 이의 제기 중인 마켓 가져오기
const disputingMarkets = await getMarketsByStatus('disputing');

모범 사례

1. 캐싱: 메타데이터는 자주 변경되지 않으므로 마켓 데이터를 적절히 캐시하세요

2. 페이지네이션: 대량 결과 집합에는 성능 향상을 위해 페이지네이션을 사용하세요

3. 오류 처리: 일시적인 네트워크 오류에 대해 재시도 로직을 구현하세요

4. 요율 제한: API 요율 제한을 준수하세요 (분당 100회, 초당 버스트 20회)

5. 데이터 검증: 사용 전에 항상 마켓 및 결과 ID를 검증하세요

관련 문서

• 빠른 시작 - API로 시작하기

• 오더북 API - 마켓의 오더북 데이터를 가져옵니다

• 주문 API - 주문을 생성하고 관리합니다

• 포지션 API - 거래 포지션을 추적합니다