# 24/7 US Equities User Guide Source: https://docs.chain.link/data-streams/rwa-streams/24-7-us-equities > For the complete documentation index, see [llms.txt](/llms.txt). > **NOTE: Early access** > > 24/7 US Equities streams are available to a limited set of integrators. To request access, contact > [chainlink\_data\_feeds@smartcontract.com](mailto:chainlink_data_feeds@smartcontract.com). Chainlink 24/7 US Equities Streams keep pricing US equities around the clock, including weekends and US market holidays. The family has two Data Streams products, with one stream per asset per product: - **[24/7 TWAP](#24-7-twap)** publishes a single [TWAP](/data-streams/concepts/twap-streams) price. - **[24/7 for Perpetual Markets](#24-7-for-perpetual-markets)** publishes a fast price for perpetual futures protocols. For lending, use the [24/7 Smoothed Tokenized Equity Feeds](/data-feeds/tokenized-equity-feeds/24-7), which publish the slow price onchain. During the trading week, pricing is built from the same regular, extended, and overnight session data as the [24/5 US Equities streams](/data-streams/rwa-streams/24-5-us-equities-user-guide). When the equity market is closed, the stream switches to an off-hours price derived from perpetual futures markets, then hands back to equity pricing when the market reopens. Unlike the 24/5 streams, you consume one stream per product instead of three session-specific streams, and you do not build session-switching logic yourself. Session selection, transitions, and off-hours pricing happen before the report is produced. Developers are responsible for choosing the appropriate stream and price field and ensuring that the operation and performance of their choice matches expectations. For more information, see the [Developer Responsibilities](/data-streams/developer-responsibilities) guidance. For a side-by-side comparison with the 24/5 streams, see the [US Equities overview](/data-streams/rwa-streams/us-equities#24-5-vs-24-7). ## Schema The family uses two schemas because its products publish different data. TWAP streams publish one TWAP price per asset. Perpetual Markets streams publish the full multi-field report, including fast and slow prices, bid and ask, volumes, and market status. The sections below cover each schema. ### v11: Perpetual Markets Perpetual Markets streams use the [RWA Advanced (v11) schema](/data-streams/reference/report-schema-v11), the same schema as the 24/5 streams. It includes `mid`, `bid`, `ask`, the volume fields, `lastTradedPrice`, and `marketStatus`, so an existing v11 decoder works unchanged. Read [Field behavior by session](#field-behavior-by-session) before integrating, even if you already consume the 24/5 streams. > **CAUTION: lastTradedPrice has a different meaning on 24/7 streams** > > On 24/5 US Equities streams, `lastTradedPrice` is deprecated and should not be used. On 24/7 v11 Perpetual Markets > streams, `lastTradedPrice` carries the **Oracle Price (slow price)** and is fully supported. If you already decode the > 24/5 streams, make sure your logic does not ignore or discard this field. These streams do not carry corporate action fields such as the multiplier and activation fields in the [Tokenized Asset (v10) schema](/data-streams/reference/report-schema-v10). Track corporate actions offchain. ### v2: 24/7 TWAP TWAP streams publish one continuous TWAP price per asset. They use the [v2 schema](/data-streams/reference/report-schema-v2#time-weighted-average-price-twap), which carries a single price field rather than the multi-field [v11 layout](/data-streams/reference/report-schema-v11). See [Available Streams](#available-streams) for the TWAP streams. ## Available Streams The family has two Data Streams products. Choose the one that matches your use case. | Product | Use case | Fields | | :-------------------------------------------------------- | :------------------------------- | :----------------------------------------------------------------------------------------------- | | [24/7 TWAP](#24-7-twap) | Continuous TWAP | One TWAP price ([v2](/data-streams/reference/report-schema-v2#time-weighted-average-price-twap)) | | [24/7 for Perpetual Markets](#24-7-for-perpetual-markets) | Perpetual futures mark and index | `mid`, `bid`, `ask` ([v11](/data-streams/reference/report-schema-v11)) | For lending, use [24/7 Smoothed Tokenized Equity Feeds](/data-feeds/tokenized-equity-feeds/24-7). ### 24/7 TWAP One continuous TWAP price per asset. TWAP streams use the [v2 schema](/data-streams/reference/report-schema-v2#time-weighted-average-price-twap) and do not carry the [v11 price fields](/data-streams/reference/report-schema-v11) described below. See [TWAP Streams](/data-streams/concepts/twap-streams) for how the window is calculated. ### 24/7 for Perpetual Markets These streams use the [v11 schema](/data-streams/reference/report-schema-v11) and publish the fast price (`mid`, `bid`, `ask`) for perpetual futures mark and index prices. ### Asset coverage 24/7 pricing depends on liquid perpetual futures markets during off-hours, so not every US equity is covered. Each asset is reviewed individually before launch, including its off-hours trading volume and how much it would cost to move its off-hours price. This review lowers risk but does not remove it: covered assets can still be manipulated or dislocated during off-hours, and the [risks](#risks) below apply to every one of them. Assets that are not covered remain available on the [24/5 US Equities streams](/data-streams/rwa-streams/24-5-us-equities-user-guide). Coverage will expand as off-hours perpetual futures markets deepen. To request an asset, contact [chainlink\_data\_feeds@smartcontract.com](mailto:chainlink_data_feeds@smartcontract.com). ## Consuming the stream Each asset has one stream per product. Use the tables above to find the stream for your use case, then fetch or stream reports with the Data Streams SDK. Perpetual Markets streams use the [v11 layout](/data-streams/reference/report-schema-v11); TWAP streams use [v2](/data-streams/reference/report-schema-v2#time-weighted-average-price-twap). For lending, use [24/7 Smoothed Tokenized Equity Feeds](/data-feeds/tokenized-equity-feeds/24-7). You do not switch streams by session or by `marketStatus`. - [Sign up for Data Streams](/data-streams/sign-up) to get API credentials - [Look up stream IDs programmatically](/data-streams/reference/data-streams-api/discovery-endpoint), including hidden streams your key is entitled to - [Fetch and decode reports](/data-streams/tutorials/ts-sdk-fetch) with the TypeScript, Go, or Rust SDK - [Stream reports](/data-streams/tutorials/ts-sdk-stream) for a continuous connection - [Verify reports onchain](/data-streams/tutorials/evm-onchain-report-verification) using the verifier addresses in the streams table Two timestamps matter, and they answer different questions: - `observationsTimestamp`: when was the report generated? - `lastSeenTimestampNs`: when did the `mid` price last change? `lastSeenTimestampNs` tracks `mid` only, not `bid`, `ask`, or `lastTradedPrice`. They can differ: a fresh report can carry an older `mid`. Use `observationsTimestamp` to judge report freshness and `lastSeenTimestampNs` to judge `mid` freshness. Use `marketStatus` to determine the session; do not infer it from either timestamp. If `marketStatus = 0` (Unknown), treat the price as unavailable. For field scope and non-monotonic behavior, see [Last Seen Timestamp](/data-streams/reference/report-schema-v11#last-seen-timestamp). The example below reads the slow price (`lastTradedPrice`) for collateral and liquidations from a [v11 stream](/data-streams/reference/report-schema-v11). Use `mid` instead for a perpetual futures mark or index price. For 24/7 TWAP streams, decode the [v2](/data-streams/reference/report-schema-v2#time-weighted-average-price-twap) report and read `price` instead. ### TypeScript ```typescript import { createClient, decodeReport } from "@chainlink/data-streams-sdk" const STALE_AFTER_MS = 5 * 60 * 1000 function isPriceUsable(marketStatus: number, midAgeMs: number): boolean { return marketStatus !== 0 && midAgeMs <= STALE_AFTER_MS } async function getPrice(feedId: string) { const client = createClient({ apiKey, userSecret, endpoint }) const report = await client.getLatestReport(feedId) const decoded = decodeReport(report.fullReport, report.feedID) if (decoded.version !== "V11") throw new Error(`Expected a v11 report, got ${decoded.version}`) const reportAgeMs = Date.now() - report.observationsTimestamp * 1000 const midAgeMs = Number((BigInt(Date.now()) * 1_000_000n - decoded.lastSeenTimestampNs) / 1_000_000n) if (!isPriceUsable(decoded.marketStatus, midAgeMs)) return undefined return { slowPrice: decoded.lastTradedPrice, // collateral, liquidations fastPrice: decoded.mid, // perpetual futures mark or index price reportAgeMs, } } ``` ### Go ```go import ( "context" "fmt" "time" streams "github.com/smartcontractkit/data-streams-sdk/go/v2" feed "github.com/smartcontractkit/data-streams-sdk/go/v2/feed" report "github.com/smartcontractkit/data-streams-sdk/go/v2/report" v11 "github.com/smartcontractkit/data-streams-sdk/go/v2/report/v11" ) const staleAfter = 5 * time.Minute func isPriceUsable(marketStatus uint32, midAge time.Duration) bool { return marketStatus != 0 && midAge <= staleAfter } func getPrice(ctx context.Context, client streams.Client, feedID feed.ID) (*v11.Data, error) { response, err := client.GetLatestReport(ctx, feedID) if err != nil { return nil, err } decoded, err := report.Decode[v11.Data](response.FullReport) if err != nil { return nil, err } d := decoded.Data if !isPriceUsable(d.MarketStatus, time.Since(d.LastSeenTimestampNs)) { return nil, fmt.Errorf("price unavailable: marketStatus=%d", d.MarketStatus) } // d.LastTradedPrice is the slow price; d.Mid is the fast price. return &d, nil } ``` ### Rust ```rust use std::time::{Duration, SystemTime, UNIX_EPOCH}; use chainlink_data_streams_report::feed_id::ID; use chainlink_data_streams_report::report::{decode_full_report, v11::ReportDataV11}; use chainlink_data_streams_sdk::client::Client; const STALE_AFTER: Duration = Duration::from_secs(5 * 60); fn is_price_usable(market_status: u32, mid_age: Duration) -> bool { market_status != 0 && mid_age <= STALE_AFTER } async fn get_price(client: &Client, feed_id: ID) -> Result, Box> { let response = client.get_latest_report(feed_id).await?; let full_report = hex::decode(&response.report.full_report[2..])?; let (_report_context, report_blob) = decode_full_report(&full_report)?; let data = ReportDataV11::decode(&report_blob)?; let now_ms = SystemTime::now().duration_since(UNIX_EPOCH)?.as_millis() as u64; let mid_age = Duration::from_millis(now_ms.saturating_sub(data.last_seen_timestamp_ns / 1_000_000)); if !is_price_usable(data.market_status, mid_age) { return Ok(None); } // data.last_traded_price is the slow price; data.mid is the fast price. Ok(Some(data)) } ``` > **CAUTION: Disclaimer** > > This guide represents an example of using a Chainlink product or service and is provided to help you understand how to > interact with Chainlink's systems and services so that you can integrate them into your own. This template is provided > "AS IS" and "AS AVAILABLE" without warranties of any kind, has not been audited, and may be missing key checks or > error handling to make the usage of the product more clear. Do not use the code in this example in a production > environment without completing your own audits and application of best practices. Neither Chainlink Labs, the > Chainlink Foundation, nor Chainlink node operators are responsible for unintended outputs that are generated due to > errors in code. ## Stream behavior ### Fast price and slow price The [v11 sections](/data-streams/reference/report-schema-v11) from here through [Which price to use](#which-price-to-use) describe the v11 Perpetual Markets streams. TWAP streams use [v2](/data-streams/reference/report-schema-v2#time-weighted-average-price-twap) and are covered in [Available Streams](#available-streams). For lending, use [24/7 Smoothed Tokenized Equity Feeds](/data-feeds/tokenized-equity-feeds/24-7). Both prices are published in every report, during every session, not only on weekends. | Price | v11 field | Behavior | Typical use | | :------------------------ | :------------------ | :----------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ | | Fast price | `mid`, `bid`, `ask` | Tracks the market as closely as the inputs allow. No continuous smoothing, no cap on how quickly it moves. | Perpetual futures mark and index prices, monitoring | | Slow price (Oracle Price) | `lastTradedPrice` | Smoothed, and referenced to the last equity close during off-hours. Follows sustained moves gradually rather than immediately. | Collateral valuation, liquidations, other value-securing uses | The slow price is intentionally lagged against live order books. Do not use it to hedge or execute against a specific venue. ### Market status `marketStatus` identifies which session is active and which source is driving the price. The values match the [24/5 mapping](/data-streams/market-hours#v11-24-5-feeds), but `5` has a different practical meaning on 24/7 streams: prices keep updating. | Value | Status | Hours (ET) | Price source | | :---- | :------------ | :----------------------------------------------- | :------------------------------------ | | `0` | Unknown | N/A | None. Treat as unavailable | | `1` | Pre-market | 4:00 AM–9:30 AM Mon–Fri | Extended hours session | | `2` | Regular hours | 9:30 AM–4:00 PM Mon–Fri | Regular hours session | | `3` | Post-market | 4:00 PM–8:00 PM Mon–Fri | Extended hours session | | `4` | Overnight | 8:00 PM–4:00 AM Sun–Fri | Overnight session | | `5` | Closed | 8:00 PM Fri–8:00 PM Sun, plus US market holidays | Off-hours perpetual futures composite | ### Field behavior by session | Field | Regular and extended hours | Overnight | Closed (off-hours) | Session transitions | | :------------------------ | :---------------------------------- | :----------------------------- | :-------------------------------------------------------- | :----------------------------- | | `mid` | Active session `mid`, unsmoothed | Overnight `mid`, unsmoothed | Off-hours composite `mid` | Smoothed blend between sources | | `bid` / `ask` | Active session values | Overnight session values | Off-hours composite `bid` / `ask` | Smoothed blend between sources | | `lastTradedPrice` | Same as `mid` | EMA of overnight `mid` | Smoothed off-hours price | Smoothed blend between sources | | `lastSeenTimestampNs` | Last `mid` update in active session | Last `mid` update in overnight | Last time an off-hours composite price was received | Active session value | | `bidVolume` / `askVolume` | Active session values | Overnight session values | May be zero. Do not rely on these fields during off-hours | Active session values | | `marketStatus` | `1`, `2`, or `3` | `4` | `5` | Current session | As with the 24/5 streams, `lastSeenTimestampNs` applies to `mid` only. It is not a freshness signal for `bid`, `ask`, the volume fields, or `lastTradedPrice`. ### Which price to use | Use case | Recommended field | Why | | :------------------------------------------------- | :------------------------------- | :------------------------------------------------------------------------------------------ | | Lending collateral, liquidations, borrowing limits | `lastTradedPrice` (slow price) | Less sensitive to short-lived dislocations in thin off-hours markets, at the cost of lag | | Perpetual futures mark or index price | `mid` (fast price), `bid`, `ask` | Tracks the current tradable price without smoothing or caps | | Monitoring and alerting | Both | The gap between fast and slow prices shows how far the market has moved from the slow price | These are different risk profiles served from the same report. If you need the slow price onchain without running your own Data Streams integration, see [24/7 Smoothed Tokenized Equity Feeds](/data-feeds/tokenized-equity-feeds/24-7). ## How pricing works This section describes the v11 Perpetual Markets streams. TWAP streams publish a single price; see the [v2 schema](/data-streams/reference/report-schema-v2#time-weighted-average-price-twap). For lending, use [24/7 Smoothed Tokenized Equity Feeds](/data-feeds/tokenized-equity-feeds/24-7). ### Trading week From the Sunday 8:00 PM ET overnight open to the Friday 8:00 PM ET post-market close, the stream follows the active 24/5 session: pre-market, regular hours, post-market, or overnight. The fast price is the `mid` of that session. The slow price equals the fast price during regular and extended hours, and is an exponential moving average (EMA) of the overnight `mid` during the overnight session, where liquidity is thinnest. Regular, extended, and overnight trading happen on different venues with different levels of liquidity, so the price can shift when one session hands off to the next. The stream smooths each transition over a short window. The one exception is **pre-market into regular hours**: the regular session is the deepest market of the day, and a move at that boundary is almost always real price discovery, so it is passed through unsmoothed. ### Off-hours From the Friday post-market close to the Sunday overnight open, and on US market holidays, no spot equity market is open. During this window the stream prices the asset from **perpetual futures** markets, which keep trading through the weekend. > **CAUTION: Off-hours prices come from derivatives** > > The off-hours price is built entirely from perpetual futures. It is not derived from spot trading in the underlying > shares, and it does not use secondary market prices of tokenized equities, which are too thin to price against safely. The fast price during off-hours is a USD composite of quotes from several perpetual futures venues, weighted toward the more liquid venues. Venues that stop updating drop out. Weighting limits the influence of any one venue, but does not remove it. The composite publishes a `bid` and `ask` as well as a `mid`. If no venue has fresh data, no new off-hours price is computed. The stream does not fabricate a price. The slow price during off-hours is referenced to the last equity close before off-hours begin and follows the fast price gradually. Short-lived dislocations have little effect on it, while sustained moves are followed in full over time, so large moves can take hours to be fully reflected. ### Entering and leaving off-hours When off-hours begins, both prices start from the equity close and blend onto the off-hours price over a short window. When the equity market reopens, both prices blend back onto the equity session price the same way, so there is no step change at either boundary. The true Sunday open is not knowable until the market opens. Expect the published price to close any remaining weekend gap to the live equity market over the short reopen window, not instantly. See [Reopen convergence](#reopen-convergence). ## Risks 24/7 streams remove the need to build session-switching logic, but they do not remove the underlying market risks. They also add risks that the 24/5 streams do not have, mainly from pricing the weekend off derivatives. The [24/5 risks](/data-streams/rwa-streams/24-5-us-equities-user-guide#risks) for overnight data, illiquid sessions, corporate actions, and trading halts still apply during the trading week. The risks below focus on the v11 Perpetual Markets streams. TWAP streams publish a single price; see the [v2 schema](/data-streams/reference/report-schema-v2#time-weighted-average-price-twap). For lending, use [24/7 Smoothed Tokenized Equity Feeds](/data-feeds/tokenized-equity-feeds/24-7). ### Slow price lag The slow price is designed to trail the market during the overnight session and off-hours. It cannot tell a genuine move from a short-lived one when the move first happens, so it follows large moves over a period of time rather than immediately. A large weekend move can take hours to be fully reflected. This reduces liquidations caused by brief dislocations, but it also means liquidations after a sustained move can happen later than they would against a live market price, and can leave room for arbitrage. #### Mitigation - Size loan-to-value ratios, liquidation thresholds, and supply caps for a lagging price, not a real-time one - Monitor the gap between `mid` and `lastTradedPrice`, and alert when it is large or persistent - Test your parameters against historical weekend moves and earnings gaps before going live ### Pre-market to regular hours is a step change Session transitions are smoothed except one: pre-market into regular hours. At 9:30 AM ET the stream passes the move directly through rather than blending it, because a move at that boundary is usually real price discovery. The slow price can step at the open instead of catching up gradually, which is the opposite of its behavior everywhere else. #### Mitigation - Treat 9:30 AM ET as a distinct event when your risk model assumes a lagging slow price - Apply deviation bounds, or pause new borrowing and liquidations briefly around the open, if a step change would be unsafe - Test parameters against days with large pre-market moves and earnings releases ### Off-hours prices come from perpetual futures A perpetual futures contract is a derivative. Its price can carry a basis to the underlying shares, influenced by funding rates and by each venue's contract design. Venues occasionally change contract specifications, including index construction and funding mechanics. Weekend perpetual futures volumes are also a fraction of weekday spot volumes, so it can take less capital to move them. Off-hours prices can be manipulated, and smoothing in the slow price reduces the effect but does not prevent it. #### Mitigation - Treat the off-hours price as an estimate of where the equity would trade, not as a traded price - Apply tighter exposure limits or supply caps during `marketStatus = 5` - Do not assume the off-hours price will match the reopen price ### Single provider and single venue dependencies Two separate single-source dependencies exist: - **Overnight:** As with the 24/5 streams, only one traditional venue trades during the overnight session. - **Off-hours:** Perpetual futures data is currently delivered through a single data provider. Using several venues reduces the impact of a bad price on one exchange, but does not help with an outage or bad data at the provider. If the provider stops delivering data, no new off-hours price can be computed. If it delivers incorrect data, cross-venue checks reduce the impact but cannot remove it. #### Mitigation - Check `lastSeenTimestampNs` against your own staleness threshold during off-hours - Define what your protocol does when no fresh price is available: pause new borrowing, hold the last valid price within bounds, or both ### Fewer contributing venues The composite keeps publishing as venues drop out. A price built from all venues and a price built from one or two are published the same way, but they are not equally robust. With fewer venues, the remaining ones have more influence and the cost to move the price falls. #### Mitigation - Monitor the fast price against independent references during off-hours - Apply value bounds and per-update deviation limits ### Slow price unavailable The slow price depends on the last equity close and on a continuous series of inputs. Two cases matter: - **Missing close:** If the equity close cannot be determined at the start of off-hours, for example because the final equity reports before the close are missing, the stream cannot produce a slow price for that off-hours period. In the worst case, an entire weekend can go without a slow price. - **Interrupted inputs:** If inputs are missing for too long, the slow price stops updating, and it needs a recovery period after inputs return before it publishes again. Before it stops, the last value may be repeated for a short time, so a slow price that is not moving is not proof that it is current. #### Mitigation - Define protocol behavior for an unavailable slow price before going live, including a full-weekend outage - Pause new borrowing and size liquidation buffers to tolerate a stale valuation - Alert on a flat `lastTradedPrice` while `mid` keeps moving ### Reopen convergence The true reopen price is only known when the equity market opens. At the reopen, both prices close any remaining weekend gap to the equity market over a short window. Positions that degraded over the weekend can still become liquidatable around the reopen, just not in a single jump. #### Mitigation - Account for the reopen window in latency-sensitive logic - Consider tighter limits on new positions in the minutes before and after the Sunday 8:00 PM ET open ### Corporate actions over a weekend Splits, reverse splits, large special dividends, and symbol changes can move the true price sharply at the reopen. During off-hours, perpetual futures may price the event before the equity market does, and the slow price will follow that move slowly because it is referenced to the pre-event close. The stream does not adjust for corporate actions. #### Mitigation - Monitor corporate action announcements for the assets you support - Pause markets or adjust parameters around corporate action dates ### Market holidays and halts Market holidays are priced as off-hours (`marketStatus = 5`). Trading halts only occur while the market is open and are not flagged in `marketStatus`. During a halt, `marketStatus` shows the active session while `lastSeenTimestampNs` stops advancing. A halt that runs into a scheduled open holds the transition until the equity price resumes. #### Mitigation - Use an authoritative exchange holiday calendar alongside `marketStatus` - Monitor exchange halt notices independently For trading schedules, see [Market Hours](/data-streams/market-hours#24-7-us-equities). ## Support For inquiries related to a data outage, contact Chainlink Labs at [data\_support@chain.link](mailto:data_support@chain.link).