> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/sonic-1.0.0-rc-production-architecture/data-and-realtime.md).

# Data & Realtime

Provider-backed price data, analytics, chart contracts, WebSocket projections and HTTP recovery.

SONIC separates commercial price authority from market-data observation. Provider data informs conversion and market context but does not silently rewrite the active Sale Release.

## Market-data provider roles

| Provider                | Primary use                                                   |
| ----------------------- | ------------------------------------------------------------- |
| **Pyth**                | primary production oracle for configured assets               |
| **Birdeye**             | production market-data confirmation where policy requires it  |
| CoinGecko               | public market reference / fallback context                    |
| CoinMarketCap           | market reference / confirmation where licensed and configured |
| Helius                  | Solana RPC/DAS/indexing and asset state                       |
| Solscan                 | explorer/indexer confirmation context                         |
| Raydium                 | venue/pool/liquidity context                                  |
| Orca                    | venue/pool/liquidity context                                  |
| Meteora                 | venue/pool/liquidity context                                  |
| Metaplex-compatible RPC | metadata / digital-asset context                              |

SONIC lookup is keyed by the configured mint address, not by the `SONIC` ticker alone.

## Price observation contract

```ts
type PriceObservation = {
  provider: string;
  assetId: string;
  mint?: string;
  quoteCurrency: "USD" | "USDC" | "EURC";
  price: string;
  observedAt: string;
  confidence?: string;
  stale: boolean;
};
```

Financial math uses atomic integers/decimals and explicit rounding policy. JavaScript floating-point values are display helpers, not ledger authority.

## Analytics structure

```
analytics/
data/charts/
types/charts/
ui/charts/
```

Charts consume persisted observations and domain snapshots. The chart layer may represent balance history, allocation state, price observations, usage, settlement or sale progression only when the underlying dataset is authoritative.

## Realtime model

```
HTTP mutation
→ PostgreSQL commit + durable event/outbox
→ /ws/v1 projection
→ client cache update

WebSocket unavailable
→ GET /api/v1/realtime/events?cursor=...
→ deterministic recovery
```

WebSocket messages are projections. They are never authorization, payment, allocation or entitlement authority.

## Failure behavior

* stale price → mark stale and require refresh where price-sensitive;
* provider disagreement → preserve observations and apply policy threshold;
* provider outage → do not fabricate a live price;
* WebSocket disconnect → continue through cursor-based HTTP polling;
* duplicate event → de-duplicate by durable event ID;
* unknown terminal state → surface recovery status and correlation ID.

{% hint style="info" %}
Commercial SaaS pricing remains controlled by the Pricing Catalog. Oracle conversion is not the commercial source of truth.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/sonic-1.0.0-rc-production-architecture/data-and-realtime.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.