Orders
The Orders API allows you to create, cancel, and manage orders on the Xmarket platform.
Create Order
Create a new order in orderbook.
123123150buyPossible values: limitPossible values: openPossible values: Order created
Bad request
Not found
Internal server error
POST /openapi/v1/order HTTP/1.1
Host:
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 117
{
"marketId": "market-id",
"outcomeId": "outcome-id",
"quantity": 1,
"price": 50,
"side": "buy",
"type": "limit",
"status": "open"
}No content
Authentication
All order operations require authentication using your API key in the x-api-key header:
x-api-key: YOUR_API_KEYCreate Batch Order
123123150buyPossible values: limitPossible values: openPossible values: Batch orders created
Bad request
Not found
Internal server error
POST /openapi/v1/order/batch HTTP/1.1
Host:
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 119
[
{
"marketId": "market-id",
"outcomeId": "outcome-id",
"quantity": 1,
"price": 50,
"side": "buy",
"type": "limit",
"status": "open"
}
]{
"success": true,
"results": [
{
"order": {
"id": "order-id",
"marketId": "123"
},
"error": null
},
{
"order": null,
"error": "Insufficient balance"
}
],
"message": "Batch create completed"
}Cancel Order
Cancel an existing open order.
a1b2c3d4-5678-90ab-cdef-1234567890abOrder cancelled
Bad request
Order not found
Internal server error
DELETE /openapi/v1/order/{orderId} HTTP/1.1
Host:
x-api-key: YOUR_API_KEY
Accept: */*
{
"success": true,
"message": "text",
"order": null
}Batch Create Orders
Create multiple orders in a single request for improved performance.
123123150buyPossible values: limitPossible values: openPossible values: Batch orders created
Bad request
Not found
Internal server error
POST /openapi/v1/order/batch HTTP/1.1
Host:
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 119
[
{
"marketId": "market-id",
"outcomeId": "outcome-id",
"quantity": 1,
"price": 50,
"side": "buy",
"type": "limit",
"status": "open"
}
]{
"success": true,
"results": [
{
"order": {
"id": "order-id",
"marketId": "123"
},
"error": null
},
{
"order": null,
"error": "Insufficient balance"
}
],
"message": "Batch create completed"
}Cancel Order
Cancel an existing open order.
a1b2c3d4-5678-90ab-cdef-1234567890abOrder cancelled
Bad request
Order not found
Internal server error
DELETE /openapi/v1/order/{orderId} HTTP/1.1
Host:
x-api-key: YOUR_API_KEY
Accept: */*
{
"success": true,
"message": "text",
"order": null
}Cancel All Orders
Cancel all open orders for a specific market.
44a64332-5304-4340-93b4-5ebae21c7b54All market orders cancelled
Bad request
No open orders found
Internal server error
DELETE /openapi/v1/order/cancel-all/{marketId} HTTP/1.1
Host:
x-api-key: YOUR_API_KEY
Accept: */*
{
"success": true,
"message": "text",
"count": 1
}Batch Cancel Orders
Cancel multiple orders by their order IDs in a single request.
["a1b2c3d4-5678-90ab-cdef-1234567890ab","b2c3d4e5-6789-01ab-cdef-2345678901bc"]Batch cancel result
Bad request
Internal server error
POST /openapi/v1/order/cancel-batch HTTP/1.1
Host:
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 92
{
"orderIds": [
"a1b2c3d4-5678-90ab-cdef-1234567890ab",
"b2c3d4e5-6789-01ab-cdef-2345678901bc"
]
}{
"success": true,
"cancelled": [
"a1b2c3d4-5678-90ab-cdef-1234567890ab"
],
"failed": [
{
"orderId": "b2c3d4e5-6789-01ab-cdef-2345678901bc",
"reason": "Order not found or unauthorized"
}
],
"message": "Batch cancel completed"
}Get My Orders
Retrieve your orders with pagination and filtering options.
1Example: 120Example: 20openPossible values: limitPossible values: buyPossible values: Filter by marketId (optional)
market-idMy orders
Bad request
Internal server error
GET /openapi/v1/order/my-orders HTTP/1.1
Host:
x-api-key: YOUR_API_KEY
Accept: */*
{
"data": [
{
"id": "text",
"marketId": "text",
"outcomeId": "text",
"quantity": "text",
"filledQuantity": "text",
"price": "text",
"side": "buy",
"type": "market",
"status": "text",
"createdAt": "text",
"updatedAt": "text"
}
],
"page": 1,
"pageSize": 1,
"total": 1,
"totalPages": 1
}Get Market Orders
Retrieve all orders in a specific market, filtered by status and paginated.
Market ID
44a64332-5304-4340-93b4-5ebae21c7b54Page number
1Example: 1Pattern: ^\d+$Page size
50Example: 50Pattern: ^\d+$Sort by updatedAt
descExample: descPossible values: Orders in market
Bad request
Market or orders not found
Internal server error
GET /openapi/v1/order/market/{marketId} HTTP/1.1
Host:
x-api-key: YOUR_API_KEY
Accept: */*
{
"orders": [
{
"id": "order-uuid",
"userId": "user-uuid",
"marketId": "44a64332-5304-4340-93b4-5ebae21c7b54",
"outcomeId": "4ccd6f43-0059-4fbe-a963-091e9c364a64",
"quantity": "10",
"amount": "100",
"filledQuantity": "5",
"price": "0.5",
"filledPrice": "0.5",
"fee": "0.01",
"side": "buy",
"type": "limit",
"status": "open",
"cancelReason": null,
"isSystem": false,
"signature": "signature",
"expiredAt": null,
"signTime": 1680000000,
"createdAt": "2024-06-01T00:00:00.000Z",
"updatedAt": "2024-06-01T00:00:00.000Z",
"outcomeName": "Yes",
"isYour": true
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 100,
"totalPages": 5
}
}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:
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
Order Validation: Always validate order parameters before submission
Batch Operations: Use batch endpoints when creating/cancelling multiple orders
Error Handling: Implement robust error handling for all API calls
Rate Limiting: Respect API rate limits to avoid being throttled
Order Management: Track your open orders and cancel outdated ones
Price Checks: Verify prices are within valid range (0 < price < 1)
Signature Security: Never expose your private key; sign orders securely
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
Last updated
Was this helpful?