跳至主要内容

訂單

創建訂單​

喺訂單簿中創建新訂單。

端點： POST /openapi/v1/order

請求主體：

欄位類型描述
outcomeIdstring要交易嘅結果
sidestringbuy 或 sell
typestringlimit 或 market
pricenumber0 同 1 之間嘅價格（限價訂單）
quantitynumber股份數量

驗證​

所有訂單操作都需要喺 x-api-key 標頭中使用你嘅 API 密鑰進行驗證：

x-api-key: YOUR_API_KEY

批量創建訂單​

端點： POST /openapi/v1/order/batch

喺單個請求中創建多個訂單以提升效能。

取消訂單​

取消現有嘅未成交訂單。

端點： DELETE /openapi/v1/order/{orderId}

取消所有訂單​

取消特定市場嘅所有未成交訂單。

端點： DELETE /openapi/v1/order/cancel-all/{marketId}

批量取消訂單​

喺單個請求中通過訂單 ID 批量取消多個訂單。

端點： POST /openapi/v1/order/cancel-batch

獲取我嘅訂單​

獲取你嘅訂單，支持分頁同篩選選項。

端點： GET /openapi/v1/order/my-orders

獲取市場訂單​

獲取特定市場嘅所有訂單，按狀態篩選同分頁。

端點： GET /openapi/v1/order/market/{marketId}

訂單類型​

限價訂單​

  • 以指定價格或更好嘅價格執行
  • 可能唔會即時成交
  • 為市場提供流動性

市價訂單​

  • 以最佳可用價格即時執行
  • 保證成交（如果有流動性）
  • 從市場獲取流動性

訂單狀態​

訂單可以有以下狀態：

狀態描述
open訂單活躍中，等待成交
partially_filled部分數量已成交
filled訂單完全執行
cancelled用戶已取消訂單
expired訂單根據 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(`訂單創建失敗: ${response.status}`);
  }

  return await response.json();
}

// 範例：以 0.65 價格買入 100 股
const order = await createLimitOrder('outcome-uuid', 'buy', 0.65, 100);
console.log(`訂單已創建: ${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(`批量訂單創建失敗: ${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(`已創建 ${result.orders.length} 個訂單`);

批量取消訂單​

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(`批量取消失敗: ${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['id']}")

# 監控訂單狀態
time.sleep(2)
orders = get_my_orders(status='open')
print(f"未成交訂單: {orders['total']}")

最佳實踐​

  1. 訂單驗證：喺提交前驗證訂單參數
  2. 批量操作：創建/取消多個訂單時使用批量端點
  3. 錯誤處理：為所有 API 調用實施穩健嘅錯誤處理
  4. 速率限制：遵守 API 速率限制以避免被節流
  5. 訂單管理：追蹤你嘅未成交訂單並取消過時嘅訂單
  6. 價格檢查：驗證價格喺有效範圍內（0 < 價格 < 1）
  7. 簽名安全：永遠唔好暴露你嘅私鑰；安全咁簽署訂單
  8. 冪等性：考慮為訂單創建實施冪等性以防止重複

效能優化​

  • 落多個訂單時使用批量創建嚟減少 API 調用
  • 使用批量取消嚟高效關閉多個持倉
  • 輪詢 my-orders 端點而唔係逐個檢查訂單狀態
  • 緩存市場數據以喺提交前驗證訂單

相關文檔​