> ## 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 source could not be reached. This read is forgiving, so a monitoring call does not fail because a feed blinked. [Submit Order](/endpoints/external-securities-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="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>
  The stale-handling settings are not echoed here. Read `priceRefHaltOnStale` and `priceRefStaleTolerance` from [Get Order Book](/endpoints/external-securities-trading/get-order-book) if you need them.

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

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

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

  const inBand = (obPrice: string) =>
    !data.lowerBound ||
    (Number(obPrice) / 1e6 >= Number(data.lowerBound) && Number(obPrice) / 1e6 <= Number(data.upperBound));
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "enabled": true,
      "mode": "MANUAL",
      "enforcement": "1HOUR",
      "spreadBps": 500,
      "currentPrice": "104.20",
      "lowerBound": "98.99",
      "upperBound": "109.41",
      "lastUpdated": "2025-06-15T11:00:00.000Z"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code                   | HTTP  | Cause                                                               |
| ---------------------- | ----- | ------------------------------------------------------------------- |
| `ORDER_BOOK_NOT_FOUND` | `404` | No such external securities book on this instance, and not imported |
| `SERVICE_NOT_ENABLED`  | `403` | The Trading service is not enabled on this instance                 |