> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trusset.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Order

> Place a new buy or sell order on an on-chain order book

Submits a new order to an on-chain order book. Supports limit and market order types with configurable time-in-force, post-only, and self-trade prevention 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. When the order book has a price reference enabled, orders priced outside the configured band are rejected.

## Authentication

Requires an instance API key with the `trading` service enabled.

## Idempotency

This endpoint accepts an optional `Idempotency-Key` header. When supplied, repeating a request with the same key and body returns the original result instead of placing a duplicate order. Reusing a key with a different body returns `IDEMPOTENCY_MISMATCH`.

## Request Body

<ParamField body="orderBookId" type="string" required>
  The target order book identifier. Max 100 characters.
</ParamField>

<ParamField body="userAddress" type="string" required>
  EVM address of the trading user. Must match `0x[a-fA-F0-9]{40}`.
</ParamField>

<ParamField body="side" type="string" required>
  Order side. One of `BUY` or `SELL`.
</ParamField>

<ParamField body="orderType" type="string" required>
  Order type. One of `LIMIT` or `MARKET`.
</ParamField>

<ParamField body="price" type="string">
  Limit price in quote token base units (wei). Required for `LIMIT` orders. Numeric string.
</ParamField>

<ParamField body="quantity" type="string" required>
  Order quantity in base token units (wei). Numeric string.
</ParamField>

<ParamField body="timeInForce" type="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.
</ParamField>

<ParamField body="postOnly" type="boolean">
  When `true`, the order is rejected if it would match immediately as a taker. Use this to guarantee maker status. Defaults to `false`.
</ParamField>

<ParamField body="selfTradePreventionMode" type="string">
  Controls what happens when an order would match against another order from the same `userAddress`. One of:

  * `NONE` - Self-trades are allowed (default).
  * `CANCEL_TAKER` - Cancel the incoming (taker) order.
  * `CANCEL_MAKER` - Cancel the resting (maker) order.
  * `CANCEL_BOTH` - Cancel both orders.
</ParamField>

<ParamField body="signature" type="string">
  Optional signature over the order message, for instances that enforce signed orders. Max 256 characters.
</ParamField>

<ParamField body="message" type="string">
  Optional signed message payload associated with `signature`. Max 512 characters.
</ParamField>

<RequestExample>
  ```json theme={null}
  {
    "orderBookId": "ob_abc123",
    "userAddress": "0x1111111111111111111111111111111111111111",
    "side": "BUY",
    "orderType": "LIMIT",
    "price": "100000000000000000000",
    "quantity": "5000000000000000000",
    "timeInForce": "GTC",
    "postOnly": true,
    "selfTradePreventionMode": "CANCEL_TAKER"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "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",
      "postOnly": true,
      "selfTradePreventionMode": "CANCEL_TAKER",
      "createdAt": "2025-01-15T10:30:00.000Z"
    },
    "metadata": {
      "requestId": "550e8400-e29b-41d4-a716-446655440000",
      "timestamp": "2025-01-15T10:30:00.000Z",
      "instanceId": "inst_abc"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code                           | Status | Description                                                         |
| ------------------------------ | ------ | ------------------------------------------------------------------- |
| `ORDER_BOOK_NOT_FOUND`         | 404    | Order book does not exist                                           |
| `ORDER_BOOK_INACTIVE`          | 400    | Order book is paused or closed                                      |
| `INSUFFICIENT_BALANCE`         | 400    | User does not have sufficient balance                               |
| `INSUFFICIENT_CUSTODY_BALANCE` | 400    | Insufficient balance in custody contract                            |
| `ORDER_TOO_SMALL`              | 400    | Order quantity below minimum                                        |
| `ORDER_TOO_LARGE`              | 400    | Order quantity above maximum                                        |
| `PRICE_REQUIRED`               | 400    | Price is required for limit orders                                  |
| `INVALID_QUANTITY`             | 400    | Invalid quantity value                                              |
| `INVALID_PRICE`                | 400    | Price does not align with tick size                                 |
| `PRICE_OUTSIDE_BAND`           | 400    | Price is outside the allowed price reference band                   |
| `PRICE_REF_STALE`              | 503    | The price reference is stale and the book halts on stale references |
| `PRICE_REF_UNAVAILABLE`        | 503    | The price reference could not be retrieved                          |
| `TRANSFER_RESTRICTED`          | 400    | User is not eligible to trade this token                            |
| `NO_CUSTODY_CONTRACT`          | 400    | Order book has no custody contract configured                       |
| `NO_LIQUIDITY`                 | 400    | No matching liquidity for a market or fill-or-kill order            |
| `SHARED_LIQUIDITY_DISABLED`    | 400    | Shared liquidity routing is disabled for this order book            |
| `INVALID_SIGNATURE`            | 401    | The provided order signature is invalid                             |
| `IDEMPOTENCY_MISMATCH`         | 409    | Idempotency key reused with a different request body                |