Data Streams: Best Practices (Market Hours, etc) (#2873)

dev-dist · web-flow · commit a7b583ae4fb0 · 2025-10-07T14:31:03.000-07:00
* link/nav updates

* update market-hours with guidance

* added notes and marketstatus

* nit: date frontmatter

* nit

* update tables

* removed old price info

* link fix

* added new best practices section, moved market our user recommendations to new section

* broken-link-fix

* update best practices intro text

* remove duplicated content from market-hours -&gt; best practices

* update

* linkfix

* best practices update

* clarify

* further clarification

* feedback

* link fix

* minor nits review

* revert unneeded changes (redirects in place)
diff --git a/src/config/sidebar.ts b/src/config/sidebar.ts
@@ -470,6 +470,10 @@ export const SIDEBAR: Partial<Record<Sections, SectionEntry[]>> = {
           title: "Architecture",
           url: "data-streams/architecture",
         },
+        {
+          title: "Best Practices",
+          url: "data-streams/concepts/best-practices",
+        },
         {
           title: "Liquidity-Weighted Bid and Ask prices",
           url: "data-streams/concepts/liquidity-weighted-prices",
diff --git a/src/content/data-streams/concepts/best-practices.mdx b/src/content/data-streams/concepts/best-practices.mdx
diff --git a/src/content/data-streams/developer-responsibilities.mdx b/src/content/data-streams/developer-responsibilities.mdx
@@ -34,6 +34,8 @@ Developers are responsible for maintaining the security and user experience of t
 
 In particular, developers implementing Chainlink Data Streams in their code and applications are responsible for their application's market integrity and code risks that may cause unanticipated pricing data behavior. These are described below in more detail:
 
+For guidance on mitigations, see the [Data Streams Best Practices](/data-streams/concepts/best-practices) — developers remain solely responsible for their integrations.
+
 ### Market Integrity Risks
 
 Market conditions can impact the pricing behavior of assets in ways beyond the ability of Chainlink node operators to predict or control.
@@ -52,6 +54,17 @@ Under the shared responsibility model, developers must thoroughly understand the
 
 **Data Streams developers are solely responsible for defining and implementing their own risk procedures and systems, including being aware of market open and closing times, and bank holidays, when integrating associated Chainlink Data Streams.**
 
+### Market hours
+
+Some Data Streams reflect assets that trade only during specific market windows or are published with a delay. Developers must not assume 24/7 trading availability for these streams and should implement validations and fallback logic where appropriate:
+
+- Offchain equity and ETF assets are traded only during standard [market hours](/data-streams/market-hours). Do not use these streams outside those windows.
+- Forex (foreign exchange) assets trade only during defined market hours for the pair and, for some currencies, primarily during local banking hours. Do not use Forex streams outside the market hours relevant to the currency pair.
+- UK ETF price streams may be published with a 15-minute delay from their original source. These assets are traded only during standard market hours — do not use UK ETF streams outside their specified trading windows or assume real-time prices.
+- Other assets may have specific market hours defined by their respective exchanges or liquidity providers.
+
+For more information, see the [Market Hours Best Practices](/data-streams/concepts/best-practices#market-hours); developers remain solely responsible for how they use this guidance and for any risks or liabilities resulting from their integrations.
+
 #### DEX-based Assets
 
 Data Streams also provides pricing data related to assets that trade, primarily, on decentralized exchanges (DEXs). Under the Shared Responsibility model, it is essential that developers understand the methodology and risks associated with such DEX-based assets. The risks include, but are not limited to:
diff --git a/src/content/data-streams/market-hours.mdx b/src/content/data-streams/market-hours.mdx
@@ -1,30 +1,73 @@
 ---
 section: dataStreams
-date: Last Modified
+date: "Last Modified"
 title: "Data Streams Market Hours"
 metadata:
   title: "Chainlink Data Streams Market Hours | Trading Hours by Asset Class"
-  description: "Learn about trading hours for different asset classes in Chainlink Data Streams including cryptocurrency, forex, and precious metals market schedules."
-  keywords: ["Market Hours", "Trading Hours", "Crypto", "Forex", "Precious Metals", "Data Streams"]
+  description: "Market-open schedules for Chainlink Data Streams, covering crypto, forex, precious metals, US equities, and commodities."
+  keywords:
+    [
+      "Market Hours",
+      "Trading Hours",
+      "Crypto",
+      "Forex",
+      "Precious Metals",
+      "US Equities",
+      "Commodities",
+      "RWA",
+      "Data Streams",
+    ]
 whatsnext:
   {
     "Find the list of available Crypto streams": "/data-streams/crypto-streams",
     "Find the list of available RWA streams": "/data-streams/rwa-streams",
     "Find the schema of data to expect from Data Streams reports: Crypto": "/data-streams/reference/report-schema-v3",
     "Find the schema of data to expect from Data Streams reports: RWA": "/data-streams/reference/report-schema-v8",
+    "Learn best practices for managing market hours risks": "/data-streams/concepts/best-practices",
   }
 ---
 
-Markets for several assets are actively traded only during certain hours. Listed streams include an attribute describing their market hours.
+import { Aside } from "@components"
 
-## Market hours
+Markets for several assets are actively traded only during certain hours.
 
-| Asset class         | Hours                                                                                                                                                                                                                                                                           |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Crypto**          | 24/7/365 - No market close.                                                                                                                                                                                                                                                     |
-| **Forex**           | 18:00 ET Sunday to 17:00 ET Friday. <br/> The feeds also follow the global Forex market Christmas and New Year's Day holiday schedule. Many non-G12 currencies primarily trade during local market hours. It is recommended to use those feeds only during local trading hours. |
-| **Precious Metals** | 18:00 ET Sunday to 17:00 ET Friday with a one-hour break Monday through Thursday from 17:00 to 18:00. <br/> The feeds also follow the global Forex market holiday schedule for Christmas and New Year's Day.                                                                    |
+---
+
+## Cryptocurrency
+
+Cryptocurrency markets operate continuously, with no designated market close.
+
+| Asset class | Hours                       |
+| ----------- | --------------------------- |
+| **Crypto**  | 24/7/365 — No market close. |
+
+---
+
+## Real-World Asset (RWA) market hours <span id="rwa-market-hours"></span>
+
+RWA markets operate during specific hours, with breaks for holidays and sometimes daily pauses.
+
+{/* prettier-ignore */}
+<Aside type="note" title="marketStatus values">
+  In the [RWA report schema (v8)](/data-streams/reference/report-schema-v8), the <code>marketStatus</code> field indicates market status:<br/>
+  • <code>0</code> → <strong>Unknown</strong><br/>
+  • <code>1</code> → <strong>Closed</strong><br/>
+  • <code>2</code> → <strong>Open</strong><br/>
+  All times are Eastern&nbsp;Time (ET, UTC-05 / UTC-04 DST).
+  </Aside>
+
+| Asset class                                                     | Weekly Open   | Weekly Close  | Daily Breaks \*     | Bank Holidays \*\*                                                                     |
+| --------------------------------------------------------------- | ------------- | ------------- | ------------------- | -------------------------------------------------------------------------------------- |
+| **US Equities**<br/>(top-50 by market cap&nbsp;+ selected ETFs) | **09:30 Mon** | **16:00 Fri** | —                   | [NYSE holiday calendar](https://www.nyse.com/markets/hours-calendars)                  |
+| **FX Majors**<br/>(G10 + KRW, SGD, HKD, CNH …)                  | **17:00 Sun** | **17:00 Fri** | —                   | Jan 1, Dec 25                                                                          |
+| **Precious Metals (Spot)**<br/>(XAU, XAG)                       | **18:00 Sun** | **17:00 Fri** | 17:00–18:00 Mon-Thu | Jan 1, Good Fri, Dec 25                                                                |
+| **Commodities** <br/> (WTI Synthetic Spot)                      | **18:00 Sun** | **17:00 Fri** | 17:00–18:00 Mon-Thu | [NYMEX holiday calendar](https://www.cmegroup.com/tools-information/holiday-calendar/) |
+
+\* Times shown as **HH:MM ET**.  
+\*\* Half-day trading may apply on the eve of certain U.S. holidays (e.g., Jul 3, Nov 28). Consult the linked exchange calendars for exact cut-off times.
+
+---
 
-## Real World Asset market status
+## User Recommendations
 
-Reports for Real World Asset (RWA) streams include the `marketStatus` value, which reflects the DON'S consensus on whether the market is currently open. For additional information, refer to the [RWA report schema](/data-streams/reference/report-schema-v8) page.
+For comprehensive guidance on managing risks related to market hours, market gaps, volatility, and corporate actions, see the [Best Practices](/data-streams/concepts/best-practices#market-hours) page.
diff --git a/src/content/data-streams/reference/report-schema-v10.mdx b/src/content/data-streams/reference/report-schema-v10.mdx
@@ -42,3 +42,4 @@ Chainlink Backed xStock Data Streams adhere to the report schema outlined below.
 - `tokenizedPrice` will be available in an upcoming release of Backed xStock Data Streams. Currently, it will always return `0`.
 - `currentMultiplier` reflects all past corporate actions and is updated only when a new action is activated.
 - `activationDateTime` and `newMultiplier` provide advance notice of upcoming corporate actions, allowing protocols to prepare.
+- See more detailed guidance for handling stock splits in the [Best Practices](/data-streams/concepts/best-practices#handling-stock-splits-for-tokenized-assets) documentation.
diff --git a/src/content/data-streams/reference/report-schema-v8.mdx b/src/content/data-streams/reference/report-schema-v8.mdx
@@ -33,4 +33,7 @@ RWA streams adhere to the report schema outlined below.
 
 **Notes**:
 
+- `marketStatus`:
+  - Users are responsible for handling market status changes in their applications.
+  - For further guidance, refer to the [Market Hours Best Practices](/data-streams/concepts/best-practices#market-hours) documentation.
 - Future RWA streams may use different report schemas.
