[EPIC] Polygon.io HTTP Client

[copyleftdev]

POLYMCP-002

Goals

• Type-safe API request/response handling
• Automatic rate limit handling with backoff
• Connection pooling and keep-alive
• Comprehensive error types with context

Implement a robust async HTTP client for the Polygon.io REST API. Must handle authentication, rate limiting, pagination, and error responses. The client will be used by all MCP tools to fetch market data.

Acceptance Criteria

AC-1

• Given A valid Polygon.io API key
• When The client makes an authenticated request
• Then The API key is included in the Authorization header or query param

AC-2

• Given A rate-limited response (429)
• When The client receives the response
• Then It waits according to retry-after and retries automatically

AC-3

• Given A paginated endpoint
• When Results span multiple pages
• Then The client can iterate through all pages using the cursor

AC-4

• Given An API error response
• When The client receives status >= 400
• Then It returns a typed error with status code, message, and request context

AC-5

• Given The POLYGON_API_KEY environment variable
• When The client is constructed without explicit key
• Then It reads the key from the environment

Technical Context

Crates: reqwest, tokio, serde, serde_json, thiserror, url

Files:

• src/polygon/mod.rs
• src/polygon/client.rs
• src/polygon/error.rs
• src/polygon/types.rs
• src/polygon/pagination.rs

Interfaces

PolygonClient

pub struct PolygonClient { ... }

Main HTTP client for Polygon.io API

PolygonError

pub enum PolygonError { RateLimit { retry_after: Duration }, ... }

Typed errors for API responses

Out of Scope

• WebSocket streaming API
• Local caching layer (future milestone)
• Request batching

---

Source: epics/01-polygon-client.json
Content Hash: 56225b6e5bae0b62

Child Issues: POLYMCP-020, POLYMCP-021, POLYMCP-022