A price data oracle does not deliver a context-free number called the market price. It delivers a reported measurement under a particular definition, methodology, and timing policy. To use it well, an application needs to understand the asset, denomination, observation age, numeric scale, and any additional quality information that accompanies the report.
This guide develops a review process for those details. It does not rank providers or recommend an asset. The examples use fictional values to show how a consumer can reject a technically valid report when it does not satisfy the application's purpose. The central idea is simple: preserve the meaning of the measurement until the application has finished deciding whether to act on it.
Name the asset more precisely than its symbol
A short ticker is useful for display, but it is not always a complete identifier. Define the specific asset or reference instrument, its network or issuance context where relevant, and the denomination of the reported value. A wrapped token, an underlying asset, and a redeemable claim can have related but different measurement needs.
Write the intended question in full. A fictional collateral application may need a reference value for one identified token in US dollars. Another application may need a conversion rate between two assets. A third may need an issuer's accounting valuation. These requests can all be described casually as prices while requiring different sources and policies.
Store the stable feed identity in configuration and use human-readable labels only as supporting information. A test should demonstrate that a report with a familiar label but an incorrect identifier is rejected before arithmetic begins.
Identify the kind of price being reported
A last trade, a bid, an ask, a midpoint, an aggregate reference, and an accounting valuation are not identical measurements. Document the chosen feed's methodology and the use your application makes of it. Do not assume that a value suitable for a display is also an executable quote for a large transaction.
Chainlink's feed-selection documentation discusses the characteristics and risks of different feeds. The feed selection reference provides source context for examining a specific deployment. The application still needs to decide whether the feed's meaning matches its own operation.
For a fictional system, compare two reports with the same asset and currency but different methodologies. Write down why one would or would not be acceptable as a fallback for the other. This exercise often exposes compatibility assumptions that a simple interface comparison misses.
Separate observation time from arrival time
A recently received response can contain an old observation. Preserve the timestamp that describes when the underlying data was observed or published under the feed's semantics. Record arrival time separately when it is useful for monitoring. The difference helps distinguish data staleness from slow transport.
Suppose a client retries a request and receives the same report again. The second arrival should not reset the report's freshness. Similarly, republishing or relaying a measurement should not erase its original observation time. Your normalized schema should make these distinctions difficult to lose.
Write separate checks for malformed timestamps, future timestamps, and observations older than the permitted window. Use the relevant application clock and explain any tolerated clock difference. Avoid using an arbitrary timeout chosen only because it made a demonstration pass.
Treat fixed-point arithmetic as part of the interface
A raw integer usually needs a documented scale before it becomes meaningful to a person or another calculation. Pyth's best-practices documentation explains its integer-and-exponent representation and accompanying confidence field; see the Pyth quality reference. Other interfaces may use a decimal count or another explicit convention.
Keep conversions exact for as long as the application requires. A display can format a value for readability, but financial state changes should use a reviewed numeric representation rather than borrowing the display's rounding behavior. Document the supported range and how invalid values are handled.
Test scale conversion independently from the feed adapter. For a fictional value, calculate the expected result on paper. Repeat with a negative exponent, a tiny positive value, and the largest supported integer. Then test the same economic quantity represented at a different scale.
Use uncertainty according to its definition
A confidence measure or uncertainty interval can provide useful information, but its interpretation depends on the provider's methodology. Do not label every such field as a guaranteed bound or assume that all providers use the same statistical meaning. Preserve the definition in the integration documentation.
An application can choose to react conservatively when uncertainty becomes large relative to the reported value. Possible design responses include limiting new exposure, declining a transaction, or requiring further review. These choices need to be justified for the application; a generic percentage copied from another protocol is not a universal safety rule.
Use fixtures that isolate uncertainty from price movement. One report can have an unchanged central value but a much wider uncertainty measure. Another can move substantially while retaining a narrow measure. The consumer should respond according to the policy it actually claims to implement.
Design for closed markets and unavailable reports
Not every underlying market produces observations continuously. A feed may follow a market schedule, and a physical or accounting source may publish only periodically. Define what the application does outside the source's normal reporting window rather than treating every pause as an identical outage.
Pyth's documentation explicitly discusses market hours and stale-price handling. The relevant lesson for a consumer is to inspect the schedule of the specific feed and make availability assumptions explicit. A blockchain that remains active does not make every external market continuously observable.
Represent unavailable data as a distinct state. Do not substitute zero, an unlabeled previous close, or an indefinitely cached value. A user interface can show the last observation with its time while clearly indicating that it is not a currently accepted input for a new operation.
Compare sources without inventing independence
A secondary source can help reveal disagreement, but multiple outputs are not automatically independent evidence. Review whether providers rely on the same market venues, publishers, collection methods, or infrastructure. A shared upstream failure can survive a superficial comparison between two APIs.
When reports disagree, first verify that they measure the same thing. Different observation times, quote currencies, or instrument definitions can explain a discrepancy without either report being malformed. A comparison should normalize only compatible measurements and retain the original metadata for investigation.
Define a disagreement response before enabling it. The fictional application might pause a particular action rather than average two incompatible values. Record which source remains authoritative for historical accounting and whether a later correction can change earlier decisions. Avoid an undocumented “choose whichever looks right” rule.
Monitor the measurement pipeline
Track retrieval success, report age, numeric validity, uncertainty, consumer rejection, and active configuration separately. A fast endpoint can repeatedly return an old observation. A well-formed report can be rejected because the application is configured for the wrong feed. One uptime indicator cannot describe all of those conditions.
Retain enough metadata to investigate an accepted value after the fact. A useful record includes the stable feed identity, observation time, normalized value and scale, relevant quality fields, and the policy version used by the consumer. Store sensitive operational information appropriately.
Build a rehearsal around a fictional incident. Stop updates, introduce a report for the wrong asset, widen uncertainty, and restore a valid stream. Confirm that the interface, consumer, and monitoring system tell a consistent story at each stage.
Conclusion: price quality is an application decision
A price data oracle becomes useful when its measurement definition matches the consumer's purpose. Asset identity, methodology, time, scale, uncertainty, and availability all belong in that match. Reducing them to a single number too early removes information the application may need most.
Continue with the Price Data Oracle overview and the DeFi Oracles section. For an offchain interface, the Oracle API guide shows how an answer envelope can preserve the same context for other consumers.
