> ## 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.

# Create Order Book

> Deploy a new on-chain order book for a token pair

Creates a new on-chain order book that pairs a stock token with a quote token. The order book settles trades through a custody contract on-chain.

Both `tokenAddress` and `quoteTokenAddress` must reference deployed, registered tokens within the instance. The custody contract handles escrow during the settlement lifecycle.

Order books support three matching modes (continuous, periodic auction, and hybrid) and an optional price reference layer that bounds execution prices against an external or manual reference. Both are configured at creation and can be adjusted later with [Update Order Book](/endpoints/stock-trading/update-order-book).

## Authentication

Requires an instance API key with the `trading` service enabled. Pass the key as `x-api-key` header in the format `trusset_{instanceRef}_{secret}`.

## Request Body

<ParamField body="tokenAddress" type="string" required>
  EVM address of the base token (the asset being traded). Must match `0x[a-fA-F0-9]{40}`.
</ParamField>

<ParamField body="quoteTokenAddress" type="string" required>
  EVM address of the quote token (the currency used for pricing). Must match `0x[a-fA-F0-9]{40}`.
</ParamField>

<ParamField body="name" type="string" required>
  Display name of the order book. 1-64 characters.
</ParamField>

<ParamField body="symbol" type="string" required>
  Short symbol for the trading pair. 1-16 characters.
</ParamField>

<ParamField body="custodyContract" type="string">
  EVM address of the custody contract for on-chain settlement. If omitted, trades require manual settlement coordination.
</ParamField>

<ParamField body="minOrderSize" type="string">
  Minimum order size in base units (wei). Numeric string.
</ParamField>

<ParamField body="maxOrderSize" type="string">
  Maximum order size in base units (wei). Numeric string. Omit for no upper limit.
</ParamField>

<ParamField body="tickSize" type="string">
  Minimum price increment in quote token base units. Numeric string.
</ParamField>

<ParamField body="makerFeeBps" type="integer">
  Fee charged to makers in basis points. 0-1000 (0%-10%).
</ParamField>

<ParamField body="takerFeeBps" type="integer">
  Fee charged to takers in basis points. 0-1000 (0%-10%).
</ParamField>

<ParamField body="tokenType" type="string">
  Type of the base token. One of `LIGHT_TOKEN` or `STOCK_TOKEN`. Defaults to `LIGHT_TOKEN`.
</ParamField>

<ParamField body="stockTokenId" type="string">
  Reference ID for stock tokens. Required when `tokenType` is `STOCK_TOKEN`. Max 100 characters.
</ParamField>

<ParamField body="underlyingIdentifier" type="string">
  Identifier of the underlying instrument (for example an ISIN). Exactly 12 alphanumeric characters, matching `[A-Za-z0-9]{12}`.
</ParamField>

<ParamField body="allowImport" type="boolean">
  Whether other instances can import this order book for cross-instance trading. Defaults to `false`.
</ParamField>

### Trading Mode (Hybrid Order Books)

These fields control the matching engine. Continuous books match orders on arrival; periodic auction books batch orders and clear at fixed intervals; hybrid books switch between the two based on live spread.

<ParamField body="tradingMode" type="string">
  Matching engine mode. One of `CONTINUOUS` (default), `PERIODIC_AUCTION`, or `HYBRID`.
</ParamField>

<ParamField body="auctionIntervalSeconds" type="integer">
  Auction clearing interval in seconds. Applies to `PERIODIC_AUCTION` and `HYBRID`. 30-3600. Nullable.
</ParamField>

<ParamField body="hybridSwitchSpreadBps" type="integer">
  Spread threshold in basis points that switches a `HYBRID` book between continuous matching and auction batching. 1-10000. Nullable.
</ParamField>

<ParamField body="auctionRollUnmatched" type="boolean">
  Whether orders left unmatched at the end of an auction roll forward into the next auction.
</ParamField>

<ParamField body="mmMakerRebateBps" type="integer">
  Maker rebate paid to registered market makers, in basis points. -1000 to 1000 (negative values charge makers). Nullable.
</ParamField>

### Price Reference

When enabled, the price reference layer bounds order and trade prices to a band around a reference price. Stale or out-of-band conditions can halt the book or reject orders.

<ParamField body="priceRefEnabled" type="boolean">
  Enable price reference enforcement for this order book.
</ParamField>

<ParamField body="priceRefMode" type="string">
  Source of the reference price. One of `MANUAL`, `STOCK_FEED`, or `EXTERNAL_FEED`.
</ParamField>

<ParamField body="priceRefFeedUrl" type="string">
  Feed endpoint to poll when `priceRefMode` is `EXTERNAL_FEED`. Max 2048 characters. Nullable.
</ParamField>

<ParamField body="priceRefFeedHeaders" type="string">
  Headers to send with the feed request, as a serialized string (for example a JSON object of header pairs). Max 4096 characters. Nullable.
</ParamField>

<ParamField body="priceRefFeedPath" type="string">
  Path used to extract the price from the feed response (for example a JSON path). Max 256 characters. Nullable.
</ParamField>

<ParamField body="priceRefEnforcement" type="string">
  How often the reference is refreshed and enforced. One of `EVERY_TRADE`, `1MIN`, `5MIN`, `10MIN`, `30MIN`, `1HOUR`, `6HOUR`, `12HOUR`, `1DAY`.
</ParamField>

<ParamField body="priceRefSpreadBps" type="integer">
  Allowed band around the reference price, in basis points. Orders priced outside the band are rejected. 1-10000. Nullable.
</ParamField>

<ParamField body="priceRefHaltOnStale" type="boolean">
  Halt the order book when the reference price is older than `priceRefStaleTolerance`.
</ParamField>

<ParamField body="priceRefStaleTolerance" type="integer">
  Maximum age of the reference price before it is considered stale, in seconds. 60-604800. Nullable.
</ParamField>

<ParamField body="priceRefCircuitBreakerBps" type="integer">
  Circuit breaker threshold in basis points. A reference move beyond this bound trips the breaker. 10-10000. Nullable.
</ParamField>

<RequestExample>
  ```json theme={null}
  {
    "tokenAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "quoteTokenAddress": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "name": "ACME Corp Shares / EURC",
    "symbol": "ACME/EURC",
    "custodyContract": "0x9876543210fedcba9876543210fedcba98765432",
    "minOrderSize": "1000000000000000000",
    "tickSize": "100000000000000",
    "makerFeeBps": 10,
    "takerFeeBps": 25,
    "tokenType": "STOCK_TOKEN",
    "stockTokenId": "acme-corp-001",
    "underlyingIdentifier": "US0000ACME01",
    "allowImport": true,
    "tradingMode": "HYBRID",
    "auctionIntervalSeconds": 300,
    "hybridSwitchSpreadBps": 50,
    "auctionRollUnmatched": true,
    "mmMakerRebateBps": 5,
    "priceRefEnabled": true,
    "priceRefMode": "EXTERNAL_FEED",
    "priceRefFeedUrl": "https://feed.example.com/acme",
    "priceRefFeedPath": "data.last",
    "priceRefEnforcement": "1MIN",
    "priceRefSpreadBps": 200,
    "priceRefHaltOnStale": true,
    "priceRefStaleTolerance": 300
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "ob_abc123",
      "tokenAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "quoteTokenAddress": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
      "name": "ACME Corp Shares / EURC",
      "symbol": "ACME/EURC",
      "status": "ACTIVE",
      "settlementMode": "ON_CHAIN",
      "custodyContract": "0x9876543210fedcba9876543210fedcba98765432",
      "minOrderSize": "1000000000000000000",
      "maxOrderSize": null,
      "tickSize": "100000000000000",
      "makerFeeBps": 10,
      "takerFeeBps": 25,
      "tokenType": "STOCK_TOKEN",
      "stockTokenId": "acme-corp-001",
      "underlyingIdentifier": "US0000ACME01",
      "allowImport": true,
      "tradingMode": "HYBRID",
      "auctionIntervalSeconds": 300,
      "hybridSwitchSpreadBps": 50,
      "auctionRollUnmatched": true,
      "mmMakerRebateBps": 5,
      "priceRefEnabled": true,
      "priceRefMode": "EXTERNAL_FEED",
      "priceRefEnforcement": "1MIN",
      "priceRefSpreadBps": 200,
      "priceRefHaltOnStale": true,
      "priceRefStaleTolerance": 300
    },
    "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_EXISTS`               | 409    | An order book for this token pair already exists         |
| `INVALID_CONFIG`                  | 400    | Invalid order book configuration                         |
| `INVALID_PAIR`                    | 400    | Invalid token pair (e.g. same token for both sides)      |
| `TOKEN_NOT_REGISTERED`            | 400    | One or both tokens are not registered in this instance   |
| `BASE_TOKEN_NOT_SUPPORTED`        | 503    | The base token is not supported by the settlement layer  |
| `QUOTE_TOKEN_NOT_SUPPORTED`       | 503    | The quote token is not supported by the settlement layer |
| `BASE_TOKEN_REGISTRATION_FAILED`  | 503    | On-chain registration of the base token failed           |
| `QUOTE_TOKEN_REGISTRATION_FAILED` | 503    | On-chain registration of the quote token failed          |
| `CUSTODY_NOT_AUTHORIZED`          | 503    | The custody contract has not authorized this order book  |
| `CUSTODY_SETUP_FAILED`            | 503    | Custody contract setup failed                            |
| `NETWORK_MISMATCH`                | 400    | Token and custody contract are on different networks     |
| `VALIDATION_ERROR`                | 400    | Request body failed schema validation                    |