From 100a1771513d3a5896daacee62bbd4b83983b0bc Mon Sep 17 00:00:00 2001 From: Devin DiStefano Date: Mon, 4 Aug 2025 07:23:35 -0700 Subject: [PATCH 01/11] link/nav updates --- public/samples/DataStreams/StreamsUpkeep.sol | 2 +- public/samples/DataStreams/StreamsUpkeepRegistrar.sol | 2 +- public/samples/DataStreams/StreamsUpkeepWithErrorHandler.sol | 2 +- src/content/chainlink-automation/llms-full.txt | 2 +- src/content/data-streams/reference/report-schema-v3-dex.mdx | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/public/samples/DataStreams/StreamsUpkeep.sol b/public/samples/DataStreams/StreamsUpkeep.sol index a90b64ac1e8..fe066db07fc 100644 --- a/public/samples/DataStreams/StreamsUpkeep.sol +++ b/public/samples/DataStreams/StreamsUpkeep.sol @@ -64,7 +64,7 @@ contract StreamsUpkeep is ILogAutomation, StreamsLookupCompatibleInterface { * @dev Represents a data report from a Data Streams stream for v3 schema (used for crypto and DEX State Price streams). * The `price`, `bid`, and `ask` values are carried to either 8 or 18 decimal places, depending on the stream. * `bid`, and `ask` values are not available for DEX State Price streams. - * For more information, see https://docs.chain.link/data-streams/crypto-streams and https://docs.chain.link/data-streams/reference/report-schema + * For more information, see https://docs.chain.link/data-streams/crypto-streams and https://docs.chain.link/data-streams/reference/report-schema-v3 */ struct ReportV3 { bytes32 feedId; // The stream ID the report has data for. diff --git a/public/samples/DataStreams/StreamsUpkeepRegistrar.sol b/public/samples/DataStreams/StreamsUpkeepRegistrar.sol index 35a7db0b7f3..03801aaef6c 100644 --- a/public/samples/DataStreams/StreamsUpkeepRegistrar.sol +++ b/public/samples/DataStreams/StreamsUpkeepRegistrar.sol @@ -91,7 +91,7 @@ contract StreamsUpkeepRegistrar is * @dev Represents a data report from a stream for v3 schema (crypto and DEX State Price streams). * The `price`, `bid`, and `ask` values are carried to either 8 or 18 decimal places, depending on the stream. * `bid`, and `ask` values are not available for DEX State Price streams. - * For more information, see https://docs.chain.link/data-streams/crypto-streams and https://docs.chain.link/data-streams/reference/report-schema + * For more information, see https://docs.chain.link/data-streams/crypto-streams and https://docs.chain.link/data-streams/reference/report-schema-v3 */ struct ReportV3 { bytes32 feedId; // The feed ID the report has data for. diff --git a/public/samples/DataStreams/StreamsUpkeepWithErrorHandler.sol b/public/samples/DataStreams/StreamsUpkeepWithErrorHandler.sol index 8a3cf856887..1ef2cae8505 100644 --- a/public/samples/DataStreams/StreamsUpkeepWithErrorHandler.sol +++ b/public/samples/DataStreams/StreamsUpkeepWithErrorHandler.sol @@ -74,7 +74,7 @@ contract StreamsUpkeepWithErrorHandler is /** * @dev Represents a data report from a Data Streams feed for v3 schema (crypto streams). * The `price`, `bid`, and `ask` values are carried to either 8 or 18 decimal places, depending on the feed. - * For more information, see https://docs.chain.link/data-streams/crypto-streams and https://docs.chain.link/data-streams/reference/report-schema + * For more information, see https://docs.chain.link/data-streams/crypto-streams and https://docs.chain.link/data-streams/reference/report-schema-v3 */ struct ReportV3 { bytes32 feedId; // The feed ID the report has data for. diff --git a/src/content/chainlink-automation/llms-full.txt b/src/content/chainlink-automation/llms-full.txt index 48ef46fe21a..43e0138c345 100644 --- a/src/content/chainlink-automation/llms-full.txt +++ b/src/content/chainlink-automation/llms-full.txt @@ -1646,7 +1646,7 @@ contract StreamsUpkeep is ILogAutomation, StreamsLookupCompatibleInterface { /** * @dev Represents a data report from a Data Streams stream for v3 schema (crypto streams). * The `price`, `bid`, and `ask` values are carried to either 8 or 18 decimal places, depending on the stream. - * For more information, see https://docs.chain.link/data-streams/crypto-streams and https://docs.chain.link/data-streams/reference/report-schema + * For more information, see https://docs.chain.link/data-streams/crypto-streams and https://docs.chain.link/data-streams/reference/report-schema-v3 */ struct ReportV3 { bytes32 feedId; // The stream ID the report has data for. diff --git a/src/content/data-streams/reference/report-schema-v3-dex.mdx b/src/content/data-streams/reference/report-schema-v3-dex.mdx index 64f842ae1c1..8ebda038027 100644 --- a/src/content/data-streams/reference/report-schema-v3-dex.mdx +++ b/src/content/data-streams/reference/report-schema-v3-dex.mdx @@ -13,7 +13,7 @@ import { PageTabs } from "@components" pages={[ { name: "Cryptocurrency Report Schema (v3)", - url: "/data-streams/reference/report-schema", + url: "/data-streams/reference/report-schema-v3", }, { name: "DEX State Price Report Schema (v3)", From 0572748a3a50b330dddd205bd1bc4e5f5f9e515a Mon Sep 17 00:00:00 2001 From: Devin DiStefano Date: Mon, 4 Aug 2025 18:35:19 -0700 Subject: [PATCH 02/11] update market-hours with guidance --- src/content/data-streams/market-hours.mdx | 204 ++++++++++++++++++++-- 1 file changed, 192 insertions(+), 12 deletions(-) diff --git a/src/content/data-streams/market-hours.mdx b/src/content/data-streams/market-hours.mdx index a38af0e30f9..02c1a3cc7be 100644 --- a/src/content/data-streams/market-hours.mdx +++ b/src/content/data-streams/market-hours.mdx @@ -1,11 +1,22 @@ --- section: dataStreams -date: Last Modified +date: "2025-08-04" 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", @@ -15,16 +26,185 @@ whatsnext: } --- -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.
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.
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 + +RWA markets operate during specific hours, with breaks for holidays and sometimes daily pauses. + +{/* prettier-ignore */} + + +| Asset class | Weekly Open | Weekly Close | Daily Breaks \* | Bank Holidays \*\* | +| --------------------------------------------------------------- | ------------- | ------------- | ------------------- | -------------------------------------------------------------------------------------- | +| **US Equities**
(top-50 by market cap + selected ETFs) | **09:30 Mon** | **16:00 Fri** | — | [NYSE holiday calendar](https://www.nyse.com/markets/hours-calendars) | +| **FX Majors**
(G10 + KRW, SGD, HKD, CNH …) | **17:00 Sun** | **17:00 Fri** | — | Jan 1, Dec 25 | +| **Precious Metals (Spot)**
(XAU, XAG) | **18:00 Sun** | **17:00 Fri** | 17:00–18:00 Mon-Thu | Jan 1, Good Fri, Dec 25 | +| **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. + +--- + +### User Recommendations + +The following sections outline common market issues related to RWA trading hours, and how users can mitigate risks. + +Users should also consult the [Developer Responsibility page](/data-streams/developer-responsibility) to understand the risks associated with both market integrity and application code. + +#### Market gaps + +Market gaps occur when there are interruptions in trading or price discovery, leading to periods where the last available price may not reflect current market conditions. These gaps can create risks, particularly around market opens, closures, and unexpected disruptions. + +##### Market close + +Large price jumps between trading sessions due to after-hours news. + +A large price jump at market open could cause sudden liquidations, potentially leaving the perpetual DEX with bad debt if a trader’s collateral is insufficient to cover the losses. + +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| | Keep markets **closed** while `marketStatus = 1` to prevent users trading at unfair prices.
Set leverage in line with the asset’s average volatility to avoid bad debt. | + +##### Price formation at open/close + +Certain assets (e.g., FX open on Sunday afternoon) experience gradual price discovery due to fragmented liquidity and delayed trading activity. + +The perpetual DEX should be careful of not opening their market with the last close price. + +| Data Stream behavior | User guidance | +| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | +| | Wait until `lastUpdateTimestamp` is current before opening the market so traders don't execute on stale quotes. | + +##### Sudden failures + +Unexpected system outages, order execution failures, or data feed disruptions can occur. + +The price will be flat during that period, meaning if a perp DEX lacks a mechanism to handle halts, it may struggle to determine fair prices thus leading to unpredictable liquidations. + +| Data Stream behavior | User guidance | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | +| | Decide whether to allow users to open/close positions when `marketStatus = 2` but `lastUpdateTimestamp` is stale. | + +##### Trading halts + +Stocks can be halted due to extreme volatility (e.g., limit up/down rules) or regulatory actions. + +The price will be flat during that period, meaning if a perp DEX lacks a mechanism to handle halts, it may struggle to determine fair prices thus leading to unpredictable liquidations. + +| Data Stream behavior | User guidance | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- | +| | Pause trading while the price is frozen; reopen only once fresh quotes resume. | + +--- + +#### Volatility & low liquidity + +During periods of high volatility or low liquidity, price movements can become unpredictable and exaggerated. These conditions can increase the risk of sudden liquidations and bad debt accumulation, requiring careful risk management strategies. + +##### Algorithmic & HFT activity + +Rapid-fire trading by algos can create unpredictable price movements. + +High volatility can lead to liquidation and potential bad debt accumulation. + +| Data Stream behavior | User guidance | +| :-------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | +| | Monitor liquidation thresholds closely to prevent accumulating bad debt. | + +##### Low liquidity at open/close + +Reduced market depth at trading session transitions can lead to higher volatility and spreads. + +High volatility can lead to liquidation and potential bad debt accumulation. + +| Data Stream behavior | User guidance | +| :-------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | +| | Widen spreads or funding rates, or briefly delay market open to let liquidity build. | + +--- + +#### Corporate actions + +Corporate actions are events initiated by publicly traded companies that can significantly impact stock prices and trading behavior. These actions are usually announced outside regular trading hours and can cause substantial price movements when markets reopen. Users should monitor these events closely as they can lead to sudden price adjustments that may trigger unexpected liquidations or require position modifications. + +##### Bankruptcy & delisting + +Bankruptcy can lead to delisting or complete loss of equity value. + +Delisting will zero out prices for the asset. + +| Data Stream behavior | User guidance | +| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- | +| | Monitor delisting news during status = 1 and close markets permanently once confirmed. | + +##### Spin-offs + +When a company spins off a business unit into a separate publicly traded entity, the parent company’s stock may adjust accordingly, while the spun-off company’s shares begin trading independently. + +Positions may need to be manually adjusted if the DEX doesn’t support tracking the new entity. + +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- | +| | Pause markets if the first post-spin price moves by more than X % from the previous close; adjust positions before reopening. | + +##### Stock splits & reverse splits + +A stock split increases the number of shares while reducing the price per share (e.g., 2-for-1 split), often making shares more accessible to investors. A reverse split does the opposite, consolidating shares to increase the price per share. + +A 2-for-1 split would reduce the price by 50% from the previous trading session, any leveraged user could get liquidated. + +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- | +| | Handle like spin-offs—pause & adjust positions, or temporarily disable leverage. | + +##### Mergers & acquisitions (M&A) + +If a company is being acquired, its stock price may rise to reflect the acquisition premium. The acquiring company’s stock might fluctuate based on investor sentiment regarding the deal’s financial and strategic impact. + +Announcements can cause sharp price spikes or sustained moves. + +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------ | +| | Widen spreads and monitor liquidation thresholds closely during announcement periods. | + +##### Share buybacks & stock issuance + +Reduced share supply from a buyback can drive stock prices higher, while increase in share supply can lead to price dilution. + +Announcements can cause sharp price spikes or sustained moves. + +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------- | +| | Monitor liquidation thresholds; adjust risk parameters as needed. | + +##### Dividends + +A company's stock price typically adjusts to reflect dividend payments. For example, when a company declares a 10% dividend, its stock price often drops by a similar amount on the ex-dividend date, as new buyers are no longer entitled to that dividend. -## Real World Asset market status +Announcements can cause sharp price spikes or sustained moves. -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. +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------- | +| | Adjust funding rates and leverage limits around ex-dividend dates to avoid unfair liquidations. | From 1309f9fe277c182397b49f4671b290636b0bbfe4 Mon Sep 17 00:00:00 2001 From: Devin DiStefano Date: Mon, 4 Aug 2025 18:40:46 -0700 Subject: [PATCH 03/11] added notes and marketstatus --- src/content/data-streams/reference/report-schema-v8.mdx | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/content/data-streams/reference/report-schema-v8.mdx b/src/content/data-streams/reference/report-schema-v8.mdx index fbb227d45e4..735874a2f59 100644 --- a/src/content/data-streams/reference/report-schema-v8.mdx +++ b/src/content/data-streams/reference/report-schema-v8.mdx @@ -45,3 +45,12 @@ RWA streams adhere to the report schema outlined below. | `lastUpdateTimestamp` | `uint64` | Timestamp of the last valid price update | | `midPrice` | `int192` | DON's consensus median price | | `marketStatus` | `uint32` | [Market status](/data-streams/market-hours). Possible values: `0` (`Unknown`), `1` (`Closed`), `2` (`Open`) | + +**Notes**: + +- `midPrice`: + - Chainlink provides real time market prices for a given RWA asset at any given time. + - RWA Streams aggregates the mid, last traded, and bid-ask average price across leading brokers and venues, which source liquidity from major providers. +- `marketStatus`: + - Users are responsible for handle market status changes in their applications. + - For further guidance, refer to the [User Recommendations section in the Market Hours](/data-streams/market-hours#rwa-recommendations) documentation. From ee8d8a4667d868def1fb399fab710cde319bca46 Mon Sep 17 00:00:00 2001 From: Devin DiStefano Date: Mon, 4 Aug 2025 18:42:51 -0700 Subject: [PATCH 04/11] nit: date frontmatter --- src/content/data-streams/market-hours.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/data-streams/market-hours.mdx b/src/content/data-streams/market-hours.mdx index 02c1a3cc7be..f9b23f7bfe6 100644 --- a/src/content/data-streams/market-hours.mdx +++ b/src/content/data-streams/market-hours.mdx @@ -1,6 +1,6 @@ --- section: dataStreams -date: "2025-08-04" +date: "Last Modified" title: "Data Streams Market Hours" metadata: title: "Chainlink Data Streams Market Hours | Trading Hours by Asset Class" From 33d8217c2cb727e193ed46391c04eaf4268053dc Mon Sep 17 00:00:00 2001 From: Devin DiStefano Date: Mon, 4 Aug 2025 18:53:37 -0700 Subject: [PATCH 05/11] nit --- src/content/data-streams/market-hours.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/data-streams/market-hours.mdx b/src/content/data-streams/market-hours.mdx index f9b23f7bfe6..0f9e8fab06a 100644 --- a/src/content/data-streams/market-hours.mdx +++ b/src/content/data-streams/market-hours.mdx @@ -60,7 +60,7 @@ RWA markets operate during specific hours, with breaks for holidays and sometime | **US Equities**
(top-50 by market cap + selected ETFs) | **09:30 Mon** | **16:00 Fri** | — | [NYSE holiday calendar](https://www.nyse.com/markets/hours-calendars) | | **FX Majors**
(G10 + KRW, SGD, HKD, CNH …) | **17:00 Sun** | **17:00 Fri** | — | Jan 1, Dec 25 | | **Precious Metals (Spot)**
(XAU, XAG) | **18:00 Sun** | **17:00 Fri** | 17:00–18:00 Mon-Thu | Jan 1, Good Fri, Dec 25 | -| **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/) | +| **Commodities**
(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. From be41e06f0146109e98182a86c8e7947fcba2f035 Mon Sep 17 00:00:00 2001 From: Devin DiStefano Date: Mon, 4 Aug 2025 19:07:39 -0700 Subject: [PATCH 06/11] update tables --- src/content/data-streams/market-hours.mdx | 54 +++++++++++------------ 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/src/content/data-streams/market-hours.mdx b/src/content/data-streams/market-hours.mdx index 0f9e8fab06a..cb897812643 100644 --- a/src/content/data-streams/market-hours.mdx +++ b/src/content/data-streams/market-hours.mdx @@ -83,9 +83,9 @@ Large price jumps between trading sessions due to after-hours news. A large price jump at market open could cause sudden liquidations, potentially leaving the perpetual DEX with bad debt if a trader’s collateral is insufficient to cover the losses. -| Data Stream behavior | User guidance | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -|
  • `midPrice`: Closing price is repeated until market open.
  • `marketStatus`: 1 = Market Closed.
  • `lastUpdateTimestamp`: Timestamp of the closing price of the last session.
| Keep markets **closed** while `marketStatus = 1` to prevent users trading at unfair prices.
Set leverage in line with the asset’s average volatility to avoid bad debt. | +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|
  • `midPrice`: Closing price is repeated until market open.
  • `marketStatus`: 1 = Market Closed.
  • `lastUpdateTimestamp`: Timestamp of the closing price of the last session.
| Keep markets closed while `marketStatus = 1` to prevent users trading at unfair prices.

Leverage available should be set in line with the asset average volatility to avoid bad debt if a trader’s collateral is insufficient to cover the losses. | ##### Price formation at open/close @@ -113,9 +113,9 @@ Stocks can be halted due to extreme volatility (e.g., limit up/down rules) or re The price will be flat during that period, meaning if a perp DEX lacks a mechanism to handle halts, it may struggle to determine fair prices thus leading to unpredictable liquidations. -| Data Stream behavior | User guidance | -| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- | -|
  • `midPrice`: Last mid-price is repeated until a new price is available.
  • `marketStatus`: `2` (Market Open).
  • `lastUpdateTimestamp`: Timestamp of the last mid-price.
| Pause trading while the price is frozen; reopen only once fresh quotes resume. | +| Data Stream behavior | User guidance | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | +|
  • `midPrice`: Last mid-price is repeated until a new price is available.
  • `marketStatus`: `2` (Market Open).
  • `lastUpdateTimestamp`: Timestamp of the last mid-price.
| Decide whether to allow users to open/close positions when `marketStatus = 2` but `lastUpdateTimestamp` is stale. | --- @@ -139,9 +139,9 @@ Reduced market depth at trading session transitions can lead to higher volatilit High volatility can lead to liquidation and potential bad debt accumulation. -| Data Stream behavior | User guidance | -| :-------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | -|
  • `midPrice`: Current mid price.
  • `marketStatus`: `2` (Market Open).
  • `lastUpdateTimestamp`: Current timestamp.
| Widen spreads or funding rates, or briefly delay market open to let liquidity build. | +| Data Stream behavior | User guidance | +| :-------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | +|
  • `midPrice`: Current mid price.
  • `marketStatus`: `2` (Market Open).
  • `lastUpdateTimestamp`: Current timestamp.
| Monitor liquidation thresholds closely to prevent accumulating bad debt. | --- @@ -155,9 +155,9 @@ Bankruptcy can lead to delisting or complete loss of equity value. Delisting will zero out prices for the asset. -| Data Stream behavior | User guidance | -| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- | -|
  • `midPrice`: Closing price is repeated until a new price is available.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Closing timestamp of the last session.
| Monitor delisting news during status = 1 and close markets permanently once confirmed. | +| Data Stream behavior | User guidance | +| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- | +|
  • `midPrice`: Closing price is repeated until a new price is available.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Closing timestamp of the last session.
| Monitor delisting news during `marketStatus` = `1` and close markets permanently once confirmed. | ##### Spin-offs @@ -165,9 +165,9 @@ When a company spins off a business unit into a separate publicly traded entity, Positions may need to be manually adjusted if the DEX doesn’t support tracking the new entity. -| Data Stream behavior | User guidance | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- | -|
  • `midPrice`: Closing price is repeated until the first post-spin trade.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Last close.
| Pause markets if the first post-spin price moves by more than X % from the previous close; adjust positions before reopening. | +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|
  • `midPrice`: Closing price is repeated until the first post-spin trade.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Last close.
| Monitor spin-off and split announcements while `marketStatus = 1`.

Auto-pause the market if the first post-event price moves by more than X% from the prior close, update positions, then reopen.

If automatic adjustment isn’t possible, disable leverage during the event window to prevent unfair liquidations. | ##### Stock splits & reverse splits @@ -175,9 +175,9 @@ A stock split increases the number of shares while reducing the price per share A 2-for-1 split would reduce the price by 50% from the previous trading session, any leveraged user could get liquidated. -| Data Stream behavior | User guidance | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- | -|
  • `midPrice`: Closing price is repeated until the split-adjusted price prints.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Last close.
| Handle like spin-offs—pause & adjust positions, or temporarily disable leverage. | +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|
  • `midPrice`: Closing price is repeated until the split-adjusted price prints.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Last close.
| Monitor spin-off and split announcements while `marketStatus = 1`.

Auto-pause the market if the first post-event price moves by more than X% from the prior close, update positions, then reopen.

If automatic adjustment isn’t possible, disable leverage during the event window to prevent unfair liquidations. | ##### Mergers & acquisitions (M&A) @@ -185,9 +185,9 @@ If a company is being acquired, its stock price may rise to reflect the acquisit Announcements can cause sharp price spikes or sustained moves. -| Data Stream behavior | User guidance | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------ | -|
  • `midPrice`: Closing price is repeated until a new price prints.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Last close.
| Widen spreads and monitor liquidation thresholds closely during announcement periods. | +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------- | +|
  • `midPrice`: Closing price is repeated until a new price prints.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Last close.
| Monitor liquidation thresholds closely to prevent accumulating bad debt. | ##### Share buybacks & stock issuance @@ -195,9 +195,9 @@ Reduced share supply from a buyback can drive stock prices higher, while increas Announcements can cause sharp price spikes or sustained moves. -| Data Stream behavior | User guidance | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------- | -|
  • `midPrice`: Closing price is repeated until a new price prints.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Last close.
| Monitor liquidation thresholds; adjust risk parameters as needed. | +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------- | +|
  • `midPrice`: Closing price is repeated until a new price prints.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Last close.
| Monitor liquidation thresholds closely to prevent accumulating bad debt. | ##### Dividends @@ -205,6 +205,6 @@ A company's stock price typically adjusts to reflect dividend payments. For exam Announcements can cause sharp price spikes or sustained moves. -| Data Stream behavior | User guidance | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------- | -|
  • `midPrice`: Closing price is repeated until the ex-date trade prints.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Last close.
| Adjust funding rates and leverage limits around ex-dividend dates to avoid unfair liquidations. | +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------- | +|
  • `midPrice`: Closing price is repeated until the ex-date trade prints.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Last close.
| Monitor liquidation thresholds closely to prevent accumulating bad debt. | From 819f9e541dc978656b153dedd4714dfc2b1ab555 Mon Sep 17 00:00:00 2001 From: Devin DiStefano Date: Tue, 5 Aug 2025 09:37:55 -0700 Subject: [PATCH 07/11] removed old price info --- src/content/data-streams/reference/report-schema-v8.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/content/data-streams/reference/report-schema-v8.mdx b/src/content/data-streams/reference/report-schema-v8.mdx index 735874a2f59..65c8cb377a2 100644 --- a/src/content/data-streams/reference/report-schema-v8.mdx +++ b/src/content/data-streams/reference/report-schema-v8.mdx @@ -48,9 +48,6 @@ RWA streams adhere to the report schema outlined below. **Notes**: -- `midPrice`: - - Chainlink provides real time market prices for a given RWA asset at any given time. - - RWA Streams aggregates the mid, last traded, and bid-ask average price across leading brokers and venues, which source liquidity from major providers. - `marketStatus`: - Users are responsible for handle market status changes in their applications. - For further guidance, refer to the [User Recommendations section in the Market Hours](/data-streams/market-hours#rwa-recommendations) documentation. From 561aa5fedfadacb5a2bd6af4216d21217c491b1f Mon Sep 17 00:00:00 2001 From: Devin DiStefano Date: Fri, 8 Aug 2025 01:03:39 -0700 Subject: [PATCH 08/11] link fix --- src/content/data-streams/market-hours.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/data-streams/market-hours.mdx b/src/content/data-streams/market-hours.mdx index cb897812643..3811d7528bd 100644 --- a/src/content/data-streams/market-hours.mdx +++ b/src/content/data-streams/market-hours.mdx @@ -71,7 +71,7 @@ RWA markets operate during specific hours, with breaks for holidays and sometime The following sections outline common market issues related to RWA trading hours, and how users can mitigate risks. -Users should also consult the [Developer Responsibility page](/data-streams/developer-responsibility) to understand the risks associated with both market integrity and application code. +Users should also consult the [Developer Responsibility page](/data-streams/developer-responsibilities) to understand the risks associated with both market integrity and application code. #### Market gaps From e90dffc610c2aa26ce680470a86d7b201329193c Mon Sep 17 00:00:00 2001 From: Devin DiStefano Date: Sun, 10 Aug 2025 13:28:22 -0700 Subject: [PATCH 09/11] added new best practices section, moved market our user recommendations to new section --- src/config/sidebar.ts | 4 + .../data-streams/concepts/best-practices.mdx | 184 ++++++++++++++++++ src/content/data-streams/market-hours.mdx | 10 +- 3 files changed, 197 insertions(+), 1 deletion(-) create mode 100644 src/content/data-streams/concepts/best-practices.mdx diff --git a/src/config/sidebar.ts b/src/config/sidebar.ts index b86099f1240..a086f9c3c61 100644 --- a/src/config/sidebar.ts +++ b/src/config/sidebar.ts @@ -416,6 +416,10 @@ export const SIDEBAR: Partial> = { 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 new file mode 100644 index 00000000000..ec7630ab66f --- /dev/null +++ b/src/content/data-streams/concepts/best-practices.mdx @@ -0,0 +1,184 @@ +--- +section: dataStreams +date: "Last Modified" +title: "Data Streams Best Practices" +metadata: + title: "Chainlink Data Streams Best Practices | Risk Management and Implementation Guide" + description: "Best practices for using Chainlink Data Streams effectively, including market hours management, risk mitigation strategies, and robust application development." + keywords: + [ + "Best Practices", + "Data Streams", + "Risk Management", + "Market Hours", + "Trading Hours", + "Market Gaps", + "Volatility", + "Corporate Actions", + "RWA", + "Crypto", + ] +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 about Data Streams market hours and schedules": "/data-streams/market-hours", + } +--- + +import { Aside } from "@components" + +This guide provides best practices and recommendations for using Chainlink Data Streams effectively. Understanding these practices is crucial for building robust applications that handle various market conditions, edge cases, and potential risks. + + + +--- + +## Market Hours Best Practices + +Markets for Real-World Assets (RWA) operate during specific hours and are subject to various market conditions that can create risks for applications. The following sections outline common market issues and how to mitigate them. + + + +### Market gaps + +Market gaps occur when there are interruptions in trading or price discovery, leading to periods where the last available price may not reflect current market conditions. These gaps can create risks, particularly around market opens, closures, and unexpected disruptions. + +#### Market close + +Large price jumps between trading sessions due to after-hours news. + +A large price jump at market open could cause sudden liquidations, potentially leaving the perpetual DEX with bad debt if a trader's collateral is insufficient to cover the losses. + +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|
  • `midPrice`: Closing price is repeated until market open.
  • `marketStatus`: 1 = Market Closed.
  • `lastUpdateTimestamp`: Timestamp of the closing price of the last session.
| Keep markets closed while `marketStatus = 1` to prevent users trading at unfair prices.

Leverage available should be set in line with the asset average volatility to avoid bad debt if a trader's collateral is insufficient to cover the losses. | + +#### Price formation at open/close + +Certain assets (e.g., FX open on Sunday afternoon) experience gradual price discovery due to fragmented liquidity and delayed trading activity. + +The perpetual DEX should be careful of not opening their market with the last close price. + +| Data Stream behavior | User guidance | +| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | +|
  • `midPrice`: Closing price is repeated until a bid/ask becomes available or a transaction occurs.
  • `marketStatus`: `2` (Market Open).
  • `lastUpdateTimestamp`: Timestamp of the closing price of the last session.
| Wait until `lastUpdateTimestamp` is current before opening the market so traders don't execute on stale quotes. | + +#### Sudden failures + +Unexpected system outages, order execution failures, or data feed disruptions can occur. + +The price will be flat during that period, meaning if a perp DEX lacks a mechanism to handle halts, it may struggle to determine fair prices thus leading to unpredictable liquidations. + +| Data Stream behavior | User guidance | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | +|
  • `midPrice`: Last mid-price is repeated until a new price is available.
  • `marketStatus`: `2` (Market Open).
  • `lastUpdateTimestamp`: Timestamp of the last mid-price.
| Decide whether to allow users to open/close positions when `marketStatus = 2` but `lastUpdateTimestamp` is stale. | + +#### Trading halts + +Stocks can be halted due to extreme volatility (e.g., limit up/down rules) or regulatory actions. + +The price will be flat during that period, meaning if a perp DEX lacks a mechanism to handle halts, it may struggle to determine fair prices thus leading to unpredictable liquidations. + +| Data Stream behavior | User guidance | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | +|
  • `midPrice`: Last mid-price is repeated until a new price is available.
  • `marketStatus`: `2` (Market Open).
  • `lastUpdateTimestamp`: Timestamp of the last mid-price.
| Decide whether to allow users to open/close positions when `marketStatus = 2` but `lastUpdateTimestamp` is stale. | + +--- + +### Volatility & low liquidity + +During periods of high volatility or low liquidity, price movements can become unpredictable and exaggerated. These conditions can increase the risk of sudden liquidations and bad debt accumulation, requiring careful risk management strategies. + +#### Algorithmic & HFT activity + +Rapid-fire trading by algos can create unpredictable price movements. + +High volatility can lead to liquidation and potential bad debt accumulation. + +| Data Stream behavior | User guidance | +| :-------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | +|
  • `midPrice`: Current mid price.
  • `marketStatus`: `2` (Market Open).
  • `lastUpdateTimestamp`: Current timestamp.
| Monitor liquidation thresholds closely to prevent accumulating bad debt. | + +#### Low liquidity at open/close + +Reduced market depth at trading session transitions can lead to higher volatility and spreads. + +High volatility can lead to liquidation and potential bad debt accumulation. + +| Data Stream behavior | User guidance | +| :-------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | +|
  • `midPrice`: Current mid price.
  • `marketStatus`: `2` (Market Open).
  • `lastUpdateTimestamp`: Current timestamp.
| Monitor liquidation thresholds closely to prevent accumulating bad debt. | + +--- + +### Corporate actions + +Corporate actions are events initiated by publicly traded companies that can significantly impact stock prices and trading behavior. These actions are usually announced outside regular trading hours and can cause substantial price movements when markets reopen. Users should monitor these events closely as they can lead to sudden price adjustments that may trigger unexpected liquidations or require position modifications. + +#### Bankruptcy & delisting + +Bankruptcy can lead to delisting or complete loss of equity value. + +Delisting will zero out prices for the asset. + +| Data Stream behavior | User guidance | +| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- | +|
  • `midPrice`: Closing price is repeated until a new price is available.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Closing timestamp of the last session.
| Monitor delisting news during `marketStatus` = `1` and close markets permanently once confirmed. | + +#### Spin-offs + +When a company spins off a business unit into a separate publicly traded entity, the parent company's stock may adjust accordingly, while the spun-off company's shares begin trading independently. + +Positions may need to be manually adjusted if the DEX doesn't support tracking the new entity. + +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|
  • `midPrice`: Closing price is repeated until the first post-spin trade.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Last close.
| Monitor spin-off and split announcements while `marketStatus = 1`.

Auto-pause the market if the first post-event price moves by more than X% from the prior close, update positions, then reopen.

If automatic adjustment isn't possible, disable leverage during the event window to prevent unfair liquidations. | + +#### Stock splits & reverse splits + +A stock split increases the number of shares while reducing the price per share (e.g., 2-for-1 split), often making shares more accessible to investors. A reverse split does the opposite, consolidating shares to increase the price per share. + +A 2-for-1 split would reduce the price by 50% from the previous trading session, any leveraged user could get liquidated. + +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|
  • `midPrice`: Closing price is repeated until the split-adjusted price prints.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Last close.
| Monitor spin-off and split announcements while `marketStatus = 1`.

Auto-pause the market if the first post-event price moves by more than X% from the prior close, update positions, then reopen.

If automatic adjustment isn't possible, disable leverage during the event window to prevent unfair liquidations. | + +#### Mergers & acquisitions (M&A) + +If a company is being acquired, its stock price may rise to reflect the acquisition premium. The acquiring company's stock might fluctuate based on investor sentiment regarding the deal's financial and strategic impact. + +Announcements can cause sharp price spikes or sustained moves. + +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------- | +|
  • `midPrice`: Closing price is repeated until a new price prints.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Last close.
| Monitor liquidation thresholds closely to prevent accumulating bad debt. | + +#### Share buybacks & stock issuance + +Reduced share supply from a buyback can drive stock prices higher, while increase in share supply can lead to price dilution. + +Announcements can cause sharp price spikes or sustained moves. + +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------- | +|
  • `midPrice`: Closing price is repeated until a new price prints.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Last close.
| Monitor liquidation thresholds closely to prevent accumulating bad debt. | + +#### Dividends + +A company's stock price typically adjusts to reflect dividend payments. For example, when a company declares a 10% dividend, its stock price often drops by a similar amount on the ex-dividend date, as new buyers are no longer entitled to that dividend. + +Announcements can cause sharp price spikes or sustained moves. + +| Data Stream behavior | User guidance | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------- | +|
  • `midPrice`: Closing price is repeated until the ex-date trade prints.
  • `marketStatus`: `1` (Market Closed).
  • `lastUpdateTimestamp`: Last close.
| Monitor liquidation thresholds closely to prevent accumulating bad debt. | diff --git a/src/content/data-streams/market-hours.mdx b/src/content/data-streams/market-hours.mdx index 3811d7528bd..ca6b65bbef9 100644 --- a/src/content/data-streams/market-hours.mdx +++ b/src/content/data-streams/market-hours.mdx @@ -23,6 +23,7 @@ whatsnext: "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", } --- @@ -67,7 +68,14 @@ RWA markets operate during specific hours, with breaks for holidays and sometime --- -### User Recommendations +## User Recommendations + +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-best-practices) page. + + The following sections outline common market issues related to RWA trading hours, and how users can mitigate risks. From 8dff9955a383135c4976ce6c631e37630f2b7dbd Mon Sep 17 00:00:00 2001 From: Devin DiStefano Date: Sun, 10 Aug 2025 22:32:30 -0700 Subject: [PATCH 10/11] broken-link-fix --- src/content/data-streams/reference/report-schema-v8.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/data-streams/reference/report-schema-v8.mdx b/src/content/data-streams/reference/report-schema-v8.mdx index 65c8cb377a2..e002fae8f46 100644 --- a/src/content/data-streams/reference/report-schema-v8.mdx +++ b/src/content/data-streams/reference/report-schema-v8.mdx @@ -50,4 +50,4 @@ RWA streams adhere to the report schema outlined below. - `marketStatus`: - Users are responsible for handle market status changes in their applications. - - For further guidance, refer to the [User Recommendations section in the Market Hours](/data-streams/market-hours#rwa-recommendations) documentation. + - For further guidance, refer to the [Market Hours Best Practices](/data-streams/concepts/best-practices#market-hours-best-practices) documentation. From 225d399efae530079679ef7d8124a9a763ba81be Mon Sep 17 00:00:00 2001 From: Devin DiStefano Date: Sun, 10 Aug 2025 22:40:39 -0700 Subject: [PATCH 11/11] update best practices intro text --- src/content/data-streams/concepts/best-practices.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/data-streams/concepts/best-practices.mdx b/src/content/data-streams/concepts/best-practices.mdx index ec7630ab66f..b34c66f8de0 100644 --- a/src/content/data-streams/concepts/best-practices.mdx +++ b/src/content/data-streams/concepts/best-practices.mdx @@ -30,7 +30,7 @@ whatsnext: import { Aside } from "@components" -This guide provides best practices and recommendations for using Chainlink Data Streams effectively. Understanding these practices is crucial for building robust applications that handle various market conditions, edge cases, and potential risks. +This page provides best practices and recommendations for using Chainlink Data Streams effectively in your applications. These practices can help you manage risks, optimize performance, and ensure compliance with market standards.