Price API

Overview

A price API provides programmatic market or quoted values for assets, currencies, products, fees, or conversion pairs at a defined time and source. Consumers use prices for display, conversion, risk controls, invoicing, and valuation. A number without source, pair direction, timestamp, precision, and freshness can be misleading. Executable payment quotes should be distinguished from informational market prices and stored with their provenance. A successful transport result from Price API should not be interpreted beyond the exact API state documented by the provider.

Clients should document the pair convention, source methodology, timestamp, update interval, decimal policy, and allowed staleness. Depending on the service, it may return spot prices, bid and ask values, indices, exchange rates, historical candles, or merchant quotes. Thin markets, outliers, stale caches, symbol collisions, and temporary provider failure can produce materially wrong payment amounts or accounting values. They need caching with expiry, rate-limit handling, plausibility checks, and fallback policy. Changes to Price API should be checked against older clients, stored payloads, enum growth, default behavior, and retry assumptions.

Observability for Price API should record operation, version, principal, request ID, latency, retry count, error code, and final state without exposing secrets.

Testing Price API should cover malformed input, denied access, rate limits, timeouts, duplicates, asynchronous completion, and version changes.

The Price API owner should publish stable error semantics and guidance on whether correction, retry, status lookup, or escalation is appropriate.

Data handled by Price API should use documented types, units, timestamp rules, nullable fields, and enum behavior to prevent silent interpretation errors.