Trading API

Order placement, cancellation, and management endpoints.

Place Order

Submit a new order to the orderbook with automatic fund locking and settlement.

Endpoint: place_order(request: PlaceOrderRequest) -> Result<PlaceOrderResponse>

Request

type PlaceOrderRequest = record {
  market_id: text;
  side: OrderSide;
  order_type: OrderType;
  quantity: nat64;
  slippage_tolerance: nat16;  // Basis points (100 = 1%)
  time_in_force: TimeInForce;
};

type OrderType = variant {
  Market;
  Limit: record { price: nat64 };
};

type OrderSide = variant { Bid; Ask };

type TimeInForce = variant {
  GTC;              // Good-Til-Cancelled
  GTD: nat64;       // Good-Til-Date (timestamp in ms)
  IOC;              // Immediate-Or-Cancel
  FOK;              // Fill-Or-Kill
};

Response

type PlaceOrderResponse = record {
  order_id: nat64;
  client_id: nat64;
  account_id: nat64;
  status: OrderStatus;
  filled_quantity: nat64;
  remaining_quantity: nat64;
  average_price: nat64;
  trades: vec SimpleTrade;
  timestamp: nat64;
};

type OrderStatus = variant {
  Active;           // Order is in the book
  PartiallyFilled;  // Partially executed
  Filled;           // Fully executed
  Cancelled;        // Cancelled by user
  Expired;          // Time-in-force expired
  Rejected;         // Validation failed
  Pending;          // Awaiting processing
};

Example (TypeScript)

const response = await backend.place_order({
  market_id: 'BTC/USDT',
  order_type: { Limit: { price: 50000_00000000n } },
  side: { Bid: null },
  quantity: 100_000000n,
  slippage_tolerance: 50,
  time_in_force: { GTC: null },
})

if ('Ok' in response) {
  console.log(`Order ${response.Ok.order_id} placed`)
}

Example (dfx CLI)

dfx canister call backend place_order '(
  record {
    market_id = "BTC/USDT";
    order_type = variant { Limit = record { price = 50_000_00000000 } };
    side = variant { Bid };
    quantity = 100_000000;
    slippage_tolerance = 50;
    time_in_force = variant { GTC };
  }
)'

TIP

• slippage_tolerance is in basis points (100 = 1%)
• Price and quantity decimals depend on market configuration
• Fund locking is automatic

Cancel Order

Cancel a single order by ID. Remaining locked funds are automatically released.

Endpoint: cancel_order(market_id: text, order_id: nat64) -> Result<CancelResponse>

const response = await backend.cancel_order('BTC/USDT', 12345n)
if ('Ok' in response) {
  console.log(`Cancelled order ${response.Ok.order_id}`)
}

Cancel All Orders

Cancel all open orders in a market.

Endpoint: cancel_all(market_id: text) -> Result<BulkCancelResponse>

const response = await backend.cancel_all('BTC/USDT')
if ('Ok' in response) {
  console.log(`Cancelled ${response.Ok.total_cancelled} orders`)
}

Update Order

Modify an existing order's price and/or quantity.

Endpoint: update_order(market_id: text, order_id: nat64, request: UpdateOrderRequest) -> Result<OrderResponse>

const response = await backend.update_order('BTC/USDT', 12345n, {
  new_price: [51000_00000000n],
  new_quantity: [],
})

INFO

At least one of new_price or new_quantity must be provided.

Get Order

Query current status of a specific order.

Endpoint: get_order(market_id: text, order_id: nat64) -> Result<AdvancedOrder> (query)

const result = await backend.get_order('BTC/USDT', 12345n)
if ('Ok' in result) {
  console.log(`Order ${result.Ok.id}: ${Object.keys(result.Ok.status)[0]}`)
}

Get Open Orders

Retrieve all active orders for the current user in a market.

Endpoint: orders(market_id: text) -> Result<vec OrderStatusRecord> (query)

const result = await backend.orders('BTC/USDT')
if ('Ok' in result) {
  console.log(`You have ${result.Ok.length} active orders`)
}

Get Order History

Retrieve historical orders (filled, cancelled, expired) with pagination.

Endpoint: order_history(market_id: text, limit: opt nat64, offset: opt nat64) -> Result<vec OrderHistoryRecord> (query)

const result = await backend.order_history('BTC/USDT', [50n], [10n])

Get Trade History

Retrieve trade fill records for the current user.

Endpoint: trade_history(market_id: text, limit: opt nat64, offset: opt nat64) -> Result<vec TradeRecord> (query)

const result = await backend.trade_history('BTC/USDT', [100n], [])
if ('Ok' in result) {
  result.Ok.forEach((trade) => {
    const role = trade.is_maker ? 'MAKER' : 'TAKER'
    console.log(`${role} ${trade.quantity} @ ${trade.price}`)
  })
}

Get Position

Retrieve position information for a market.

Endpoint: positions(market_id: text) -> Result<PositionInfo> (query)