# Venue market data

Source: https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-market-data
A Trading Venue instrument's official close, ticker, candles, streams, announcements and price alerts, plus its trading calendar and participant notifications.

An instrument is one trading line on a [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue), a base token against a quote token, on a tenant's own venue. The API paths and the `marketId` field keep the older name, market. Each instrument publishes its own prices and trades on a calendar its venue and the instrument set together, and the platform tells participants what happened to their orders. The Trading Venue page explains what a venue and a market are and how an order becomes a delivered trade.

## Market data: what an instrument publishes [#market-data-what-an-instrument-publishes]

An instrument keeps its own price record from its trades: an official close for each session, a ticker, candles and live streams. The ticker and the candles leave out an undone trade: a bust takes the trade out of the prices as well as out of the books. The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) carries every route and field this section names. [Market Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/market-data) is the separate feed system that holds a token's price, and the reference instrument's close is the one value a venue writes to it.

### The official close and the token's price feed [#the-official-close-and-the-tokens-price-feed]

An instrument's official close is its last trade of the session, or the volume-weighted average price over a set window before the close, rounded down to the price step. On a day with a closing auction, the close is the auction's price when it cleared one. When it cleared nothing, the close counts only the trades up to the start of the auction. On a day with a Trade-At-Last session, the close counts only the trades up to the start of that session and the window ends there, so trades at the last price after it do not move the close. When no trade falls in that window but the session traded earlier, the platform takes the same length of window ending at the session's last trade. A session with no trade falls back to the auction price and then the previous official close, or straight to the previous close, and an instrument with no previous close uses its reference price. An instrument set to close on the volume-weighted price cannot be listed or changed without its window, and the window cannot be longer than the instrument's shortest scheduled session. [Venue market settings](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument#most-listing-choices-get-a-later-edit-some-do-not) covers the setting and the fallback in full.

Of the instruments that trade a token, one can be flagged as its reference instrument, and the platform writes that instrument's close to the token's price feed. A token has at most one reference instrument on each system. Listing an instrument without a choice makes it the reference instrument only when no other instrument holds the role. Asking for the role is refused with "Another instrument already publishes this base token's price on this system" when another instrument holds it, and it is refused for a base token pegged to a currency or with an unknown asset class. Moving the role onto an instrument through an instrument update takes it from the instrument that held it. It skips the write in seven cases. Each skip is logged with its reason, and the instrument's own close stands either way.

| The platform skips the feed write when | Why |
| --- | --- |
| The base token has no active price feed on the system | There is no feed to write to |
| The base or the quote token has no resolved price | The close cannot be converted without it |
| The base token's asset class is pegged to a currency, or is unknown | A pegged token takes its price from exchange-rate feeds, and an unclassified one has no rule that prices it from a market |
| The quote token's own price was observed after the close | The conversion would mix a later price into an earlier close |
| No exchange rate known at the close converts the quote currency into the base token's currency | Only exchange rates observed at or before the close count |
| The converted close rounds to zero at the feed's precision | The feed would record a price of zero |
| The organisation has no operations signer bound to the system | Nothing can sign the feed update |

A close can move after the session ends. A trade that settles late, a bust, or a change to the previous close makes the platform recompute the last five closed sessions of the instrument, and it republishes only the latest close.

### Ticker, candles and live streams [#ticker-candles-and-live-streams]

The ticker gives the latest trade price, the best bid and offer, and the last 24 hours' open, high, low, volume and trade count. It adds the current session's open, high, low, volume and value, with the change from the previous official close. Its 52-week range comes from the daily candles of the last 365 days. Candles come in 1-minute, 5-minute, 15-minute, 1-hour, 4-hour, 1-day and 1-week intervals. By default the platform stores the first six. A deployment can narrow that list but always keeps 1-day candles, and a 1-week candle folds the 1-day candles of its week. A request that names none of `to`, `limit` and `indicators` returns the whole series, at most the newest 1500 buckets. A request that names any of them returns a window of 1 to 500 bars, 500 by default, that ends at the bar holding `to` (now by default), so its last bar is the forming one. A bucket with no trade repeats the previous close with zero volume. A 1-day candle starts at local midnight in the instrument's calendar time zone, or at UTC midnight when the calendar sets no time zone, a 1-week candle starts at Monday midnight in the same zone, and shorter candles start at UTC-aligned times. On the trading desk header, "Open price" is the opening auction price of the current session, or the first trade of the session when the auction set no price, while the first candle on the chart opens at the first trade, so the two can differ.

On the Console and Investor portal charts, the Open, High, Low and Close summary wraps to keep the labels readable in a narrow panel. Working-order labels stay at their order prices in a separate column beside the axis, clear of the candles and the last-price tag. The axis labels the candles at the market's tick precision in equal-width figures, so a price under 4 reads 3.9990 and the separators line up in one column.

The `indicators` parameter takes a comma-separated list of `sma`, `ema`, `vwap`, `bb`, `rsi` and `macd`. The platform computes them over the bars with a trade in the returned window and answers one array per indicator, aligned to the candles. An entry is null while an indicator is still warming up and on every bar without a trade, so a quiet stretch does not pull an average toward the repeated close or narrow the Bollinger bands. The simple and exponential moving averages and the Bollinger bands use the last 20 bars with a trade, the bands sit two standard deviations from the middle, and the RSI uses 14. The MACD uses 12, 26 and 9 unless `macdFast`, `macdSlow` and `macdSignal` set periods from 2 to 200.

Three live streams push changes so that a screen does not poll. Each path below starts with `/api/v2/addons/trading-venues/{venueAddress}`.

| Stream | Who may open it | What it sends |
| --- | --- | --- |
| Instrument stream, `GET .../markets/{marketId}/stream` | Anyone who can see the instrument | A snapshot of the book, then book changes, trades, indicative auction prices, the price band in force with any volatility interruption and when it ends, and each announcement the viewer may read. When settlement undoes a trade the stream already announced, a `trade-undone` frame names the undone trade sequences and carries the ticker figures without them. A heartbeat follows 30 seconds of silence, and the stream ends when the viewer loses access to the instrument |
| Participant order stream, `GET .../order-stream` | A participant, for their own wallets | The caller's open orders, then every change to their orders and trades and each new notification |
| Operator order stream, `GET .../orders/stream` | A venue operator | Every order of the venue, or of one instrument |

Each book change after the snapshot carries the instrument identifier and two positions in that instrument's own event log, `fromSequence` and `toSequence`, which bound the change. Each instrument numbers its own log, so the same pair listed on two venues streams two independent sequences.

The two order streams resume from an event cursor. The platform keeps seven days of order changes for resuming, and a cursor older than that opens a fresh snapshot instead. One caller holds at most eight order streams on one venue in each instance of the Platform API, and the next one is refused with HTTP 429 and `ORDER_STREAM_LIMIT_REACHED` before anything is read. Close a stream you no longer read, then open the new one. A reserved slot whose stream never starts frees after 30 seconds.

### Grouping the order book by a price step [#grouping-the-order-book-by-a-price-step]

The Console and the Investor portal group the order book by a price step in ticks. The options are 1, 2, 5, 10, 50 and 100 ticks of the instrument's own price step, each named by the price it adds up to. When the levels of a book sit 100 ticks or more apart, the same options move up by powers of ten and the one-tick option stays first, so the coarsest step always spans more than one gap between levels. A bucket's price is a multiple of the step, rounded down for bids and up for asks, and its size is the sum of its levels. On a compact desk, where the six options do not fit on one row, the control folds into a single select that lists the same options. A bucket hides its size when any level inside it is hidden.

### Announcements [#announcements]

A venue operator publishes an announcement to the whole venue or to one instrument, in the category "Notice", "Broadcast", "Trading window" or "Corporate action", with the severity "Information", "Warning" or "Critical". An optional display window limits when participants see it. A display-from time in the future schedules the announcement, and the platform publishes it within 15 seconds of that time. An edit keeps the replaced text, the editor, the time and the reason as a numbered revision. An announcement carries up to five PDF attachments, each up to 10 MiB, or a lower limit the deployment sets, and only someone who can see the announcement can download them. A withdrawal cannot be undone.

After its display window ends, an announcement stays readable as history. A participant's plain list answers only what is on display, and `filter[history]=true` lists the notices that have gone on display, including those whose display ended. A participant never receives a withdrawn announcement, a scheduled one or one pending approval. A venue operator's plain list keeps every notice, and `filter[history]` narrows it to the same published notices. The Investor portal shows this history on the **Announcements** page under "Wealth", a table of the venues the investor can see that they filter by category, market and date and in which each row reads "On display" or "Display ended".

An issuer can also publish an announcement about its own security, in the category "Issuer", when the caller holds the token's governance or supply management role. It is sent with the category `issuer` and the security's address, and it names no instrument. The announcement waits as pending approval, invisible to participants, until a venue operator of the submitting venue approves it through the Platform API. It then reaches every visible instrument whose base token is that security, on any venue of the same organisation and network. A venue admin can set daily publication windows for these announcements through the listing rules API. In `warn` mode, which a venue that never set the windows uses, an announcement outside them is accepted with a warning. In `block` mode it is refused with HTTP 422 and `OUTSIDE_PUBLICATION_WINDOW`, error [DALP-14744](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference).

### Watchlists and price alerts [#watchlists-and-price-alerts]

A watchlist belongs to one user in one organisation. Each entry is a token, and it can pin one instrument of that token. A price alert names an instrument and either an absolute price or a percentage move from the instrument's previous official close. It fires once, when a trade prints at or beyond its target, and sends a webhook and a notification. A percentage alert works out its target again from the close in force at each trade, so its level moves with each new session.

## The trading calendar [#the-trading-calendar]

Every instrument opens and closes on a calendar, and the same calendar decides which dates count as trading days for a good-til-date order. A venue calendar holds a time zone, a weekly template of preopen, open and close times, and dated exceptions such as half days. It can extend a shared holiday calendar, and it adds its own closed days. An instrument can replace the venue's weekly template with its own and add its own dated exceptions. A holiday closure always wins: an instrument's own entry for the same date gives way to it, and a closure the venue owns wins over one inherited from a shared calendar. On any other date, an instrument's own dated entry replaces the venue's entry for that date.

The platform generates sessions 90 days ahead. It judges a calendar save on the day each instrument trades, which is the venue and instrument layers combined, not on the layer being saved alone. A day or exception can also carry an optional closing auction time, after the open and before Trade at last or the close, which the calendar occurrence reports as `closingAuctionAt` and an auction-only or private instrument refuses. A day or exception can also carry an optional Trade-At-Last time, after the open and before the close, that starts a post-session in which a public continuous instrument trades only at the last price (see [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue)). The calendar occurrence reports it as `tradeAtLastAt`, and an auction-only or private instrument refuses a calendar that sets it. A save that would leave a combined day in the next 90 days with a preopen after its open, an open at or after its close, a closing auction time outside the open and the Trade-At-Last time or close, or a Trade-At-Last time outside the open and the close is refused. The refusal names up to five affected instruments, each with its first broken date, and counts the rest.

Two reads answer calendar questions, so a client never combines the layers itself. Both paths start with `/api/v2/addons/trading-venues/{venueAddress}`. `GET .../markets/{marketId}/calendar/trading-days` answers, for each date in a range of at most 366 dates, whether the instrument trades and when its session opens and closes. `GET .../markets/{marketId}/calendar/effective-closures` lists every closed date in a range with its name and its `source`: `venue`, `shared-calendar` or `instrument`. A shortened day is not a closure, and neither is a weekday the weekly template never opens. Both reads combine the layers the same way the platform does when it generates sessions, and neither offers a date the schedule skips.

An auction-only instrument has no daily hours. It collects orders over collection windows and clears once, at each window's end. The platform refuses a window that does not start before it ends, does not end in the future, spans more than 90 days, clears on a closed calendar day, overlaps another window, or clears on the same local date as another window. The Console saves a weekly pattern as separate windows for the next 12 weeks, and the platform keeps the pattern and generates windows from it 90 days ahead. [Instrument](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument#a-calendar-override-adds-one-exception-for-today-and-still-needs-saving) covers the operator overrides and a day without a preopen, and [Trading calendar](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trading-calendar) covers the calendar editor.

## How a participant hears about an order [#how-a-participant-hears-about-an-order]

Every venue event that concerns a participant lands in their notification list on the platform, and the same event can also reach them by email. The kinds are an order that filled or partly filled, any other change to an order (expired, cancelled by the venue, rejected, refused at entry), a price alert the participant set that fired, an announcement, and a corporate action.

Email is a choice per kind, made twice. A venue operator sets the organisation default on the "Participant alerts" tab of Venues, and a participant changes their own settings on "Notifications" in the Investor portal. A setting a participant never changed follows the organisation default and the portal marks that row "Your organisation's default". With no organisation default the setting is off, so the organisation decides whether alerts leave the platform at all, and each participant decides which ones reach them. An alert email goes to the participant's email address and names the instrument, side, filled and remaining quantity, average fill price and time. It uses the organisation's theme and time zone, and the participant's own language when the organisation has that language enabled. The platform sends no text message or mobile push alerts.

Delivery runs beside trading rather than inside it. A separate process reads the notification list after the event is committed and sends what the settings allow, so a slow or failing mail server never holds an order, a fill or a settlement. One event reaches a participant once even when it concerns several of their wallets, and an alert that is more than an hour old when delivery first sees it is not sent.

An email also links to the participant's notification settings in the Investor portal, where they turn these emails off after signing in. A mail server refusal is tried again later rather than dropped: the wait doubles from 30 seconds to at most an hour, and delivery gives up after eight attempts. A participant with no email address is not retried, because a later attempt cannot succeed.

The participant's settings are readable and writable through `GET /api/v2/addons/trading-venues/notification-preferences` and `PATCH /api/v2/addons/trading-venues/notification-preferences`, and an organisation default through `GET /api/v2/addons/trading-venues/notification-defaults` and `PATCH /api/v2/addons/trading-venues/notification-defaults`. Any venue operator of the organisation may read them. Only an organisation owner or platform admin may change them, and the change needs the same wallet verification as other venue writes. A change names only the settings it changes, and a null value drops a participant's own choice so the organisation default applies again. The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) carries the request and response shapes.

Without an Investor portal URL, the platform sends no alert email, even when an organisation default enables it, because the recipient has no alert settings page to stop these emails. The delivery is not retried, and the alert stays in the participant's notification list on the Console.

The notification list keeps each notification for 90 days, whatever the email settings say. `GET /api/v2/addons/trading-venues/notifications` returns the caller's notifications newest first, and `unread=true` keeps only the unread ones, which makes its total the unread count. A transition marks one notification read, or every unread one at once. An order the participant cancelled themselves raises no notification, and neither does a cancel the maker may have sent on chain. An announcement notification follows its announcement: a withdrawal deletes it, and an edit updates its title and severity.