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

# Set Price Reference

> Publish a manual reference price for a commodity book

Records a reference price on a book and makes it effective immediately. Use this when the book is in `MANUAL` mode; in the feed modes the reference is fetched, and a value posted here is overwritten by the next fetch.

Commodities usually have a live external benchmark, so a feed is the natural configuration and manual pricing is the fallback when the feed is down or the instrument has no public quote.

The book must belong to your instance and have `priceRefEnabled` set, otherwise the request is refused with `PRICE_REF_DISABLED`.

## Path Parameters

<ParamField path="orderBookId" type="string" required>Order book ID. Must be a book your instance owns.</ParamField>

## Body Parameters

<ParamField body="price" type="string" required>
  Reference price as a plain positive decimal, such as `"2412.55"`. The commodity's price in the quote currency per unit of the token, not an order book unit value. Up to 64 characters.
</ParamField>

## Side effects

**Circuit breaker.** If `priceRefCircuitBreakerBps` is set and the new price differs from the previous one by more than that threshold, the book is moved to `PAUSED` and a `CIRCUIT_BREAKER_TRIGGERED` entry is written to the log. The request still succeeds; the pause is the response to it. Reopen the book with [Update Order Book](/endpoints/commodity-trading/update-order-book) once you are satisfied the move is real.

**Band sweep.** If the circuit breaker did not trip and `priceRefSpreadBps` is set, resting limit orders now outside the band are cancelled with `PRICE_BAND_VIOLATION` and their reservations released. This runs in the background, so cancellations may land a moment after the response.

Neither runs on the first price a book ever receives.

## Response Fields

<ResponseField name="data" type="object">
  <Expandable>
    <ResponseField name="price" type="string">The stored price, normalised.</ResponseField>
    <ResponseField name="updatedAt" type="string">ISO 8601 timestamp.</ResponseField>
  </Expandable>
</ResponseField>

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

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

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": { "price": "2412.55", "updatedAt": "2025-06-15T12:00:00.000Z" }
  }
  ```

  ```json Error - Reference Not Enabled theme={null}
  {
    "success": false,
    "data": null,
    "error": {
      "code": "PRICE_REF_DISABLED",
      "message": "Price reference is not enabled for this order book"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code                   | HTTP  | Cause                                                                       |
| ---------------------- | ----- | --------------------------------------------------------------------------- |
| `VALIDATION_ERROR`     | `400` | `price` is missing or not a positive decimal string                         |
| `INVALID_PARAM`        | `400` | `orderBookId` is missing or longer than 100 characters                      |
| `INVALID_PRICE`        | `400` | `price` parses to zero, a negative number, or a non-finite value            |
| `PRICE_REF_DISABLED`   | `400` | The book does not have `priceRefEnabled` set                                |
| `ORDER_BOOK_NOT_FOUND` | `404` | The book does not exist on your instance. Imported books cannot be repriced |
| `SERVICE_NOT_ENABLED`  | `403` | The Trading service is not enabled on this instance                         |