주문

Orders API를 통해 Xmarket 플랫폼에서 주문을 생성, 취소 및 관리할 수 있습니다.

주문 생성

오더북에 새 주문을 생성합니다.

인증

모든 주문 작업은 x-api-key 헤더에 API 키를 사용한 인증이 필요합니다:

x-api-key: YOUR_API_KEY

배치 주문 생성

주문 취소

기존의 오픈 주문을 취소합니다.

배치 주문들 생성

성능 향상을 위해 단일 요청으로 여러 주문을 생성합니다.

주문 취소

기존의 오픈 주문을 취소합니다.

모든 주문 취소

특정 마켓의 모든 오픈 주문을 취소합니다.

배치 주문 취소

단일 요청으로 주문 ID들로 여러 주문을 취소합니다.

내 주문 조회

페이징과 필터링 옵션으로 내 주문을 조회합니다.

마켓 주문 조회

상태로 필터링하고 페이징된 특정 마켓의 모든 주문을 조회합니다.

주문 유형

지정가 주문

• 특정 가격 또는 그보다 유리한 가격에서 체결

• 즉시 체결되지 않을 수 있음

• 마켓에 유동성 제공

마켓 주문

• 사용 가능한 최적가로 즉시 체결

• 유동성이 존재하면 체결이 보장됨

• 마켓에서 유동성 취하기

주문 상태

주문은 다음 상태를 가질 수 있습니다:

상태	설명
열려	주문이 활성화되어 체결을 기다리는 중
부분 체결됨	일부 수량이 체결됨
체결됨	주문이 완전히 실행됨
취소됨	사용자에 의해 주문이 취소됨
만료됨	expiredAt 시간에 따라 주문이 만료됨

코드 예제

지정가 주문 생성

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

async function createLimitOrder(outcomeId, side, price, quantity) {
  const orderData = {
    outcomeId: outcomeId,
    side: side, // 'buy' 또는 'sell'
    type: 'limit',
    price: price, // 0과 1 사이
    quantity: quantity
  };

  const response = await fetch(
    `${BASE_URL}/order`,
    {
      method: 'POST',
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(orderData)
    }
  );

  if (!response.ok) {
    throw new Error(`Order creation failed: ${response.status}`);
  }

  return await response.json();
}

// 예시: 가격 0.65에 100주 매수
const order = await createLimitOrder('outcome-uuid', 'buy', 0.65, 100);
console.log(`Order created: ${order.id}`);

배치 주문들 생성

async function batchCreateOrders(orders) {
  const response = await fetch(
    `${BASE_URL}/order/batch`,
    {
      method: 'POST',
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ orders })
    }
  );

  if (!response.ok) {
    throw new Error(`Batch order creation failed: ${response.status}`);
  }

  return await response.json();
}

// 한 번에 여러 주문 생성
const orders = [
  { outcomeId: 'outcome-1', side: 'buy', type: 'limit', price: 0.60, quantity: 50 },
  { outcomeId: 'outcome-2', side: 'buy', type: 'limit', price: 0.45, quantity: 75 },
  { outcomeId: 'outcome-3', side: 'sell', type: 'limit', price: 0.80, quantity: 100 }
];

const result = await batchCreateOrders(orders);
console.log(`Created ${result.orders.length} orders`);

여러 주문 취소

async function batchCancelOrders(orderIds) {
  const response = await fetch(
    `${BASE_URL}/order/cancel-batch`,
    {
      method: 'POST',
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ orderIds })
    }
  );

  if (!response.ok) {
    throw new Error(`Batch cancel failed: ${response.status}`);
  }

  return await response.json();
}

// 한 번에 여러 주문 취소
const orderIdsToCancel = ['order-id-1', 'order-id-2', 'order-id-3'];
await batchCancelOrders(orderIdsToCancel);
console.log('주문이 성공적으로 취소되었습니다');

마켓 주문 조회

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

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

// 특정 마켓의 모든 오픈 주문을 가져옵니다
const marketOrders = await getMarketOrders('market-uuid', 'open');
console.log(`마켓에서 ${marketOrders.length}개의 오픈 주문을 찾았습니다`);

Python 예제 - 주문 생성 및 모니터링

import requests
import time

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://engine.xmarket.app/openapi/v1'

def create_order(outcome_id, side, price, quantity, order_type='limit'):
    headers = {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
    }

    order_data = {
        'outcomeId': outcome_id,
        'side': side,
        'type': order_type,
        'price': price,
        'quantity': quantity
    }

    response = requests.post(
        f'{BASE_URL}/order',
        headers=headers,
        json=order_data
    )

    response.raise_for_status()
    return response.json()

def get_my_orders(status='all', page=1, page_size=50):
    headers = {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
    }

    params = {
        'status': status,
        'page': page,
        'pageSize': page_size
    }

    response = requests.get(
        f'{BASE_URL}/order/my-orders',
        headers=headers,
        params=params
    )

    response.raise_for_status()
    return response.json()

# 주문 생성
order = create_order('outcome-uuid', 'buy', 0.65, 100)
print(f"Order created: {order['id']}")

# 주문 상태 모니터링
time.sleep(2)
orders = get_my_orders(status='open')
print(f"오픈 주문: {orders['total']}")

모범 사례

1. 주문 검증: 제출 전에 항상 주문 파라미터를 검증하세요

2. 배치 작업: 여러 주문을 생성/취소할 때 배치 엔드포인트를 사용하세요

3. 오류 처리: 모든 API 호출에 대해 견고한 오류 처리를 구현하세요

4. 요율 제한: API 속도 제한을 준수하여 차단되는 것을 방지하세요

5. 주문 관리: 오픈 주문을 추적하고 오래된 주문을 취소하세요

6. 가격 확인: 가격이 유효 범위 내인지 확인하세요 (0 < price < 1)

7. 서명 보안: 개인 키를 절대 노출하지 마세요; 주문에 안전하게 서명하세요

8. 멱등성: 중복을 방지하기 위해 주문 생성에 멱등성 구현을 고려하세요

성능 최적화

• 사용 배치 생성 여러 주문을 할 때 API 호출을 줄이기 위해

• 사용 배치 취소 여러 포지션을 효율적으로 종료하기 위해

• 폴링 내-주문 개별 주문 상태 확인 대신 엔드포인트를 사용하세요

• 제출 전에 주문을 검증하기 위해 마켓 데이터를 캐시하세요

관련 문서

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

• 마켓 API - 주문하기 전에 마켓 정보를 가져오기

• 오더북 API - 주문하기 전에 현재 가격을 확인하기

• 포지션 API - 주문 체결 후 포지션을 추적하기