diff --git a/public/images/data-streams/24-5-availability.png b/public/images/data-streams/24-5-availability.png new file mode 100644 index 00000000000..01298dcbe27 Binary files /dev/null and b/public/images/data-streams/24-5-availability.png differ diff --git a/public/images/data-streams/24-5-price-jumps-example.png b/public/images/data-streams/24-5-price-jumps-example.png new file mode 100644 index 00000000000..d38453ea31e Binary files /dev/null and b/public/images/data-streams/24-5-price-jumps-example.png differ diff --git a/reports/llms-report.json b/reports/llms-report.json index 4e89e780fbf..bb2b781a566 100644 --- a/reports/llms-report.json +++ b/reports/llms-report.json @@ -1,5 +1,5 @@ { - "startedAt": "2025-12-09T23:41:23.311Z", + "startedAt": "2025-12-11T21:04:08.357Z", "siteBase": "https://docs.chain.link", "sections": [ { @@ -39,16 +39,16 @@ "pagesProcessed": 37, "outputPath": "src/content/data-feeds/llms-full.txt", "bytes": 302589, - "prevBytes": 302327, - "deltaBytes": 262 + "prevBytes": 302589, + "deltaBytes": 0 }, { "section": "data-streams", - "pagesProcessed": 55, + "pagesProcessed": 59, "outputPath": "src/content/data-streams/llms-full.txt", - "bytes": 477063, - "prevBytes": 477063, - "deltaBytes": 0 + "bytes": 516576, + "prevBytes": 516531, + "deltaBytes": 45 }, { "section": "dta-technical-standard", @@ -123,5 +123,5 @@ "deltaBytes": 0 } ], - "finishedAt": "2025-12-09T23:41:27.135Z" + "finishedAt": "2025-12-11T21:04:12.341Z" } diff --git a/src/config/sidebar.ts b/src/config/sidebar.ts index c70e3d9195a..acefd8722b9 100644 --- a/src/config/sidebar.ts +++ b/src/config/sidebar.ts @@ -873,6 +873,15 @@ export const SIDEBAR: Partial> = { title: "Report Schema v11 (RWA Advanced)", url: "data-streams/reference/report-schema-v11", }, + { + title: "Handling Market Events", + url: "data-streams/rwa-streams/handling-market-events", + highlightAsCurrent: ["data-streams/rwa-streams/handling-market-events-v11"], + }, + { + title: "24/5 US Equities User Guide", + url: "data-streams/rwa-streams/24-5-us-equities-user-guide", + }, ], }, { @@ -893,6 +902,10 @@ export const SIDEBAR: Partial> = { title: "Report Schema v10 (Tokenized Asset)", url: "data-streams/reference/report-schema-v10", }, + { + title: "Handling Stock Splits", + url: "data-streams/backed-streams/handling-stock-splits", + }, ], }, { diff --git a/src/content/data-streams/backed-streams/handling-stock-splits.mdx b/src/content/data-streams/backed-streams/handling-stock-splits.mdx new file mode 100644 index 00000000000..9b099f83bc2 --- /dev/null +++ b/src/content/data-streams/backed-streams/handling-stock-splits.mdx @@ -0,0 +1,108 @@ +--- +section: dataStreams +date: "Last Modified" +title: "Handling Stock Splits" +metadata: + title: "Handling Stock Splits for Tokenized Assets | Chainlink Data Streams" + description: "Learn how to handle stock splits and reverse splits for tokenized assets using Chainlink Data Streams v10 schema." +whatsnext: + { + "Find the schema of data to expect from Data Streams reports: Tokenized Asset (v10)": "/data-streams/reference/report-schema-v10", + } +--- + +import { Aside } from "@components" + +Corporate actions, such as stock splits and reverse splits, require precise handling for tokenized assets to ensure price continuity and avoid disruptions. These events alter per‑share pricing while leaving the underlying economic exposure unchanged. They can produce abrupt per‑share price moves and must be handled carefully to avoid incorrect onchain price computations and unexpected liquidations. + +In the [v10 report schema](/data-streams/reference/report-schema-v10), continuity is preserved by staging a multiplier change with a scheduled `activationDateTime` so the Theoretical Price (`price` \* `currentMultiplier`) remains continuous. Split ratios are typically known in advance, but activation may occur while markets are closed, so some external price sources may not reflect the split until trading resumes. + + + +## Guiding principle + +Follow these principles when handling multiplier changes during corporate actions: + +1. The protocol considers the Theoretical Price as `price` \* `currentMultiplier`. +1. Ahead of the event, `newMultiplier` and `activationDateTime` are staged. +1. At `activationDateTime` (Unix), `currentMultiplier` becomes `newMultiplier`. + - The underlying `price` from traditional markets should start reflecting the split the next time trading opens, so at the next `price` update, the Theoretical Price should remain continuous. + +## Example (10:1 split, AAPL) + +The following hypothetical scenario demonstrates how a 10:1 AAPL stock split is handled through the staged multiplier system, showing the progression from announcement through protocol reopening with proper price continuity maintained throughout. + +The following timeline outlines the key events and actions taken at each stage: + +- **T-2**: [Split announcement and multiplier staging](#announcement-t-2) +- **T-1**: [Protocol preparation and monitoring setup](#protocol-engagement-t-1) +- **T0**: [Multiplier activation (split effective date)](#activation-t0) +- **T+1**: [Market reopening with adjusted prices](#market-reopening-t1) +- **T+2**: [Protocol resumption after verification](#protocol-reopening-t2) + +### Announcement (T-2) + +A 10:1 AAPL stock split is announced. [The report](/data-streams/reference/report-schema-v10) updates to stage the split: + +- `newMultiplier` is set to 10x the value of `currentMultiplier`. +- `activationDateTime` is set to the Unix timestamp of the split. +- `currentMultiplier` is unaffected until activation. + +### Protocol engagement (T-1) + +At this stage, users are advised to monitor for changes in `activationDateTime` and inspect the upcoming change to prepare appropriate action, such as preparing the protocol for a pause around the `activationDateTime` in order to ensure appropriate handling of the stock split. + +### Activation (T0) + +When the provider applies the split, [the report](/data-streams/reference/report-schema-v10) updates: + +- `newMultiplier` remains the current value. +- `activationDateTime` is set to `0`. +- `currentMultiplier` is updated to the same value as `newMultiplier`. + + + +If activation occurs while the underlying market is closed, prices may still show the pre‑event last trade. Do not compute the Theoretical Price during this pre-adjustment window. Monitor `marketStatus` and keep the protocol paused until the first post‑event trade prints and the Theoretical Price is continuous. + +### Market reopening (T1) + +The stock split has taken effect. Generally, this occurs after the market closes or over the weekend, meaning `price` may not yet reflect the new economic value per share. Upon the market reopening, `price` should start reflecting the split-adjusted value. + +### Protocol reopening (T2) + +Users should pause markets before `activationDateTime` and keep them paused until: + +- The market has reopened (monitor `marketStatus`) +- `price` has updated in line with the split ratio (e.g., 10:1) +- You have confirmed that the Theoretical Price matches expectations + +After all the above checks have been confirmed, users can unpause their protocol and continue and resume normal operation. + +## Activation-time convention + +Each tokenized asset issuer sets its own activation time. For example, the xStocks default `activationDateTime` is 00:00 UTC on the effective date. Once `activationDateTime` is reached, `currentMultiplier` becomes `newMultiplier`. + +Because underlying venues may be closed at activation, some external price sources may not reflect the split immediately. If `activationDateTime` occurs while the underlying market is closed, the report’s `currentMultiplier` will become `newMultiplier`; however, `price` can remain at the pre-event level until the market reopens. During this post-activation, pre-adjustment interval (after the multiplier has changed but before the underlying `price` updates), the Theoretical Price can be incorrect. Use `marketStatus` to pause until `price` reflects the event. + +## Integrator risk & handling + +Computing `price` \* `currentMultiplier` when the price has not adjusted (e.g., market closed) can produce large errors. It is critical to ensure that the Theoretical Price is again reflective of actual market conditions before allowing live trading. + +Treat any multiplier change (splits, dividends, etc) and `activationDateTime` as a maintenance window; pause/guard the protocol, then verify post-activation conditions before resuming. + + + +For broader guidance around market hours and event handling, refer to the [Market Hours](/data-streams/market-hours) guidance. diff --git a/src/content/data-streams/concepts/best-practices.mdx b/src/content/data-streams/concepts/best-practices.mdx index 67bdbb86243..69112466fcf 100644 --- a/src/content/data-streams/concepts/best-practices.mdx +++ b/src/content/data-streams/concepts/best-practices.mdx @@ -25,6 +25,8 @@ whatsnext: "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", + "Learn how to handle market events": "/data-streams/rwa-streams/handling-market-events", + "Learn how to handle stock splits": "/data-streams/backed-streams/handling-stock-splits", } --- @@ -41,252 +43,8 @@ This page provides best practices and recommendations for using Chainlink Data S ## Real-World Assets (RWA) -Apply these RWA best practices when integrating or operating markets that use tokenized real-world assets. Developers and operators are responsible for assessing market integrity, implementing mitigations, and managing application-level risks — see the [Developer Responsibilities](/data-streams/developer-responsibilities) guidance for details. +For best practices regarding RWA market hours, volatility, and corporate actions, please see the [Handling Market Events](/data-streams/rwa-streams/handling-market-events) guide. -### Market Hours +## Tokenized Assets -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 | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| | 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 avoid 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 | -| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | -| | 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 | -| :-------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | -| | 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 | -| :-------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | -| | 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 | -| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- | -| | 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 | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| | 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 | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| | 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 | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------- | -| | 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 an 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 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 | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------- | -| | Monitor liquidation thresholds closely to prevent accumulating bad debt. | - ---- - -### Handling stock splits for tokenized assets - -Corporate actions, such as stock splits and reverse splits, require precise handling for tokenized assets to ensure price continuity and avoid disruptions. These events alter per‑share pricing while leaving the underlying economic exposure unchanged. They can produce abrupt per‑share price moves and must be handled carefully to avoid incorrect onchain price computations and unexpected liquidations. - -In the [v10 report schema](/data-streams/reference/report-schema-v10), continuity is preserved by staging a multiplier change with a scheduled `activationDateTime` so the Theoretical Price (`price` \* `currentMultiplier`) remains continuous. Split ratios are typically known in advance, but activation may occur while markets are closed, so some external price sources may not reflect the split until trading resumes. - - - -#### Guiding principle - -Follow these principles when handling multiplier changes during corporate actions: - -1. The protocol considers the Theoretical Price as `price` \* `currentMultiplier`. -1. Ahead of the event, `newMultiplier` and `activationDateTime` are staged. -1. At `activationDateTime` (Unix), `currentMultiplier` becomes `newMultiplier`. - - The underlying `price` from traditional markets should start reflecting the split the next time trading opens, so at the next `price` update, the Theoretical Price should remain continuous. - -#### Example (10:1 split, AAPL) - -The following hypothetical scenario demonstrates how a 10:1 AAPL stock split is handled through the staged multiplier system, showing the progression from announcement through protocol reopening with proper price continuity maintained throughout. - -The following timeline outlines the key events and actions taken at each stage: - -- **T-2**: [Split announcement and multiplier staging](#announcement-t-2) -- **T-1**: [Protocol preparation and monitoring setup](#protocol-engagement-t-1) -- **T0**: [Multiplier activation (split effective date)](#activation-t0) -- **T+1**: [Market reopening with adjusted prices](#market-reopening-t1) -- **T+2**: [Protocol resumption after verification](#protocol-reopening-t2) - -##### Announcement (T-2) - -A 10:1 AAPL stock split is announced. [The report](/data-streams/reference/report-schema-v10) updates to stage the split: - -- `newMultiplier` is set to 10x the value of `currentMultiplier`. -- `activationDateTime` is set to the Unix timestamp of the split. -- `currentMultiplier` is unaffected until activation. - -##### Protocol engagement (T-1) - -At this stage, users are advised to monitor for changes in `activationDateTime` and inspect the upcoming change to prepare appropriate action, such as preparing the protocol for a pause around the `activationDateTime` in order to ensure appropriate handling of the stock split. - -##### Activation (T0) - -When the provider applies the split, [the report](/data-streams/reference/report-schema-v10) updates: - -- `newMultiplier` remains the current value. -- `activationDateTime` is set to `0`. -- `currentMultiplier` is updated to the same value as `newMultiplier`. - - - -If activation occurs while the underlying market is closed, prices may still show the pre‑event last trade. Do not compute the Theoretical Price during this pre-adjustment window. Monitor `marketStatus` and keep the protocol paused until the first post‑event trade prints and the Theoretical Price is continuous. - -##### Market reopening (T1) - -The stock split has taken effect. Generally, this occurs after the market closes or over the weekend, meaning `price` may not yet reflect the new economic value per share. Upon the market reopening, `price` should start reflecting the split-adjusted value. - -##### Protocol reopening (T2) - -Users should pause markets before `activationDateTime` and keep them paused until: - -- The market has reopened (monitor `marketStatus`) -- `price` has updated in line with the split ratio (e.g., 10:1) -- You have confirmed that the Theoretical Price matches expectations - -After all the above checks have been confirmed, users can unpause their protocol and continue and resume normal operation. - -#### Activation-time convention - -Each tokenized asset issuer sets its own activation time. For example, the xStocks default `activationDateTime` is 00:00 UTC on the effective date. Once `activationDateTime` is reached, `currentMultiplier` becomes `newMultiplier`. - -Because underlying venues may be closed at activation, some external price sources may not reflect the split immediately. If `activationDateTime` occurs while the underlying market is closed, the report’s `currentMultiplier` will become `newMultiplier`; however, `price` can remain at the pre-event level until the market reopens. During this post-activation, pre-adjustment interval (after the multiplier has changed but before the underlying `price` updates), the Theoretical Price can be incorrect. Use `marketStatus` to pause until `price` reflects the event. - -#### Integrator risk & handling - -Computing `price` \* `currentMultiplier` when the price has not adjusted (e.g., market closed) can produce large errors. It is critical to ensure that the Theoretical Price is again reflective of actual market conditions before allowing live trading. - -Treat any multiplier change (splits, dividends, etc) and `activationDateTime` as a maintenance window; pause/guard the protocol, then verify post-activation conditions before resuming. - - - -For broader guidance around market hours and event handling, refer to the [Market Hours](#market-hours) guidance. +For best practices regarding stock splits and reverse splits for tokenized assets, please see the [Handling Stock Splits](/data-streams/backed-streams/handling-stock-splits) guide. diff --git a/src/content/data-streams/llms-full.txt b/src/content/data-streams/llms-full.txt index 2ed3dd881c8..184aec44d95 100644 --- a/src/content/data-streams/llms-full.txt +++ b/src/content/data-streams/llms-full.txt @@ -111,206 +111,8 @@ Automatic failover handles availability and traffic routing in the following sce --- -# Tokenized Asset Data Streams -Source: https://docs.chain.link/data-streams/backed-streams - - - ---- - -# Data Streams Billing -Source: https://docs.chain.link/data-streams/billing - - - -Chainlink Data Streams offers two billing models: - -1. **Subscription model**: A subscription-based billing option. - -2. **Pay-per-report model**: You pay to verify reports from Data Streams onchain using the verifier contract. You pay per report verified. If you verify multiple reports in a batch, you pay for all of the reports included in that batch. - - The verification price is 0.35 USD per report. Chainlink Data Streams supports fee payments in LINK and in alternative assets, which currently includes native blockchain gas tokens and their ERC20-wrapped version. Payments made in alternative assets have a 10% surcharge when compared to LINK payments. - -[Contact us](https://chainlinkcommunity.typeform.com/datastreams?#ref_id=docs) to learn more about Mainnet pricing and subscription options. - ---- - -# Data Streams Best Practices -Source: https://docs.chain.link/data-streams/concepts/best-practices - -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. - - - -*** - -## Real-World Assets (RWA) - -Apply these RWA best practices when integrating or operating markets that use tokenized real-world assets. Developers and operators are responsible for assessing market integrity, implementing mitigations, and managing application-level risks — see the [Developer Responsibilities](/data-streams/developer-responsibilities) guidance for details. - -### Market Hours - -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 | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| | 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 avoid 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 | -| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | -| | 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 | -| :-------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | -| | 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 | -| :-------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | -| | 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 | -| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- | -| | 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 | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| | 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 | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| | 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 | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------- | -| | 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 an 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 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 | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------- | -| | Monitor liquidation thresholds closely to prevent accumulating bad debt. | - -*** - -### Handling stock splits for tokenized assets +# Handling Stock Splits +Source: https://docs.chain.link/data-streams/backed-streams/handling-stock-splits Corporate actions, such as stock splits and reverse splits, require precise handling for tokenized assets to ensure price continuity and avoid disruptions. These events alter per‑share pricing while leaving the underlying economic exposure unchanged. They can produce abrupt per‑share price moves and must be handled carefully to avoid incorrect onchain price computations and unexpected liquidations. @@ -323,7 +125,7 @@ In the [v10 report schema](/data-streams/reference/report-schema-v10), continuit exact behavior will depend on each schema's design and are not guaranteed. -#### Guiding principle +## Guiding principle Follow these principles when handling multiplier changes during corporate actions: @@ -332,7 +134,7 @@ Follow these principles when handling multiplier changes during corporate action 3. At `activationDateTime` (Unix), `currentMultiplier` becomes `newMultiplier`. - The underlying `price` from traditional markets should start reflecting the split the next time trading opens, so at the next `price` update, the Theoretical Price should remain continuous. -#### Example (10:1 split, AAPL) +## Example (10:1 split, AAPL) The following hypothetical scenario demonstrates how a 10:1 AAPL stock split is handled through the staged multiplier system, showing the progression from announcement through protocol reopening with proper price continuity maintained throughout. @@ -344,7 +146,7 @@ The following timeline outlines the key events and actions taken at each stage: - **T+1**: [Market reopening with adjusted prices](#market-reopening-t1) - **T+2**: [Protocol resumption after verification](#protocol-reopening-t2) -##### Announcement (T-2) +### Announcement (T-2) A 10:1 AAPL stock split is announced. [The report](/data-streams/reference/report-schema-v10) updates to stage the split: @@ -352,11 +154,11 @@ A 10:1 AAPL stock split is announced. [The report](/data-streams/reference/repor - `activationDateTime` is set to the Unix timestamp of the split. - `currentMultiplier` is unaffected until activation. -##### Protocol engagement (T-1) +### Protocol engagement (T-1) At this stage, users are advised to monitor for changes in `activationDateTime` and inspect the upcoming change to prepare appropriate action, such as preparing the protocol for a pause around the `activationDateTime` in order to ensure appropriate handling of the stock split. -##### Activation (T0) +### Activation (T0) When the provider applies the split, [the report](/data-streams/reference/report-schema-v10) updates: @@ -372,11 +174,11 @@ When the provider applies the split, [the report](/data-streams/reference/report If activation occurs while the underlying market is closed, prices may still show the pre‑event last trade. Do not compute the Theoretical Price during this pre-adjustment window. Monitor `marketStatus` and keep the protocol paused until the first post‑event trade prints and the Theoretical Price is continuous. -##### Market reopening (T1) +### Market reopening (T1) The stock split has taken effect. Generally, this occurs after the market closes or over the weekend, meaning `price` may not yet reflect the new economic value per share. Upon the market reopening, `price` should start reflecting the split-adjusted value. -##### Protocol reopening (T2) +### Protocol reopening (T2) Users should pause markets before `activationDateTime` and keep them paused until: @@ -386,13 +188,13 @@ Users should pause markets before `activationDateTime` and keep them paused unti After all the above checks have been confirmed, users can unpause their protocol and continue and resume normal operation. -#### Activation-time convention +## Activation-time convention Each tokenized asset issuer sets its own activation time. For example, the xStocks default `activationDateTime` is 00:00 UTC on the effective date. Once `activationDateTime` is reached, `currentMultiplier` becomes `newMultiplier`. Because underlying venues may be closed at activation, some external price sources may not reflect the split immediately. If `activationDateTime` occurs while the underlying market is closed, the report’s `currentMultiplier` will become `newMultiplier`; however, `price` can remain at the pre-event level until the market reopens. During this post-activation, pre-adjustment interval (after the multiplier has changed but before the underlying `price` updates), the Theoretical Price can be incorrect. Use `marketStatus` to pause until `price` reflects the event. -#### Integrator risk & handling +## Integrator risk & handling Computing `price` \* `currentMultiplier` when the price has not adjusted (e.g., market closed) can produce large errors. It is critical to ensure that the Theoretical Price is again reflective of actual market conditions before allowing live trading. @@ -404,7 +206,60 @@ Treat any multiplier change (splits, dividends, etc) and `activationDateTime` as post-activation conditions are verified before resuming operations. -For broader guidance around market hours and event handling, refer to the [Market Hours](#market-hours) guidance. +For broader guidance around market hours and event handling, refer to the [Market Hours](/data-streams/market-hours) guidance. + +--- + +# Tokenized Asset Data Streams +Source: https://docs.chain.link/data-streams/backed-streams + + + +--- + +# Data Streams Billing +Source: https://docs.chain.link/data-streams/billing + + + +Chainlink Data Streams offers two billing models: + +1. **Subscription model**: A subscription-based billing option. + +2. **Pay-per-report model**: You pay to verify reports from Data Streams onchain using the verifier contract. You pay per report verified. If you verify multiple reports in a batch, you pay for all of the reports included in that batch. + + The verification price is 0.35 USD per report. Chainlink Data Streams supports fee payments in LINK and in alternative assets, which currently includes native blockchain gas tokens and their ERC20-wrapped version. Payments made in alternative assets have a 10% surcharge when compared to LINK payments. + +[Contact us](https://chainlinkcommunity.typeform.com/datastreams?#ref_id=docs) to learn more about Mainnet pricing and subscription options. + +--- + +# Data Streams Best Practices +Source: https://docs.chain.link/data-streams/concepts/best-practices + +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. + + + +*** + +## Real-World Assets (RWA) + +For best practices regarding RWA market hours, volatility, and corporate actions, please see the [Handling Market Events](/data-streams/rwa-streams/handling-market-events) guide. + +## Tokenized Assets + +For best practices regarding stock splits and reverse splits for tokenized assets, please see the [Handling Stock Splits](/data-streams/backed-streams/handling-stock-splits) guide. --- @@ -852,6 +707,23 @@ RWA markets operate during specific hours, with breaks for holidays and sometime | **Precious Metals (Spot)**
(XAU, XAG) | **18:00 Sun** | **17:00 Fri** | 17:00–18:00 Mon-Thu | Jan 1, Good Fri, Dec 25 | | **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/) | +### US Equities 24/5 Trading Sessions + +For feeds using the [RWA Advanced (v11) schema](/data-streams/reference/report-schema-v11), US Equities are available across three distinct trading sessions, providing 24/5 coverage: + +| Session | Hours (ET) | `marketStatus` Value | Description | +| ------------------- | ------------------------------------- | ------------------------------------ | ---------------------------------------------- | +| **Regular Hours** | 9:30am–4:00pm Mon–Fri | `2` (Regular hours) | Primary trading session with highest liquidity | +| **Extended Hours** | 4:00am–9:30am & 4:00pm–8:00pm Mon–Fri | `1` (Pre-market) & `3` (Post-market) | Pre-market and post-market sessions | +| **Overnight Hours** | 8:00pm–4:00am Sun evening–Fri morning | `4` (Overnight) | Overnight session with limited liquidity | + +**Additional `marketStatus` values:** + +- `0` (Unknown) — Market status cannot be determined +- `5` (Weekend) — Weekend period: 8:00pm Fri–8:00pm Sun + +See the [24/5 US Equities User Guide](/data-streams/rwa-streams/24-5-us-equities-user-guide) for detailed information on building continuous price feeds and managing session transitions. + \* 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. @@ -5191,7 +5063,7 @@ Chainlink Backed xStock Data Streams adhere to the report schema outlined below. - `price` updates in real time during market open, but may become stale during market closed periods. - `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. +- See more detailed guidance for handling stock splits in the [Handling Stock Splits](/data-streams/backed-streams/handling-stock-splits) documentation. --- @@ -5212,12 +5084,12 @@ Chainlink Data Streams that use the RWA Advanced (v11) schema adhere to the stru | `nativeFee` | `uint192` | Cost to verify report onchain (native token) | | `linkFee` | `uint192` | Cost to verify report onchain (LINK) | | `expiresAt` | `uint32` | Expiration date of the report (seconds) | -| `mid` | `int192` | Liquidity-weighted mid price | -| `lastSeenTimestampNs` | `uint64` | Staleness indicator based on mid price (nanoseconds) | +| `mid` | `int192` | DON Consensus mid-price | +| `lastSeenTimestampNs` | `uint64` | Reflects the timestamp of the last update for the **mid price only** (nanoseconds). See [Notes](#notes) below. | | `bid` | `int192` | Median bid price | -| `bidVolume` | `int192` | Volume at bid price | +| `bidVolume` | `int192` | Volume at bid price. See [bid/ask volume note](#bidask-volume-note) below. | | `ask` | `int192` | Median ask price | -| `askVolume` | `int192` | Volume at ask price | +| `askVolume` | `int192` | Volume at ask price. See [bid/ask volume note](#bidask-volume-note) below. | | `lastTradedPrice` | `int192` | Last traded price | | `marketStatus` | `uint32` | Status of the real-world equity market.
Possible values:
`0` (Unknown),
`1` (Pre-market extended hours),
`2` (Regular hours),
`3` (Post-market hours),
`4` (Overnight),
`5` (Weekend)
[More details](#market-status-values) | @@ -5238,8 +5110,20 @@ Users should implement appropriate safeguards based on market status, such as pa ### Notes +#### Last Seen Timestamp + +- **IMPORTANT**: The `lastSeenTimestampNs` field reflects the timestamp of the last update for the `mid` price only. Do not assume this timestamp applies to `bid`, `ask`, `bidVolume`, `askVolume`, or `lastTradedPrice`. Different fields may have been updated at different times. +- `lastSeenTimestampNs` helps applications detect stale data for the mid price, especially important during market transitions and holidays. + +#### Bid/Ask Volume + +For U.S. equities, there is no single consolidated order book. Instead, multiple venues each maintain their own order books. Because data providers source from different markets, the `bidVolume` and `askVolume` reported at each update come from one specific order book at a time, not an aggregate across all venues. + +As a result, these volume fields should not be treated as a proxy for total market liquidity at the top of book. They are informational and not especially representative in fragmented markets like U.S. equities. + +#### Additional Notes + - Future streams using this format may adopt different report schemas as needed. -- `lastSeenTimestampNs` helps applications detect stale data, especially important during market transitions and holidays. - Market status cannot detect public holidays. See [Market Hours](/data-streams/market-hours) for major holiday periods. - Data availability and sourcing vary by session. Liquidity is typically highest during regular hours and lower during extended and overnight sessions. @@ -5380,7 +5264,7 @@ RWA streams adhere to the report schema outlined below. - `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. + - For further guidance, refer to the [Handling Market Events](/data-streams/rwa-streams/handling-market-events) documentation. - Future RWA streams may use different report schemas. --- @@ -5418,6 +5302,592 @@ Chainlink NAV Data Streams streams adhere to the report schema outlined below. --- +# 24/5 US Equities User Guide +Source: https://docs.chain.link/data-streams/rwa-streams/24-5-us-equities-user-guide + +Chainlink 24/5 U.S. Equities Streams provide real-time equity pricing data across all major U.S. single-name equities and ETFs spanning regular, pre-market, post-market, and overnight trading sessions. The [advanced RWA schema](/data-streams/reference/report-schema-v11) includes fields such as market status flags, best bid and ask prices, bid and ask volumes, staleness measures, and last traded prices to facilitate more advanced execution and risk management. + +The data referenced in this document covers 24/5 trading hours in US equities on a range of traditional venues. While there is currently no trading activity in traditional markets over the weekend on any venue, protocols can extend their pricing coverage to 24/7 in multiple ways, such as leveraging the pricing of [tokenized stocks](#stream-switching-example-logic) on secondary markets such as CEXes and DEXes. + +Developers are responsible for choosing the appropriate feed and ensuring that the operation and performance of their choice matches expectations. For more information, please visit the Chainlink [documentation](/data-streams/developer-responsibilities). + +## Schema + +The data is delivered using the [RWA Advanced (v11) schema](/data-streams/reference/report-schema-v11). + +This advanced RWA schema is built to support 24/5 streams, including DON Consensus `mid` price (with its corresponding timestamp `lastSeenTimestampNs` for staleness tracking), order book depth (`bid`, `ask`, `bidVolume`, `askVolume`), execution data (`lastTradedPrice`), and granular market phases (`marketStatus` values for Pre-market, Regular hours, Post-market, Overnight, and Weekend). + + + + + +## Feeds + +Each instrument is exposed through three distinct data streams feeds, each corresponding to a specific trading phase: **Regular Hours**, **Extended Hours**, and **Overnight Hours**. + +[Click here to view a list of RWA streams that support 24-5 US equities](/data-streams/rwa-streams?page=1\&testnetPage=1\&show24x5=true). Use the filters to select your desired time segment. + +For example, **TSLA** is available via the [following streams](/data-streams/rwa-streams?page=1\&testnetPage=1\&show24x5=true\&search=tsla): + +- `TSLA/USD-Streams-ExtendedHours` +- `TSLA/USD-Streams-OvernightHours` +- `TSLA/USD-Streams-RegularHours` + +To construct a **continuous price feed**, users must **dynamically switch** between these individual streams based on the value of `marketStatus`. The mapping logic is as follows: + +| Market Status | Stream | +| ----------------- | --------------------------------- | +| `1` (Pre-market) | `TSLA/USD-Streams-ExtendedHours` | +| `2` (Regular) | `TSLA/USD-Streams-RegularHours` | +| `3` (Post-market) | `TSLA/USD-Streams-ExtendedHours` | +| `4` (Overnight) | `TSLA/USD-Streams-OvernightHours` | + + + +## Building a Continuous Price Feed + +Building a continuous price feed by dynamically switching streams requires robust exception handling to manage edge cases effectively. Because different protocols have unique risk profiles and design requirements, Data Streams allows you to implement custom logic tailored to your specific needs. + +There is no one-size-fits-all solution to integrating 24/5 streams. The sections below outline edge cases you will encounter when building a continuous price feed along with recommended mitigation strategies. For information on structural risks and protocol-specific considerations, see the [Risks](#risks) section. + +If you wish to jump ahead to view an example of switching logic, jump to [Stream Switching Example Logic](#stream-switching-example-logic). + +### Edge Cases and Mitigation + +#### Price Jumps at Session Transition Boundaries + +When transitioning between Regular ↔ Extended ↔ Overnight sessions, noticeable price dislocations can occur. + +These differences are expected and normal due to unique liquidity conditions, venues, participants, and pricing sources per session. These are not bad data; they are true market microstructure effects. + +Typical jumps are **1–2%**, but **larger spikes (10–20%+)** are possible during low-liquidity environments or impactful news cycles. + +##### Mitigation + +**Phase-specific streams are provided intentionally** to give users control over when and how transitions occur. Optional safeguards: + +- Pause or lock market activity during transition windows +- Delay feed switching until price convergence or stability threshold is met +- Apply price smoothing (EMA/VWAP/TWAP) across transition windows +- Temporarily reference [tokenized asset](#stream-switching-example-logic) price (where available) + +#### Market Status Unknown/Unavailable (`marketStatus = 0`) + +The system may return `marketStatus = 0` (Unknown). **If your implementation relies on automated feed switching based on market status, you must account for this scenario.** + +Market status is sourced from several independent providers configured as primary/fallback. While resilient, multiple providers can fail simultaneously. + +##### Mitigation + +Consumers must treat `marketStatus = 0` (Unknown) as a valid state and define deterministic behaviors when it is returned. Potential actions include: + +- Pause or lock market activity +- Allow restricted trading within a bounded range (e.g., last-valid price ± threshold) +- Temporarily reference [tokenized asset](#stream-switching-example-logic) price (where available) + +#### Weekends (`marketStatus = 5`) + +Traditional equity markets are closed on weekends, so all three feeds will carry stale values. This reflects true underlying market inactivity rather than an outage or failure. + +##### Mitigation + +Consumers must treat `marketStatus = 5` (Weekend) as a valid state and define deterministic behaviors when it is returned. Potential actions include: + +- Pause or lock market activity +- Allow restricted trading within a bounded range (e.g., last-valid price ± threshold) +- Temporarily reference [tokenized asset](#stream-switching-example-logic) price (where available) + +#### Stale Data Detection + +Markets may stop updating due to exchange outages, circuit breakers, trading halts, or corporate actions. Use the `lastSeenTimestampNs` field (which reflects the timestamp of the last update for the `mid` price only) to detect staleness by comparing it against the current time. When this timestamp stops advancing, it indicates the underlying venue has stopped providing updates. + +Phase-specific feeds can introduce unique behavior due to venue-specific operational characteristics and market microstructure. The following are some examples of scenarios that may occur during session transitions or under specific market conditions: + +##### Regular Hours Session: Delayed Quote Availability at Market Open + +During the first 10–20 seconds after regular hours open (9:30am ET), bid/ask quotes may not yet be available from the regular hours venue. In those cases, the reported price may still reflect the previous regular hours close rather than live market data. + +Users should factor this transition period into their switching logic and consider alternative strategies during the first \~20 seconds of regular hours, such as: + +- Pause or lock market activity +- Continue using the pre-market (Extended Hours) stream until fresh regular hours quotes are available +- Temporarily reference [tokenized asset](#stream-switching-example-logic) price (where available) + +##### Overnight Session: Stale Bid/Ask at Session Start + +During the early overnight session -- before the overnight venue begins publishing data -- the feed may display the last bid/ask prices and volumes from the previous regular session. This occurs because no new quotes are available yet from the overnight venue. + +Once the overnight venue starts publishing its own quotes, the data will update to reflect current overnight market conditions. This behavior is normal market microstructure, not a data quality issue. It reflects the actual state of the market during the transition period when overnight liquidity has not yet begun. + +Users relying on bid/ask data during early overnight hours should be aware of this carryover behavior and implement appropriate safeguards, such as checking `lastSeenTimestampNs` for staleness or widening risk parameters during overnight session transitions. + +##### Mitigation + +Consumers must have fallback logic in place when the data is stale. Potential actions include: + +- Pause or lock market activity +- Use last-valid price as reference +- Allow bounded-range trading based on last-valid price +- Temporarily reference [tokenized asset](#stream-switching-example-logic) price (where available) + +### Stream Switching Example Logic + +The following examples demonstrate how to implement a continuous price feed by dynamically switching between phase-specific streams. These examples use tokenized asset prices as the fallback strategy for edge cases (stale data, Unknown market status, and Weekends). Developers may choose alternative mitigation strategies based on their protocol's risk requirements. + +Developers interested in using tokenized assets can find the list of supported assets and schema in the [Tokenized Assets documentation](/data-streams/backed-streams). Using tokenized assets carries its own risks, including liquidity limitations and price deviations from spot markets. Evaluate these factors carefully before integrating tokenized prices into your protocol. + + + +#### Decision Flow + +To build a continuous price feed, follow this general decision flow. This is a simplified outline that leverages tokenized asset prices as fallback; your implementation must account for all risks outlined above and in the [Risks](#risks) section below. + +1. **Fetch and decode** the Regular Hours stream report to get `marketStatus` and `lastSeenTimestampNs` + +2. **Check staleness first:** + - **If data is stale** (timestamp older than your threshold) → **[Use Tokenized Asset stream](/data-streams/backed-streams)** or apply custom risk mitigation + - **If data is fresh** → Continue to step 3 + +3. **Route based on market status:** + - **`marketStatus = 0`** (Unknown) → **Use Tokenized Asset stream** or apply custom risk mitigation + - **`marketStatus = 1`** (Pre-market) → **Use Extended Hours stream** + - **`marketStatus = 2`** (Regular) → **Use Regular Hours stream** + - **`marketStatus = 3`** (Post-market) → **Use Extended Hours stream** + - **`marketStatus = 4`** (Overnight) → **Use Overnight Hours stream** + - **`marketStatus = 5`** (Weekend) → **Use Tokenized Asset stream** or apply custom risk mitigation + +4. **Apply additional safeguards** as needed for your protocol (e.g., price jump checks, circuit breakers, holiday calendars, bounded trading ranges) + +5. **Return the `mid` price** from the selected stream + + + +#### Example Implementation Logic + +This example demonstrates switching logic with tokenized asset prices as fallback. View examples in different SDK languages. + +Please note that these code snippets are illustrative and may require adaptation to fit your specific environment, SDK versions, and error handling practices. Refer to the guide to [fetch](/data-streams/tutorials/go-sdk-fetch) and [stream](/data-streams/tutorials/go-sdk-stream) decoded reports in your chosen SDK. + + + + +## Risks + +While 24/5 streams provide extended market coverage, they introduce specific risks related to liquidity, volatility, and data sourcing. Users must understand these factors and implement appropriate safeguards. + +In the following sections, we outline key risks and recommended mitigation strategies. + +### Single Provider for Extended & Overnight Data + +Extended and overnight session price feeds are currently sourced from a single data provider, making these sessions less reliable than the regular hours price feed which is multi-sourced. + +If the provider experiences downtime, technical failures, or connectivity disruption, the feed may flatline or report highly inaccurate figures, preventing users from reacting to real price movements. Such issues may lead to mispricing, failed liquidations, and potential bad debt accumulation. + +##### Mitigation + +The feed includes a staleness indicator, allowing consumers to detect when data stops updating. Users are strongly recommended to implement fallback logic within their protocol risk framework, which may include: + +- Pause or lock market activity +- Restrict to narrow price bands +- Temporarily switch to the tokenized price feed (understanding that it also carries liquidity limitations) + +### Structural Illiquidity and Volatility in Extended & Overnight Hours + +Pre-market and post-market sessions are typically thinly traded, with fragmented liquidity and higher spreads, leading to stale ticks, price gaps, and elevated volatility. These conditions are inherent to the market, not to the feed, and will be visible in the published data. + +##### Mitigation + +Users should evaluate whether the full 24/5 price coverage is appropriate for their use case. Consider the following: + +- Configure risk thresholds, circuit breakers, or mode switching aligned with your risk appetite +- Validate these configurations during integration and simulation, not post-deployment + +### Corporate Actions + +Traditional equities are subject to corporate actions which can dramatically change the price of an asset overnight, especially in the case of stock splits and reverse stock splits. These actions are usually announced outside regular trading hours and can cause substantial price movements when markets reopen. + +Additionally, the overnight session data provider may disable trading for individual symbols during pending corporate actions such as dividends, splits, or mergers. When this occurs, there will be no overnight session data available for that specific symbol, and this closure will not be reflected in the `marketStatus` field. The overnight feed may continue to display stale data from the previous session, or the data may flatline, making it critical to monitor `lastSeenTimestampNs` for staleness detection. + +##### Mitigation + +Consumers should: + +- Actively monitor corporate action announcements +- Adjust pricing logic, risk parameters, and open positions accordingly +- Consider pausing markets during corporate action windows to prevent unfair liquidations +- Implement staleness checks on `lastSeenTimestampNs` to detect when overnight session data stops updating due to symbol-specific trading halts + +### Market Closures and Halts Are Not Explicitly Flagged + +Market Status data providers do not flag exchange public holidays or trading halts. As a result, the feeds for instruments listed on U.S. exchanges may appear stale, flatline, or behave inconsistently during these periods even though this reflects true market inactivity. + +Trading halts can occur for various reasons including regulatory actions, pending news announcements, volatility circuit breakers, or operational issues. Similar to holidays, when the underlying market is halted, this will not be reflected in the `marketStatus` field. + +Automated switching logic that relies only on `marketStatus` or staleness signals can incorrectly interpret holiday or halt inactivity as an outage or unexpected feed degradation, leading to unnecessary fallbacks, paused markets, or erroneous risk decisions. + +##### Mitigation + +Consumers must: + +- Incorporate an authoritative exchange holiday calendar into their integration (for U.S. listings, the NYSE/NASDAQ holiday calendar is the recommended source) +- Monitor exchange halt notifications and adjust protocol behavior accordingly +- Keep markets closed during exchange holidays to prevent users from trading at unfair prices +- Implement appropriate safeguards when trading halts are detected to prevent unfair liquidations or trades at stale prices + +For detailed market hours and trading schedules, see the [Market Hours](/data-streams/market-hours) documentation. + +--- + +# Handling Market Events (v11) +Source: https://docs.chain.link/data-streams/rwa-streams/handling-market-events-v11 + + + + + +Apply these best practices when integrating or operating markets that use tokenized real-world assets during standard market hours. Developers and operators are responsible for assessing market integrity, implementing mitigations, and managing application-level risks — see the [Developer Responsibilities](/data-streams/developer-responsibilities) guidance for details. + +## Market Hours + +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`, `3`, `4`, `5` (Not Regular Hours).
  • `lastUpdateTimestamp`: Timestamp of the closing price of the last session.
| Keep markets closed while `marketStatus != 2` 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 avoid 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` (Regular Hours).
  • `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` (Regular Hours).
  • `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` (Regular Hours).
  • `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` (Regular Hours).
  • `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` (Regular Hours).
  • `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`, `3`, `4`, `5` (Not Regular Hours).
  • `lastUpdateTimestamp`: Closing timestamp of the last session.
| Monitor delisting news during `marketStatus != 2` 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`, `3`, `4`, `5` (Not Regular Hours).
  • `lastUpdateTimestamp`: Last close.
| Monitor spin-off and split announcements while `marketStatus != 2`.

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`, `3`, `4`, `5` (Not Regular Hours).
  • `lastUpdateTimestamp`: Last close.
| Monitor spin-off and split announcements while `marketStatus != 2`.

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`, `3`, `4`, `5` (Not Regular Hours).
  • `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 an 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`, `3`, `4`, `5` (Not Regular Hours).
  • `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`, `3`, `4`, `5` (Not Regular Hours).
  • `lastUpdateTimestamp`: Last close.
| Monitor liquidation thresholds closely to prevent accumulating bad debt. | + +--- + +# Handling Market Events +Source: https://docs.chain.link/data-streams/rwa-streams/handling-market-events + + + +Apply these best practices when integrating or operating markets that use tokenized real-world assets. Developers and operators are responsible for assessing market integrity, implementing mitigations, and managing application-level risks — see the [Developer Responsibilities](/data-streams/developer-responsibilities) guidance for details. + +## Market Hours + +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 avoid 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 an 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. | + +--- + # Real World Asset (RWA) Data Streams Source: https://docs.chain.link/data-streams/rwa-streams diff --git a/src/content/data-streams/market-hours.mdx b/src/content/data-streams/market-hours.mdx index 333387e2757..c9337770919 100644 --- a/src/content/data-streams/market-hours.mdx +++ b/src/content/data-streams/market-hours.mdx @@ -71,6 +71,23 @@ RWA markets operate during specific hours, with breaks for holidays and sometime | **Precious Metals (Spot)**
(XAU, XAG) | **18:00 Sun** | **17:00 Fri** | 17:00–18:00 Mon-Thu | Jan 1, Good Fri, Dec 25 | | **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/) | +### US Equities 24/5 Trading Sessions + +For feeds using the [RWA Advanced (v11) schema](/data-streams/reference/report-schema-v11), US Equities are available across three distinct trading sessions, providing 24/5 coverage: + +| Session | Hours (ET) | `marketStatus` Value | Description | +| ------------------- | ------------------------------------- | ------------------------------------ | ---------------------------------------------- | +| **Regular Hours** | 9:30am–4:00pm Mon–Fri | `2` (Regular hours) | Primary trading session with highest liquidity | +| **Extended Hours** | 4:00am–9:30am & 4:00pm–8:00pm Mon–Fri | `1` (Pre-market) & `3` (Post-market) | Pre-market and post-market sessions | +| **Overnight Hours** | 8:00pm–4:00am Sun evening–Fri morning | `4` (Overnight) | Overnight session with limited liquidity | + +**Additional `marketStatus` values:** + +- `0` (Unknown) — Market status cannot be determined +- `5` (Weekend) — Weekend period: 8:00pm Fri–8:00pm Sun + +See the [24/5 US Equities User Guide](/data-streams/rwa-streams/24-5-us-equities-user-guide) for detailed information on building continuous price feeds and managing session transitions. + \* 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. diff --git a/src/content/data-streams/reference/report-schema-v10.mdx b/src/content/data-streams/reference/report-schema-v10.mdx index 08f8498104a..c46b68cc345 100644 --- a/src/content/data-streams/reference/report-schema-v10.mdx +++ b/src/content/data-streams/reference/report-schema-v10.mdx @@ -49,4 +49,4 @@ Chainlink Backed xStock Data Streams adhere to the report schema outlined below. - `price` updates in real time during market open, but may become stale during market closed periods. - `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. +- See more detailed guidance for handling stock splits in the [Handling Stock Splits](/data-streams/backed-streams/handling-stock-splits) documentation. diff --git a/src/content/data-streams/reference/report-schema-v11.mdx b/src/content/data-streams/reference/report-schema-v11.mdx index 25278ef3faf..515ceb653a7 100644 --- a/src/content/data-streams/reference/report-schema-v11.mdx +++ b/src/content/data-streams/reference/report-schema-v11.mdx @@ -38,12 +38,12 @@ Chainlink Data Streams that use the RWA Advanced (v11) schema adhere to the stru | `nativeFee` | `uint192` | Cost to verify report onchain (native token) | | `linkFee` | `uint192` | Cost to verify report onchain (LINK) | | `expiresAt` | `uint32` | Expiration date of the report (seconds) | -| `mid` | `int192` | Liquidity-weighted mid price | -| `lastSeenTimestampNs` | `uint64` | Staleness indicator based on mid price (nanoseconds) | +| `mid` | `int192` | DON Consensus mid-price | +| `lastSeenTimestampNs` | `uint64` | Reflects the timestamp of the last update for the **mid price only** (nanoseconds). See [Notes](#notes) below. | | `bid` | `int192` | Median bid price | -| `bidVolume` | `int192` | Volume at bid price | +| `bidVolume` | `int192` | Volume at bid price. See [bid/ask volume note](#bidask-volume-note) below. | | `ask` | `int192` | Median ask price | -| `askVolume` | `int192` | Volume at ask price | +| `askVolume` | `int192` | Volume at ask price. See [bid/ask volume note](#bidask-volume-note) below. | | `lastTradedPrice` | `int192` | Last traded price | | `marketStatus` | `uint32` | Status of the real-world equity market.
Possible values:
`0` (Unknown),
`1` (Pre-market extended hours),
`2` (Regular hours),
`3` (Post-market hours),
`4` (Overnight),
`5` (Weekend)
[More details](#market-status-values) | @@ -64,7 +64,19 @@ Users should implement appropriate safeguards based on market status, such as pa ### Notes +#### Last Seen Timestamp + +- **IMPORTANT**: The `lastSeenTimestampNs` field reflects the timestamp of the last update for the `mid` price only. Do not assume this timestamp applies to `bid`, `ask`, `bidVolume`, `askVolume`, or `lastTradedPrice`. Different fields may have been updated at different times. +- `lastSeenTimestampNs` helps applications detect stale data for the mid price, especially important during market transitions and holidays. + +#### Bid/Ask Volume + +For U.S. equities, there is no single consolidated order book. Instead, multiple venues each maintain their own order books. Because data providers source from different markets, the `bidVolume` and `askVolume` reported at each update come from one specific order book at a time, not an aggregate across all venues. + +As a result, these volume fields should not be treated as a proxy for total market liquidity at the top of book. They are informational and not especially representative in fragmented markets like U.S. equities. + +#### Additional Notes + - Future streams using this format may adopt different report schemas as needed. -- `lastSeenTimestampNs` helps applications detect stale data, especially important during market transitions and holidays. - Market status cannot detect public holidays. See [Market Hours](/data-streams/market-hours) for major holiday periods. - Data availability and sourcing vary by session. Liquidity is typically highest during regular hours and lower during extended and overnight sessions. diff --git a/src/content/data-streams/reference/report-schema-v8.mdx b/src/content/data-streams/reference/report-schema-v8.mdx index 061a3ec2fe8..aee16c91a8c 100644 --- a/src/content/data-streams/reference/report-schema-v8.mdx +++ b/src/content/data-streams/reference/report-schema-v8.mdx @@ -35,5 +35,5 @@ RWA streams adhere to the report schema outlined below. - `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. + - For further guidance, refer to the [Handling Market Events](/data-streams/rwa-streams/handling-market-events) documentation. - Future RWA streams may use different report schemas. diff --git a/src/content/data-streams/rwa-streams/24-5-us-equities-user-guide.mdx b/src/content/data-streams/rwa-streams/24-5-us-equities-user-guide.mdx new file mode 100644 index 00000000000..14a4dd538b8 --- /dev/null +++ b/src/content/data-streams/rwa-streams/24-5-us-equities-user-guide.mdx @@ -0,0 +1,390 @@ +--- +section: dataStreams +date: "Last Modified" +title: "24/5 US Equities User Guide" +metadata: + title: "24/5 US Equities User Guide | Chainlink Data Streams" + description: "User guide for Chainlink 24/5 U.S. Equities Streams, covering schema, feeds, continuous price feed composition, and risk management." +whatsnext: + { + "Find the schema of data to expect from Data Streams reports: RWA Advanced (v11)": "/data-streams/reference/report-schema-v11", + "Learn about Data Streams market hours and schedules": "/data-streams/market-hours", + } +--- + +import { Aside, ClickToZoom } from "@components" +import { Tabs } from "@components/Tabs" + +Chainlink 24/5 U.S. Equities Streams provide real-time equity pricing data across all major U.S. single-name equities and ETFs spanning regular, pre-market, post-market, and overnight trading sessions. The [advanced RWA schema](/data-streams/reference/report-schema-v11) includes fields such as market status flags, best bid and ask prices, bid and ask volumes, staleness measures, and last traded prices to facilitate more advanced execution and risk management. + + + +The data referenced in this document covers 24/5 trading hours in US equities on a range of traditional venues. While there is currently no trading activity in traditional markets over the weekend on any venue, protocols can extend their pricing coverage to 24/7 in multiple ways, such as leveraging the pricing of [tokenized stocks](#stream-switching-example-logic) on secondary markets such as CEXes and DEXes. + +Developers are responsible for choosing the appropriate feed and ensuring that the operation and performance of their choice matches expectations. For more information, please visit the Chainlink [documentation](/data-streams/developer-responsibilities). + +## Schema + +The data is delivered using the [RWA Advanced (v11) schema](/data-streams/reference/report-schema-v11). + +This advanced RWA schema is built to support 24/5 streams, including DON Consensus `mid` price (with its corresponding timestamp `lastSeenTimestampNs` for staleness tracking), order book depth (`bid`, `ask`, `bidVolume`, `askVolume`), execution data (`lastTradedPrice`), and granular market phases (`marketStatus` values for Pre-market, Regular hours, Post-market, Overnight, and Weekend). + + + + + +## Feeds + +Each instrument is exposed through three distinct data streams feeds, each corresponding to a specific trading phase: **Regular Hours**, **Extended Hours**, and **Overnight Hours**. + +[Click here to view a list of RWA streams that support 24-5 US equities](/data-streams/rwa-streams?page=1&testnetPage=1&show24x5=true). Use the filters to select your desired time segment. + +For example, **TSLA** is available via the [following streams](/data-streams/rwa-streams?page=1&testnetPage=1&show24x5=true&search=tsla): + +- `TSLA/USD-Streams-ExtendedHours` +- `TSLA/USD-Streams-OvernightHours` +- `TSLA/USD-Streams-RegularHours` + +To construct a **continuous price feed**, users must **dynamically switch** between these individual streams based on the value of `marketStatus`. The mapping logic is as follows: + +| Market Status | Stream | +| ----------------- | --------------------------------- | +| `1` (Pre-market) | `TSLA/USD-Streams-ExtendedHours` | +| `2` (Regular) | `TSLA/USD-Streams-RegularHours` | +| `3` (Post-market) | `TSLA/USD-Streams-ExtendedHours` | +| `4` (Overnight) | `TSLA/USD-Streams-OvernightHours` | + + + +## Building a Continuous Price Feed + +Building a continuous price feed by dynamically switching streams requires robust exception handling to manage edge cases effectively. Because different protocols have unique risk profiles and design requirements, Data Streams allows you to implement custom logic tailored to your specific needs. + +There is no one-size-fits-all solution to integrating 24/5 streams. The sections below outline edge cases you will encounter when building a continuous price feed along with recommended mitigation strategies. For information on structural risks and protocol-specific considerations, see the [Risks](#risks) section. + +If you wish to jump ahead to view an example of switching logic, jump to [Stream Switching Example Logic](#stream-switching-example-logic). + +### Edge Cases and Mitigation + +#### Price Jumps at Session Transition Boundaries + +When transitioning between Regular ↔ Extended ↔ Overnight sessions, noticeable price dislocations can occur. + +These differences are expected and normal due to unique liquidity conditions, venues, participants, and pricing sources per session. These are not bad data; they are true market microstructure effects. + +Typical jumps are **1–2%**, but **larger spikes (10–20%+)** are possible during low-liquidity environments or impactful news cycles. + + + +##### Mitigation + +**Phase-specific streams are provided intentionally** to give users control over when and how transitions occur. Optional safeguards: + +- Pause or lock market activity during transition windows +- Delay feed switching until price convergence or stability threshold is met +- Apply price smoothing (EMA/VWAP/TWAP) across transition windows +- Temporarily reference [tokenized asset](#stream-switching-example-logic) price (where available) + +#### Market Status Unknown/Unavailable (`marketStatus = 0`) + +The system may return `marketStatus = 0` (Unknown). **If your implementation relies on automated feed switching based on market status, you must account for this scenario.** + +Market status is sourced from several independent providers configured as primary/fallback. While resilient, multiple providers can fail simultaneously. + +##### Mitigation + +Consumers must treat `marketStatus = 0` (Unknown) as a valid state and define deterministic behaviors when it is returned. Potential actions include: + +- Pause or lock market activity +- Allow restricted trading within a bounded range (e.g., last-valid price ± threshold) +- Temporarily reference [tokenized asset](#stream-switching-example-logic) price (where available) + +#### Weekends (`marketStatus = 5`) + +Traditional equity markets are closed on weekends, so all three feeds will carry stale values. This reflects true underlying market inactivity rather than an outage or failure. + +##### Mitigation + +Consumers must treat `marketStatus = 5` (Weekend) as a valid state and define deterministic behaviors when it is returned. Potential actions include: + +- Pause or lock market activity +- Allow restricted trading within a bounded range (e.g., last-valid price ± threshold) +- Temporarily reference [tokenized asset](#stream-switching-example-logic) price (where available) + +#### Stale Data Detection + +Markets may stop updating due to exchange outages, circuit breakers, trading halts, or corporate actions. Use the `lastSeenTimestampNs` field (which reflects the timestamp of the last update for the `mid` price only) to detect staleness by comparing it against the current time. When this timestamp stops advancing, it indicates the underlying venue has stopped providing updates. + +Phase-specific feeds can introduce unique behavior due to venue-specific operational characteristics and market microstructure. The following are some examples of scenarios that may occur during session transitions or under specific market conditions: + +##### Regular Hours Session: Delayed Quote Availability at Market Open + +During the first 10–20 seconds after regular hours open (9:30am ET), bid/ask quotes may not yet be available from the regular hours venue. In those cases, the reported price may still reflect the previous regular hours close rather than live market data. + +Users should factor this transition period into their switching logic and consider alternative strategies during the first ~20 seconds of regular hours, such as: + +- Pause or lock market activity +- Continue using the pre-market (Extended Hours) stream until fresh regular hours quotes are available +- Temporarily reference [tokenized asset](#stream-switching-example-logic) price (where available) + +##### Overnight Session: Stale Bid/Ask at Session Start + +During the early overnight session -- before the overnight venue begins publishing data -- the feed may display the last bid/ask prices and volumes from the previous regular session. This occurs because no new quotes are available yet from the overnight venue. + +Once the overnight venue starts publishing its own quotes, the data will update to reflect current overnight market conditions. This behavior is normal market microstructure, not a data quality issue. It reflects the actual state of the market during the transition period when overnight liquidity has not yet begun. + +Users relying on bid/ask data during early overnight hours should be aware of this carryover behavior and implement appropriate safeguards, such as checking `lastSeenTimestampNs` for staleness or widening risk parameters during overnight session transitions. + +##### Mitigation + +Consumers must have fallback logic in place when the data is stale. Potential actions include: + +- Pause or lock market activity +- Use last-valid price as reference +- Allow bounded-range trading based on last-valid price +- Temporarily reference [tokenized asset](#stream-switching-example-logic) price (where available) + +### Stream Switching Example Logic + +The following examples demonstrate how to implement a continuous price feed by dynamically switching between phase-specific streams. These examples use tokenized asset prices as the fallback strategy for edge cases (stale data, Unknown market status, and Weekends). Developers may choose alternative mitigation strategies based on their protocol's risk requirements. + +Developers interested in using tokenized assets can find the list of supported assets and schema in the [Tokenized Assets documentation](/data-streams/backed-streams). Using tokenized assets carries its own risks, including liquidity limitations and price deviations from spot markets. Evaluate these factors carefully before integrating tokenized prices into your protocol. + + + +#### Decision Flow + +To build a continuous price feed, follow this general decision flow. This is a simplified outline that leverages tokenized asset prices as fallback; your implementation must account for all risks outlined above and in the [Risks](#risks) section below. + +1. **Fetch and decode** the Regular Hours stream report to get `marketStatus` and `lastSeenTimestampNs` + +2. **Check staleness first:** + - **If data is stale** (timestamp older than your threshold) → **[Use Tokenized Asset stream](/data-streams/backed-streams)** or apply custom risk mitigation + - **If data is fresh** → Continue to step 3 + +3. **Route based on market status:** + - **`marketStatus = 0`** (Unknown) → **Use Tokenized Asset stream** or apply custom risk mitigation + - **`marketStatus = 1`** (Pre-market) → **Use Extended Hours stream** + - **`marketStatus = 2`** (Regular) → **Use Regular Hours stream** + - **`marketStatus = 3`** (Post-market) → **Use Extended Hours stream** + - **`marketStatus = 4`** (Overnight) → **Use Overnight Hours stream** + - **`marketStatus = 5`** (Weekend) → **Use Tokenized Asset stream** or apply custom risk mitigation + +4. **Apply additional safeguards** as needed for your protocol (e.g., price jump checks, circuit breakers, holiday calendars, bounded trading ranges) + +5. **Return the `mid` price** from the selected stream + + + +#### Example Implementation Logic + +This example demonstrates switching logic with tokenized asset prices as fallback. View examples in different SDK languages. + +Please note that these code snippets are illustrative and may require adaptation to fit your specific environment, SDK versions, and error handling practices. Refer to the guide to [fetch](/data-streams/tutorials/go-sdk-fetch) and [stream](/data-streams/tutorials/go-sdk-stream) decoded reports in your chosen SDK. + +
+ +{/* prettier-ignore */} + + TypeScript + Go + Rust + + ```typescript + import { createClient, decodeReport } from "@chainlink/data-streams-sdk" + + const client = createClient({ apiKey, userSecret, endpoint }) + + async function getPrice() { + const regularReport = await client.getLatestReport(REGULAR_HOURS) + const decoded = decodeReport(regularReport.fullReport, regularReport.feedID) + + // Check staleness (5 minute threshold) + const isStale = (Date.now() - decoded.lastSeenTimestampNs / 1000000) > 300000 + + // Determine which stream to use + if (isStale || decoded.marketStatus === 0 || decoded.marketStatus === 5) { + const tokenReport = await client.getLatestReport(TOKENIZED_TSLA) + return decodeReport(tokenReport.fullReport, tokenReport.feedID).mid + } else if (decoded.marketStatus === 1 || decoded.marketStatus === 3) { + const report = await client.getLatestReport(EXTENDED_HOURS) + return decodeReport(report.fullReport, report.feedID).mid + } else if (decoded.marketStatus === 2) { + return decoded.mid + } else if (decoded.marketStatus === 4) { + const report = await client.getLatestReport(OVERNIGHT_HOURS) + return decodeReport(report.fullReport, report.feedID).mid + } + } + ``` + + + + ```go + import "github.com/smartcontractkit/data-streams-sdk/go/feed" + + func getPrice() (*big.Int, error) { + report, err := client.GetLatestReport(REGULAR_HOURS) + if err != nil { + return nil, err + } + + decoded, err := feed.Decode(report.FullReport) + if err != nil { + return nil, err + } + + // Check staleness (5 minute threshold) + isStale := time.Since(decoded.LastSeenTimestamp) > 5*time.Minute + + // Determine which stream to use + if isStale || decoded.MarketStatus == 0 || decoded.MarketStatus == 5 { + tokenReport, _ := client.GetLatestReport(TOKENIZED_TSLA) + tokenDecoded, _ := feed.Decode(tokenReport.FullReport) + return tokenDecoded.Mid, nil + } else if decoded.MarketStatus == 1 || decoded.MarketStatus == 3 { + extReport, _ := client.GetLatestReport(EXTENDED_HOURS) + extDecoded, _ := feed.Decode(extReport.FullReport) + return extDecoded.Mid, nil + } else if decoded.MarketStatus == 2 { + return decoded.Mid, nil + } else if decoded.MarketStatus == 4 { + ovnReport, _ := client.GetLatestReport(OVERNIGHT_HOURS) + ovnDecoded, _ := feed.Decode(ovnReport.FullReport) + return ovnDecoded.Mid, nil + } + } + ``` + + + + ```rust + use data_streams_sdk::{client::Client, feed}; + + async fn get_price() -> Result> { + let report = client.get_latest_report(REGULAR_HOURS).await?; + let decoded = feed::decode(&report.full_report)?; + + // Check staleness (5 minute threshold) + let is_stale = (SystemTime::now().duration_since(UNIX_EPOCH)?.as_nanos() + - decoded.last_seen_timestamp_ns as u128) > 300_000_000_000; + + // Determine which stream to use + if is_stale || decoded.market_status == 0 || decoded.market_status == 5 { + let token_report = client.get_latest_report(TOKENIZED_TSLA).await?; + let token_decoded = feed::decode(&token_report.full_report)?; + Ok(token_decoded.mid) + } else if decoded.market_status == 1 || decoded.market_status == 3 { + let ext_report = client.get_latest_report(EXTENDED_HOURS).await?; + let ext_decoded = feed::decode(&ext_report.full_report)?; + Ok(ext_decoded.mid) + } else if decoded.market_status == 2 { + Ok(decoded.mid) + } else if decoded.market_status == 4 { + let ovn_report = client.get_latest_report(OVERNIGHT_HOURS).await?; + let ovn_decoded = feed::decode(&ovn_report.full_report)?; + Ok(ovn_decoded.mid) + } else { + Err("Unknown market status".into()) + } + } + ``` + + + + + + +## Risks + +While 24/5 streams provide extended market coverage, they introduce specific risks related to liquidity, volatility, and data sourcing. Users must understand these factors and implement appropriate safeguards. + +In the following sections, we outline key risks and recommended mitigation strategies. + +### Single Provider for Extended & Overnight Data + +Extended and overnight session price feeds are currently sourced from a single data provider, making these sessions less reliable than the regular hours price feed which is multi-sourced. + +If the provider experiences downtime, technical failures, or connectivity disruption, the feed may flatline or report highly inaccurate figures, preventing users from reacting to real price movements. Such issues may lead to mispricing, failed liquidations, and potential bad debt accumulation. + +##### Mitigation + +The feed includes a staleness indicator, allowing consumers to detect when data stops updating. Users are strongly recommended to implement fallback logic within their protocol risk framework, which may include: + +- Pause or lock market activity +- Restrict to narrow price bands +- Temporarily switch to the tokenized price feed (understanding that it also carries liquidity limitations) + +### Structural Illiquidity and Volatility in Extended & Overnight Hours + +Pre-market and post-market sessions are typically thinly traded, with fragmented liquidity and higher spreads, leading to stale ticks, price gaps, and elevated volatility. These conditions are inherent to the market, not to the feed, and will be visible in the published data. + +##### Mitigation + +Users should evaluate whether the full 24/5 price coverage is appropriate for their use case. Consider the following: + +- Configure risk thresholds, circuit breakers, or mode switching aligned with your risk appetite +- Validate these configurations during integration and simulation, not post-deployment + +### Corporate Actions + +Traditional equities are subject to corporate actions which can dramatically change the price of an asset overnight, especially in the case of stock splits and reverse stock splits. These actions are usually announced outside regular trading hours and can cause substantial price movements when markets reopen. + +Additionally, the overnight session data provider may disable trading for individual symbols during pending corporate actions such as dividends, splits, or mergers. When this occurs, there will be no overnight session data available for that specific symbol, and this closure will not be reflected in the `marketStatus` field. The overnight feed may continue to display stale data from the previous session, or the data may flatline, making it critical to monitor `lastSeenTimestampNs` for staleness detection. + +##### Mitigation + +Consumers should: + +- Actively monitor corporate action announcements +- Adjust pricing logic, risk parameters, and open positions accordingly +- Consider pausing markets during corporate action windows to prevent unfair liquidations +- Implement staleness checks on `lastSeenTimestampNs` to detect when overnight session data stops updating due to symbol-specific trading halts + +### Market Closures and Halts Are Not Explicitly Flagged + +Market Status data providers do not flag exchange public holidays or trading halts. As a result, the feeds for instruments listed on U.S. exchanges may appear stale, flatline, or behave inconsistently during these periods even though this reflects true market inactivity. + +Trading halts can occur for various reasons including regulatory actions, pending news announcements, volatility circuit breakers, or operational issues. Similar to holidays, when the underlying market is halted, this will not be reflected in the `marketStatus` field. + +Automated switching logic that relies only on `marketStatus` or staleness signals can incorrectly interpret holiday or halt inactivity as an outage or unexpected feed degradation, leading to unnecessary fallbacks, paused markets, or erroneous risk decisions. + +##### Mitigation + +Consumers must: + +- Incorporate an authoritative exchange holiday calendar into their integration (for U.S. listings, the NYSE/NASDAQ holiday calendar is the recommended source) +- Monitor exchange halt notifications and adjust protocol behavior accordingly +- Keep markets closed during exchange holidays to prevent users from trading at unfair prices +- Implement appropriate safeguards when trading halts are detected to prevent unfair liquidations or trades at stale prices + +For detailed market hours and trading schedules, see the [Market Hours](/data-streams/market-hours) documentation. diff --git a/src/content/data-streams/rwa-streams/handling-market-events-v11.mdx b/src/content/data-streams/rwa-streams/handling-market-events-v11.mdx new file mode 100644 index 00000000000..43de59d344c --- /dev/null +++ b/src/content/data-streams/rwa-streams/handling-market-events-v11.mdx @@ -0,0 +1,176 @@ +--- +section: dataStreams +date: "Last Modified" +title: "Handling Market Events (v11)" +metadata: + title: "Handling Market Events (v11) | Chainlink Data Streams" + description: "Learn how to handle market hours, volatility, and corporate actions when using Chainlink Data Streams with the v11 schema." +whatsnext: + { + "Learn about Data Streams market hours and schedules": "/data-streams/market-hours", + "Find the schema of data to expect from Data Streams reports: RWA Advanced (v11)": "/data-streams/reference/report-schema-v11", + } +--- + +import { Aside } from "@components" +import MarketEventsTabs from "@features/data-streams/common/MarketEventsTabs.astro" + + + + + +Apply these best practices when integrating or operating markets that use tokenized real-world assets during standard market hours. Developers and operators are responsible for assessing market integrity, implementing mitigations, and managing application-level risks — see the [Developer Responsibilities](/data-streams/developer-responsibilities) guidance for details. + +## Market Hours + +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`, `3`, `4`, `5` (Not Regular Hours).
  • `lastUpdateTimestamp`: Timestamp of the closing price of the last session.
| Keep markets closed while `marketStatus != 2` 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 avoid 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` (Regular Hours).
  • `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` (Regular Hours).
  • `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` (Regular Hours).
  • `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` (Regular Hours).
  • `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` (Regular Hours).
  • `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`, `3`, `4`, `5` (Not Regular Hours).
  • `lastUpdateTimestamp`: Closing timestamp of the last session.
| Monitor delisting news during `marketStatus != 2` 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`, `3`, `4`, `5` (Not Regular Hours).
  • `lastUpdateTimestamp`: Last close.
| Monitor spin-off and split announcements while `marketStatus != 2`.

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`, `3`, `4`, `5` (Not Regular Hours).
  • `lastUpdateTimestamp`: Last close.
| Monitor spin-off and split announcements while `marketStatus != 2`.

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`, `3`, `4`, `5` (Not Regular Hours).
  • `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 an 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`, `3`, `4`, `5` (Not Regular Hours).
  • `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`, `3`, `4`, `5` (Not Regular Hours).
  • `lastUpdateTimestamp`: Last close.
| Monitor liquidation thresholds closely to prevent accumulating bad debt. | diff --git a/src/content/data-streams/rwa-streams/handling-market-events.mdx b/src/content/data-streams/rwa-streams/handling-market-events.mdx new file mode 100644 index 00000000000..0386352fed4 --- /dev/null +++ b/src/content/data-streams/rwa-streams/handling-market-events.mdx @@ -0,0 +1,170 @@ +--- +section: dataStreams +date: "Last Modified" +title: "Handling Market Events" +metadata: + title: "Handling Market Events | Chainlink Data Streams" + description: "Learn how to handle market hours, volatility, and corporate actions when using Chainlink Data Streams." +whatsnext: + { + "Learn about Data Streams market hours and schedules": "/data-streams/market-hours", + "Find the schema of data to expect from Data Streams reports: RWA": "/data-streams/reference/report-schema-v8", + } +--- + +import { Aside } from "@components" +import MarketEventsTabs from "@features/data-streams/common/MarketEventsTabs.astro" + + + +Apply these best practices when integrating or operating markets that use tokenized real-world assets. Developers and operators are responsible for assessing market integrity, implementing mitigations, and managing application-level risks — see the [Developer Responsibilities](/data-streams/developer-responsibilities) guidance for details. + +## Market Hours + +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 avoid 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 an 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/features/data-streams/common/MarketEventsTabs.astro b/src/features/data-streams/common/MarketEventsTabs.astro new file mode 100644 index 00000000000..25fa87baa76 --- /dev/null +++ b/src/features/data-streams/common/MarketEventsTabs.astro @@ -0,0 +1,20 @@ +--- +import { PageTabs } from "@components" + +const marketEventsPages = [ + { + name: "Standard (v8)", + url: "/data-streams/rwa-streams/handling-market-events", + }, + { + name: "Advanced (v11)", + url: "/data-streams/rwa-streams/handling-market-events-v11", + }, +] +--- + + diff --git a/src/features/feeds/components/FeedList.tsx b/src/features/feeds/components/FeedList.tsx index 43d809409b1..00afb136dea 100644 --- a/src/features/feeds/components/FeedList.tsx +++ b/src/features/feeds/components/FeedList.tsx @@ -30,6 +30,7 @@ export type DataFeedType = type SchemaFilterValue = "all" | "v8" | "v11" type StreamsRwaFeedTypeValue = "all" | "datalink" | "equities" | "forex" +type TradingHoursFilterValue = "all" | "regular" | "extended" | "overnight" type FilterOption = { label: string @@ -60,10 +61,19 @@ const feedTypeFilterOptions: FilterOption[] = [ { label: "Forex Streams", value: "forex" }, ] +const tradingHoursFilterOptions: FilterOption[] = [ + { label: "All Time Segments", value: "all" }, + { label: "Regular Hours", value: "regular" }, + { label: "Extended Hours", value: "extended" }, + { label: "Overnight Hours", value: "overnight" }, +] + const isSchemaFilterValue = (value: unknown): value is SchemaFilterValue => value === "all" || value === "v8" || value === "v11" const isStreamsRwaFeedTypeValue = (value: unknown): value is StreamsRwaFeedTypeValue => value === "all" || value === "datalink" || value === "equities" || value === "forex" +const isTradingHoursFilterValue = (value: unknown): value is TradingHoursFilterValue => + value === "all" || value === "regular" || value === "extended" || value === "overnight" const FilterDropdown = ({ label, @@ -311,6 +321,19 @@ export const FeedList = ({ const [showOnlyMVRFeedsTestnet, setShowOnlyMVRFeedsTestnet] = useState(false) const [showOnlyDEXFeeds, setShowOnlyDEXFeeds] = useState(false) const [showOnlyDEXFeedsTestnet, setShowOnlyDEXFeedsTestnet] = useState(false) + const [show24x5FeedsParam, setShow24x5FeedsParam] = useQueryString("show24x5") + const show24x5Feeds = show24x5FeedsParam === "true" + const setShow24x5Feeds = (value: boolean) => { + setShow24x5FeedsParam(value ? "true" : []) + } + const [tradingHoursFilterParam, setTradingHoursFilterParam] = useQueryString("tradingHours") + const tradingHoursFilter = + typeof tradingHoursFilterParam === "string" && isTradingHoursFilterValue(tradingHoursFilterParam) + ? tradingHoursFilterParam + : "all" + const setTradingHoursFilter = (next: TradingHoursFilterValue) => { + setTradingHoursFilterParam(next === "all" ? [] : next) + } const [rwaSchemaFilterParam, setRwaSchemaFilterParam] = useQueryString("schema") const rwaSchemaFilter = typeof rwaSchemaFilterParam === "string" && isSchemaFilterValue(rwaSchemaFilterParam) ? rwaSchemaFilterParam : "all" @@ -325,6 +348,19 @@ export const FeedList = ({ const setTestnetRwaSchemaFilter = (next: SchemaFilterValue) => { setTestnetRwaSchemaFilterParam(next === "all" ? [] : next) } + const [show24x5FeedsTestnetParam, setShow24x5FeedsTestnetParam] = useQueryString("testnetShow24x5") + const show24x5FeedsTestnet = show24x5FeedsTestnetParam === "true" + const setShow24x5FeedsTestnet = (value: boolean) => { + setShow24x5FeedsTestnetParam(value ? "true" : []) + } + const [testnetTradingHoursFilterParam, setTestnetTradingHoursFilterParam] = useQueryString("testnetTradingHours") + const testnetTradingHoursFilter = + typeof testnetTradingHoursFilterParam === "string" && isTradingHoursFilterValue(testnetTradingHoursFilterParam) + ? testnetTradingHoursFilterParam + : "all" + const setTestnetTradingHoursFilter = (next: TradingHoursFilterValue) => { + setTestnetTradingHoursFilterParam(next === "all" ? [] : next) + } const [openDropdownId, setOpenDropdownId] = useState(null) const handleDropdownToggle = (dropdownId: string, isOpen: boolean) => { setOpenDropdownId((current) => { @@ -1061,7 +1097,42 @@ export const FeedList = ({ setCurrentPage("1") }} /> - {(searchValue || rwaSchemaFilter !== "all" || streamCategoryFilter !== "all") && ( +
+ +
+ {show24x5Feeds && ( + handleDropdownToggle("main-trading-hours", isOpen)} + onClose={closeAllDropdowns} + label="Time segment" + options={tradingHoursFilterOptions} + value={tradingHoursFilter} + groupId="trading-hours-main" + onSelect={(next) => { + setTradingHoursFilter(next) + setCurrentPage("1") + }} + /> + )} + {(searchValue || rwaSchemaFilter !== "all" || streamCategoryFilter !== "all" || show24x5Feeds) && (