Data Streams 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 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.

Price formation at open/close

Certain assets (e.g., FX open on Sunday afternoon) experience gradual price discovery due to fragmented liquidity and delayed trading activity.

The perpetual DEX should be careful of not opening their market with the last close price.

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.

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.

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.

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.

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.

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.

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.

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.

Share buybacks & stock issuance

Reduced share supply from a buyback can drive stock prices higher, while increase in share supply can lead to price dilution.

Announcements can cause sharp price spikes or sustained moves.

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.

Stock splits

Corporate actions that change the share count (splits and reverse splits) alter per‑share pricing while leaving the underlying economic exposure unchanged. These events 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, 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 xStock's Theoretical Price as price * currentMultiplier.
2. Ahead of the event, newMultiplier and activationDateTime are staged.
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)

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
• T-1: Protocol preparation and monitoring setup
• T0: Multiplier activation (split effective date)
• T+1: Market reopening with adjusted prices
• T+2: Protocol resumption after verification

Announcement (T-2)

A 10:1 AAPL stock split is announced. The report 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 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

The 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 guidance.