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

# Get Price Reference

> Read the current reference price and the band it implies

Returns the book's reference configuration together with the live price and the band derived from it. The price is resolved the same way an incoming order would resolve it: from cache if the enforcement interval has not elapsed, otherwise from the configured source.

A book with the reference disabled returns its configuration with `currentPrice`, `lowerBound` and `upperBound` all `null`. So does a book whose feed could not be reached. This read is deliberately forgiving, so a monitoring call does not fail because a feed blinked. [Submit Order](/endpoints/commodity-trading/submit-order) takes the stricter view and can refuse with `PRICE_REF_STALE`.

## Path Parameters

<ParamField path="orderBookId" type="string" required>Order book ID.</ParamField>

## Response Fields

<ResponseField name="data" type="object">
  <Expandable>
    <ResponseField name="enabled" type="boolean">Whether the band is enforced on incoming orders.</ResponseField>
    <ResponseField name="mode" type="string">`MANUAL`, `STOCK_FEED` or `EXTERNAL_FEED`.</ResponseField>
    <ResponseField name="enforcement" type="string">Refresh interval, from `EVERY_TRADE` to `1DAY`.</ResponseField>
    <ResponseField name="spreadBps" type="integer">Band half-width in basis points, or `null` if no band is enforced.</ResponseField>
    <ResponseField name="haltOnStale" type="boolean">Whether a stale reference stops trading.</ResponseField>
    <ResponseField name="staleTolerance" type="integer">Staleness window in seconds, or `null` for the derived default.</ResponseField>
    <ResponseField name="currentPrice" type="string">Live reference price as a plain decimal, or `null`.</ResponseField>
    <ResponseField name="lowerBound" type="string">Lowest accepted price as a plain decimal, or `null`.</ResponseField>
    <ResponseField name="upperBound" type="string">Highest accepted price as a plain decimal, or `null`.</ResponseField>
    <ResponseField name="lastUpdated" type="string">When the stored reference was last written, or `null`.</ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Bounds are decimals in the quote currency. An order's `price` is an order book unit integer, so divide it by 1000000 before comparing it against `lowerBound` and `upperBound`.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.trusset.org/orderbooks/commodities/api/order-books/clx_ob_comm_001/price-reference" \
    -H "X-API-Key: trusset_your_key_here"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    `https://api.trusset.org/orderbooks/commodities/api/order-books/${orderBookId}/price-reference`,
    { headers: { 'X-API-Key': 'trusset_your_key_here' } }
  );
  const { data } = await res.json();
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "enabled": true,
      "mode": "EXTERNAL_FEED",
      "enforcement": "1MIN",
      "spreadBps": 100,
      "haltOnStale": true,
      "staleTolerance": 300,
      "currentPrice": "2412.55",
      "lowerBound": "2388.4245",
      "upperBound": "2436.6755",
      "lastUpdated": "2025-06-15T11:59:30.000Z"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code                   | HTTP  | Cause                                                     |
| ---------------------- | ----- | --------------------------------------------------------- |
| `INVALID_PARAM`        | `400` | `orderBookId` is missing or longer than 100 characters    |
| `ORDER_BOOK_NOT_FOUND` | `404` | No such commodity book on this instance, and not imported |
| `SERVICE_NOT_ENABLED`  | `403` | The Trading service is not enabled on this instance       |