# CapitalFlow Developer API

> Read-only REST API and MCP server for real-time institutional options flow data. Query trades, top contracts, and AI-generated market reports — or connect your AI coding tools via Model Context Protocol (MCP).

The CapitalFlow Developer API provides programmatic access to the same institutional-grade options flow data that powers the CapitalFlow exchange terminal. Data is sourced in real-time from OPRA and includes sweeps, blocks, multi-leg spreads, and unusual activity detection.

## Documentation

- [API Documentation](https://developer.capitalflow.app/docs): Full endpoint reference with interactive examples
- [OpenAPI Specification](https://developer.capitalflow.app/openapi.json): OpenAPI 3.1 spec for code generation
- [Full LLM Documentation](https://developer.capitalflow.app/llms-full.txt): Complete API docs in a single markdown file

## API Endpoints

- [GET /v1/trades](https://developer.capitalflow.app/docs#trades): Query options trades with filters (symbol, premium, date range, direction, unusual activity)
- [GET /v1/orders/top-contracts](https://developer.capitalflow.app/docs#top-contracts): Highest premium contracts for the current trading day
- [GET /v1/reports/hourly](https://developer.capitalflow.app/docs#reports): AI-generated hourly mover analysis reports
- [GET /v1/reports/daily](https://developer.capitalflow.app/docs#reports): AI-generated daily market summary reports
- [GET /v1/reports/{slug}/content](https://developer.capitalflow.app/docs#reports): Full report analysis content by slug

## MCP Server

- [MCP Integration Guide](https://developer.capitalflow.app/docs#mcp): Setup instructions for Claude Desktop, Claude Code, VS Code, Cursor, Windsurf, ChatGPT, and more
- **Streamable HTTP**: `https://developer.capitalflow.app/mcp`
- **SSE (legacy)**: `https://developer.capitalflow.app/mcp/sse`

### MCP Tools
- `get_trades` — Query options trades by symbol, premium, date range, and direction
- `get_top_contracts` — Retrieve highest premium contracts for the current session
- `get_hourly_reports` — List recent hourly mover analysis reports
- `get_daily_reports` — List recent daily market summary reports
- `get_report_content` — Fetch full report analysis content by slug

## Authentication

- **REST API**: API key via `X-API-Key` header. Keys created at [Developer Dashboard](https://dashboard.capitalflow.app/developer).
- **MCP (Claude Desktop)**: OAuth 2.1 — auto-discovered, no manual config needed.
- **MCP (other clients)**: API key via `X-API-Key` header.

## Related

- [CapitalFlow Product](https://capitalflow.app/): Main product site
- [Dashboard](https://dashboard.capitalflow.app): Trading terminal (requires login)