# Data Provider Integration Guide

## Current status

No external data adapter is implemented or tested. Milestone 2 will first add a deterministic local fixture provider.

## Provider contract

Each adapter returns canonical instruments and timestamped observations with:

- source/provider identity and source symbol;
- UTC event time and data-availability time;
- asset class, venue, currency, and adjustment/corporate-action metadata;
- request parameters, retrieval time, content/data-set digest, and quality outcome;
- explicit handling of pagination, throttling, retryability, and provider errors.

The adapter may not expose vendor SDK objects beyond its own module. Consumer packages receive normalized domain records.

## Candidate data sources

Alpaca’s [market-data documentation](https://docs.alpaca.markets/us/docs/about-market-data-api) describes authenticated HTTP and WebSocket access, US stocks/ETFs, plan-dependent real-time coverage and history availability. Polygon’s [stocks overview](https://polygon.io/docs/rest/stocks/overview?auth=signup) documents US stock REST, WebSocket, and flat-file access and says timestamps are UTC Unix timestamps.

Before implementation, confirm exact current plan, exchange entitlement, historical depth, corporate-action/reference coverage, cache/retention rights, redistribution restrictions, SDK support, and rate limits from current official terms.

## Test strategy

Use recorded, license-permitted fixtures for unit tests; do not place vendor data in the repository without a rights review. Test normalization, invalid/missing/duplicate data, timezone conversion, pagination, retries, 429 responses, timeouts, and data lineage. Credential-gated connectivity tests are opt-in and must never print response headers containing secrets.