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