> ## 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 Off-Chain Order Book

> Open a book that settles on your custody ledger instead of on chain

Creates a book that settles against your instance's custody ledger. There is no custody contract and no on-chain prerequisite, so the book is usable immediately.

Off-chain is the settlement mode stock orders execute in. See [Settlement modes](/endpoints/stock-trading/introduction#settlement-modes).

Three properties are fixed by this route and cannot be overridden: the settlement mode is `OFF_CHAIN`, no custody contract is attached, and the book is never publishable for import. Everything else behaves as it does on an on-chain book.

## Authentication

Authenticates with an instance API key like the rest of the surface, but does not require the Trading service entitlement, because nothing here touches a custody contract.

## Body Parameters

<ParamField body="tokenAddress" type="string" required>
  Base token contract. Must be registered in your instance's custody ledger before orders can be placed against it.
</ParamField>

<ParamField body="quoteTokenAddress" type="string" required>
  Settlement token (stablecoin) contract, also registered in the ledger. Must differ from `tokenAddress`.
</ParamField>

<ParamField body="name" type="string" required>Display name, 1 to 64 characters.</ParamField>

<ParamField body="symbol" type="string" required>Display symbol, 1 to 16 characters.</ParamField>

<ParamField body="tokenType" type="string" default="LIGHT_TOKEN">
  `STOCK_TOKEN` or `LIGHT_TOKEN`. Set `STOCK_TOKEN` if the book should also appear in the stock reads, which filter on that type.
</ParamField>

<ParamField body="stockTokenId" type="string">Your stock token record ID, up to 100 characters.</ParamField>

<ParamField body="minOrderSize" type="string" default="0">Smallest accepted quantity, in order book units.</ParamField>

<ParamField body="maxOrderSize" type="string">Largest accepted quantity, in order book units.</ParamField>

<ParamField body="tickSize" type="string" default="1">Price increment, in order book units.</ParamField>

<ParamField body="makerFeeBps" type="integer" default="0">Maker fee in basis points, 0 to 1000.</ParamField>

<ParamField body="takerFeeBps" type="integer" default="0">Taker fee in basis points, 0 to 1000.</ParamField>

<ParamField body="priceRefEnabled" type="boolean" default="false">Enforce a reference price band.</ParamField>

<ParamField body="priceRefMode" type="string" default="MANUAL">
  `MANUAL` or `EXTERNAL_FEED`. The market data feed mode is not offered on this route.
</ParamField>

<ParamField body="priceRefFeedUrl" type="string">HTTPS feed endpoint, up to 2048 characters. Must resolve to a public host.</ParamField>

<ParamField body="priceRefFeedHeaders" type="string">Feed request headers as a JSON string, up to 4096 characters.</ParamField>

<ParamField body="priceRefFeedPath" type="string">Dot-separated JSON path to the price in the feed response.</ParamField>

<ParamField body="priceRefEnforcement" type="string" default="EVERY_TRADE">
  Refresh interval, from `EVERY_TRADE` to `1DAY`.
</ParamField>

<ParamField body="priceRefSpreadBps" type="integer">Band half-width in basis points, 1 to 10000.</ParamField>

<ParamField body="priceRefHaltOnStale" type="boolean" default="false">Refuse orders when the reference is stale.</ParamField>

<ParamField body="priceRefStaleTolerance" type="integer">Staleness window in seconds, 60 to 604800.</ParamField>

## Response Fields

Returns `201` with the created book, in the same shape as [Get Order Book](/endpoints/stock-trading/get-order-book). `settlementMode` is `OFF_CHAIN`, `custodyContract` is `null`, and `allowImport` is `false`.

<Note>
  A circuit breaker cannot be configured on this route. To attach one, create the book here and then set `priceRefCircuitBreakerBps` with [Update Order Book](/endpoints/stock-trading/update-order-book).
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.trusset.org/orderbooks/stocks/api/offchain/order-books" \
    -H "X-API-Key: trusset_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "tokenAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
      "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
      "name": "Nyala Fund I",
      "symbol": "NYF1",
      "tokenType": "STOCK_TOKEN",
      "tickSize": "10000",
      "minOrderSize": "1000000",
      "makerFeeBps": 5,
      "takerFeeBps": 15
    }'
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    'https://api.trusset.org/orderbooks/stocks/api/offchain/order-books',
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'trusset_your_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        tokenAddress,
        quoteTokenAddress,
        name: 'Nyala Fund I',
        symbol: 'NYF1',
        tokenType: 'STOCK_TOKEN',
        tickSize: '10000',
        minOrderSize: '1000000'
      })
    }
  );
  const { data } = await res.json();
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "clx_ob_stock_001",
      "instanceId": "inst_abc123",
      "tokenAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
      "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
      "name": "Nyala Fund I",
      "symbol": "NYF1",
      "status": "ACTIVE",
      "tokenType": "STOCK_TOKEN",
      "settlementMode": "OFF_CHAIN",
      "custodyContract": null,
      "allowImport": false,
      "minOrderSize": "1000000",
      "maxOrderSize": null,
      "tickSize": "10000",
      "makerFeeBps": 5,
      "takerFeeBps": 15,
      "tradingMode": "CONTINUOUS",
      "priceRefEnabled": false,
      "priceRefMode": "MANUAL",
      "createdAt": "2025-06-15T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code                | HTTP  | Cause                                                              |
| ------------------- | ----- | ------------------------------------------------------------------ |
| `VALIDATION_ERROR`  | `400` | A field failed schema validation                                   |
| `INVALID_PAIR`      | `400` | Base and quote token are the same                                  |
| `INVALID_CONFIG`    | `400` | An invalid price reference mode, enforcement interval, or feed URL |
| `ORDER_BOOK_EXISTS` | `409` | An `ACTIVE` or `PAUSED` book already quotes this pair              |