Orders

Create Order

Create a new order in orderbook.

Endpoint: POST /openapi/v1/order

Request Body:

Field	Type	Description
outcomeId	string	The outcome to trade
side	string	buy or sell
type	string	limit or market
price	number	Price between 0 and 1 (for limit orders)
quantity	number	Number of shares

Authentication

All order operations require authentication using your API key in the x-api-key header:

x-api-key: YOUR_API_KEY

Create Batch Order

Endpoint: POST /openapi/v1/order/batch

Create multiple orders in a single request for improved performance.

Cancel Order

Cancel an existing open order.

Endpoint: DELETE /openapi/v1/order/{orderId}

Cancel All Orders

Cancel all open orders for a specific market.

Endpoint: DELETE /openapi/v1/order/cancel-all/{marketId}

Batch Cancel Orders

Cancel multiple orders by their order IDs in a single request.

Endpoint: POST /openapi/v1/order/cancel-batch

Get My Orders

Retrieve your orders with pagination and filtering options.

Endpoint: GET /openapi/v1/order/my-orders

Get Market Orders

Retrieve all orders in a specific market, filtered by status and paginated.

Endpoint: GET /openapi/v1/order/market/{marketId}

Order Types

Limit Orders

• Execute at a specific price or better
• May not fill immediately
• Provide liquidity to the market

Market Orders

• Execute immediately at best available price
• Guaranteed to fill (if liquidity exists)
• Take liquidity from the market

Order Status

Orders can have the following statuses:

Status	Description
open	Order is active and waiting to be filled
partially_filled	Some quantity has been filled
filled	Order completely executed
cancelled	Order cancelled by user
expired	Order expired based on expiredAt time

Code Examples

Create a Limit Order

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' or 'sell'
    type: 'limit',
    price: price, // Between 0 and 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();
}

// Example: Buy 100 shares at 0.65 price
const order = await createLimitOrder('outcome-uuid', 'buy', 0.65, 100);
console.log(`Order created: ${order.id}`);

Batch Create Orders

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

// Create multiple orders at once
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`);

Cancel Multiple 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();
}

// Cancel multiple orders at once
const orderIdsToCancel = ['order-id-1', 'order-id-2', 'order-id-3'];
await batchCancelOrders(orderIdsToCancel);
console.log('Orders cancelled successfully');

Get Market Orders

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

// Get all open orders for a specific market
const marketOrders = await getMarketOrders('market-uuid', 'open');
console.log(`Found ${marketOrders.length} open orders in market`);

Python Example - Create and Monitor Order

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()

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

# Monitor order status
time.sleep(2)
orders = get_my_orders(status='open')
print(f"Open orders: {orders['total']}")

Best Practices

1. Order Validation: Always validate order parameters before submission
2. Batch Operations: Use batch endpoints when creating/cancelling multiple orders
3. Error Handling: Implement robust error handling for all API calls
4. Rate Limiting: Respect API rate limits to avoid being throttled
5. Order Management: Track your open orders and cancel outdated ones
6. Price Checks: Verify prices are within valid range (0 < price < 1)
7. Signature Security: Never expose your private key; sign orders securely
8. Idempotency: Consider implementing idempotency for order creation to prevent duplicates

Performance Optimization

• Use batch create when placing multiple orders to reduce API calls
• Use batch cancel to efficiently close multiple positions
• Poll my-orders endpoint instead of individual order status checks
• Cache market data to validate orders before submission

Related Documentation

• Quick Start - Get started with the API
• Markets API - Get market information before ordering
• Orderbook API - Check current prices before placing orders
• Positions API - Track your positions after orders fill