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

# Preview Price Feed

> Read a price feed once before you save it on a book

Reads a price feed once and returns the price it would give, converted into the book's settlement currency where that applies. Nothing is saved. Use it to check a stock ticker, a commodity unit or a custom feed before you set it with `priceFeed` on [Create Order Book](https://docs.trusset.org/endpoints/external-securities-trading/create-order-book.md) or [Update Order Book](https://docs.trusset.org/endpoints/external-securities-trading/update-order-book.md). See [Price feed module](https://docs.trusset.org/endpoints/external-securities-trading/introduction.md#price-feed-module).

The settlement currency comes from `orderBookId` when you name a book, or from `quoteTokenAddress` before a book exists. With neither, the price comes back in the feed's own currency. A USD feed on a book that settles in a USD stablecoin such as USDC is not converted. A custom feed is never converted and comes back with `currency` `null`, because its currency is not known: it is used as it quotes.

## Body Parameters

**priceFeed** `object` *required*

The feed to read, in the same shape as on [Create Order Book](https://docs.trusset.org/endpoints/external-securities-trading/create-order-book.md).

**source** `string` *required*

`MANUAL`, `STOCK`, `COMMODITY` or `CUSTOM`.

**symbol** `string`

`STOCK`: the ticker of the listing, with its exchange MIC after a colon for a listing outside the US, such as `SAP:XETR` or `AIR:XPAR`. A bare ticker such as `AAPL` reads the US listing. `COMMODITY`: `XAU`, `XAG`, `XPT` or `XPD`.

**unit** `string` (default: TROY\_OUNCE)

`COMMODITY` only: `TROY_OUNCE`, `GRAM` or `KILOGRAM`.

**url** `string`

`CUSTOM` only: HTTPS feed endpoint on a public host.

**path** `string`

`CUSTOM` only: dotted JSON path to the price.

**headers** `string`

`CUSTOM` only: request headers as a JSON string. Leave it out on a book you own to use the headers stored for the same feed host.

**orderBookId** `string`

A book you own or have imported. Its settlement currency is used.

**quoteTokenAddress** `string`

The settlement asset of a book you are about to create. Its currency is used.

## Response Fields

**data** `object`

**source** `string`

What was read: `STOCK_FEED:<symbol>`, `COMMODITY_FEED:<metal>:<unit>`, `EXTERNAL_FEED`, or `MANUAL`.

**price** `string`

The price per token as a plain decimal, or `null` for `MANUAL`, which has nothing to read.

**currency** `string`

The currency of `price`, or `null` when it is not known.

**converted** `boolean`

Whether the feed price was converted between USD and EUR.

**feedPrice** `string`

Converted reads only. The price as the feed gave it.

**feedCurrency** `string`

Converted reads only. The feed's own currency.

**rate** `number`

Converted reads only. The factor applied, from the ECB reference rate.

**rateDate** `string`

Converted reads only. The ECB reference date of that rate.

**instrument** `object`

`STOCK` only. The listing the provider priced: `symbol`, `name`, `exchange` and `micCode`. Check it names the company you mean before you save the feed.

**readAt** `string`

When the feed was read, as an ISO 8601 timestamp. Absent for `MANUAL`.

```bash cURL theme={null}
curl -X POST "https://api.trusset.org/orderbooks/external-securities/api/price-feeds/preview" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "priceFeed": { "source": "COMMODITY", "symbol": "XAU", "unit": "GRAM" },
    "quoteTokenAddress": "0x08210f9170f89ab7658f0b5e3ff39b0e03c594d4"
  }'
```

```typescript TypeScript theme={null}
const res = await fetch(
  'https://api.trusset.org/orderbooks/external-securities/api/price-feeds/preview',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'trusset_your_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      priceFeed: { source: 'STOCK', symbol: 'SAP:XETR' },
      orderBookId
    })
  }
);
const { data } = await res.json();
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "source": "COMMODITY_FEED:XAU:GRAM",
    "price": "102.48",
    "currency": "EUR",
    "converted": true,
    "feedPrice": "110.21",
    "feedCurrency": "USD",
    "rate": 0.9298,
    "rateDate": "2025-06-13",
    "readAt": "2025-06-15T12:00:00.000Z"
  }
}
```

```json Error - Currency Cannot Be Converted theme={null}
{
  "success": false,
  "data": null,
  "error": {
    "code": "FEED_CURRENCY_UNSUPPORTED",
    "message": "The feed quotes in GBP and the order book settles in EUR. Only USD and EUR convert automatically."
  }
}
```

## Error Codes

| Code | HTTP | Cause |
| - | - | - |
| `VALIDATION_ERROR` | `400` | A field failed schema validation, or an unknown field was sent |
| `INVALID_CONFIG` | `400` | A `priceFeed` field is invalid. Carries `field` |
| `INVALID_FEED_URL` | `400` | The custom feed host resolves to an address that is not public |
| `ORDER_BOOK_NOT_FOUND` | `404` | `orderBookId` names no book reachable from your instance |
| `SYMBOL_NOT_FOUND` | `422` | The stock data provider knows no listing for the ticker, or for the ticker on the named exchange |
| `FEED_CURRENCY_UNSUPPORTED` | `422` | The feed's currency differs from the settlement currency, and one of them is neither USD nor EUR |
| `FEED_FETCH_ERROR` | `424` | The custom feed could not be fetched |
| `FEED_HTTP_ERROR` | `424` | The custom feed answered with an error status |
| `FEED_TIMEOUT` | `424` | The custom feed did not answer in time |
| `FEED_RESPONSE_TOO_LARGE` | `424` | The custom feed answered with more than 64 KB |
| `FEED_PARSE_ERROR` | `424` | No positive price could be read at `path` |
| `STOCK_FEED_NO_DATA` | `424` | The stock data provider returned no price |
| `COMMODITY_FEED_NO_DATA` | `424` | No spot price is available for the metal |
| `FX_RATE_UNAVAILABLE` | `503` | The ECB reference rate is unavailable, so the price cannot be converted |
| `PROVIDER_UNAVAILABLE` | `503` | The stock data provider is unavailable |
| `RATE_LIMIT_EXCEEDED` | `429` | More than 10 writes per minute on this key |
| `SERVICE_NOT_ENABLED` | `403` | The Trading service is not enabled on this instance |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.