Skip to main content
POST
/
orderbooks
/
stocks
/
api
/
orders
{
  "orderBookId": "ob_abc123",
  "userAddress": "0x1111111111111111111111111111111111111111",
  "side": "BUY",
  "orderType": "LIMIT",
  "price": "100000000000000000000",
  "quantity": "5000000000000000000",
  "timeInForce": "GTC"
}

{
  "success": true,
  "data": {
    "id": "ord_xyz789",
    "orderBookId": "ob_abc123",
    "userAddress": "0x1111111111111111111111111111111111111111",
    "side": "BUY",
    "orderType": "LIMIT",
    "price": "100000000000000000000",
    "quantity": "5000000000000000000",
    "filledQuantity": "0",
    "status": "OPEN",
    "timeInForce": "GTC",
    "createdAt": "2025-01-15T10:30:00.000Z"
  },
  "metadata": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-01-15T10:30:00.000Z",
    "instanceId": "inst_abc"
  }
}
Submits a new order to an on-chain order book. Supports limit and market order types with configurable time-in-force policies. For LIMIT orders, the price field is required and specifies the maximum (buy) or minimum (sell) acceptable price. MARKET orders execute immediately at the best available price. The userAddress must be a verified on-chain identity with sufficient custody balance for sell orders, or sufficient quote token balance for buy orders.

​
Authentication

Requires an instance API key with the trading service enabled.

​
Request Body

​
orderBookId
string
required
The target order book identifier. Max 100 characters.
​
userAddress
string
required
EVM address of the trading user. Must match 0x[a-fA-F0-9]{40}.
​
side
string
required
Order side. One of BUY or SELL.
​
orderType
string
required
Order type. One of LIMIT or MARKET.
​
price
string
Limit price in quote token base units (wei). Required for LIMIT orders. Numeric string.
​
quantity
string
required
Order quantity in base token units (wei). Numeric string.
​
timeInForce
string
Time-in-force policy. One of:
  • GTC - Good Till Cancelled (default). Remains on the book until filled or cancelled.
  • IOC - Immediate or Cancel. Fills what it can immediately, cancels the rest.
  • FOK - Fill or Kill. Must fill entirely or is rejected.
{
  "orderBookId": "ob_abc123",
  "userAddress": "0x1111111111111111111111111111111111111111",
  "side": "BUY",
  "orderType": "LIMIT",
  "price": "100000000000000000000",
  "quantity": "5000000000000000000",
  "timeInForce": "GTC"
}

{
  "success": true,
  "data": {
    "id": "ord_xyz789",
    "orderBookId": "ob_abc123",
    "userAddress": "0x1111111111111111111111111111111111111111",
    "side": "BUY",
    "orderType": "LIMIT",
    "price": "100000000000000000000",
    "quantity": "5000000000000000000",
    "filledQuantity": "0",
    "status": "OPEN",
    "timeInForce": "GTC",
    "createdAt": "2025-01-15T10:30:00.000Z"
  },
  "metadata": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-01-15T10:30:00.000Z",
    "instanceId": "inst_abc"
  }
}

​
Error Codes

CodeStatusDescription
ORDER_BOOK_NOT_FOUND404Order book does not exist
ORDER_BOOK_INACTIVE400Order book is paused or closed
INSUFFICIENT_BALANCE400User does not have sufficient balance
INSUFFICIENT_CUSTODY_BALANCE400Insufficient balance in custody contract
ORDER_TOO_SMALL400Order quantity below minimum
ORDER_TOO_LARGE400Order quantity above maximum
PRICE_REQUIRED400Price is required for limit orders
INVALID_QUANTITY400Invalid quantity value
INVALID_PRICE400Price does not align with tick size
TRANSFER_RESTRICTED400User is not eligible to trade this token
NO_CUSTODY_CONTRACT400Order book has no custody contract configured