CapitalFlow Developer API

v1 · Read Only

Options Flow Data API

Access the same institutional-grade options flow data that powers the CapitalFlow exchange terminal. Query trades, top contracts, and order flow analytics programmatically — or connect your AI tools via MCP.

Authentication

Include your API key in the X-API-Key header with every request. Generate keys from the Developer Dashboard.

X-API-Key: cfsk-your-api-key-here

Trades

Query live and historical options trade data from the CapitalFlow exchange. Trades are sourced in real-time from OPRA and reflect institutional-level order flow including sweeps, blocks, and multi-leg spreads. Data is partitioned by trade date for efficient historical lookups. When no date range is specified, defaults to the last 7 days.

GET/v1/tradesQuery options trades with filters
Parameters
Parameter Type Default Description
symbols string[] — Filter by one or more ticker symbols (1–10 letters each, e.g. SPY). Pass multiple via ?symbols=SPY&symbols=AAPL
premiumMinimum number 25000 Minimum total premium spent (price × size × 100). Must be non-negative
minCreated ISO 8601 7 days ago Start of time window, e.g. 2026-03-10T09:30:00Z. Must be before maxCreated when both are provided
maxCreated ISO 8601 now End of time window. Must be after minCreated when both are provided
tradeDirectionType string — C for calls, P for puts. Returns 400 for other values
unusual boolean false When true, returns only trades flagged as unusual activity (volume > open interest)
limit integer 100 Results per page (1–500). Returns 400 if outside range
offset integer 0 Pagination offset for scrolling through large result sets (0–10,000)
Example Request
# Get unusual SPY call trades over $50k premium curl -H "X-API-Key: cfsk-your-key" \ "https://developer.capitalflow.app/v1/trades?symbols=SPY&tradeDirectionType=C&unusual=true&premiumMinimum=50000"
Response Fields
Field Type Description
id string Unique trade identifier (contract descriptor)
created string Trade timestamp in Eastern Time (ISO 8601)
symbol string Underlying ticker symbol (e.g. SPY, AAPL)
contract string Full contract identifier
strike number Option strike price
expiration string Contract expiration date (YYYY-MM-DD)
type string C (call) or P (put)
price number Fill price per contract
size integer Number of contracts traded
premium number Total premium spent (price × size × 100)
bid number? NBBO bid at time of execution
ask number? NBBO ask at time of execution
sentiment string? Inferred trade sentiment: BULLISH, BEARISH, or NEUTRAL. Only populated when unusual=true
additionalType string? Trade execution type: SWEEP, BLOCK, SPLIT, etc. Only populated when unusual=true
unusual boolean Flagged as unusual activity (volume exceeds open interest)
totalVolume integer? Total daily volume on this contract at time of trade
openInterest integer? Open interest on the contract
Example Response
[ { "id": "SPY260320C00575000", "created": "2026-03-17T10:32:15.123-04:00", "symbol": "SPY", "contract": "SPY260320C00575000", "strike": 575.0, "expiration": "2026-03-20", "type": "C", "price": 3.45, "size": 500, "premium": 172500.0, "bid": 3.40, "ask": 3.50, "sentiment": "BULLISH", "additionalType": "SWEEP", "unusual": true, "totalVolume": 12450, "openInterest": 8200 } ]

Orders

Aggregated order flow analytics computed from the raw trade stream. Top contracts ranks individual option contracts by total premium accumulated throughout the current trading session. This surfaces where the biggest institutional bets are concentrated — useful for identifying conviction trades and significant positioning.

GET/v1/orders/top-contractsHighest premium contracts today
Parameters
Parameter Type Default Description
symbol string — Filter by a single ticker symbol (1–10 letters, e.g. AAPL). Omit for all symbols
limit integer 50 Number of top contracts to return (1–500). Returns 400 if outside range
Example Request
# Top 10 most heavily traded AAPL contracts today curl -H "X-API-Key: cfsk-your-key" \ "https://developer.capitalflow.app/v1/orders/top-contracts?symbol=AAPL&limit=10"
Response Fields
Field Type Description
trade_date string Trading session date (YYYY-MM-DD)
symbol string Underlying ticker symbol
contract string Full option contract identifier
strike number Strike price
expiration string Contract expiration date (YYYY-MM-DD)
type string C (call) or P (put)
total_premium number Aggregate premium across all fills on this contract today
total_contracts integer Total number of contracts traded
fill_count integer Number of individual trade executions (fills)
first_seen string? Timestamp of the first trade on this contract today
last_seen string? Timestamp of the most recent trade
Example Response
[ { "trade_date": "2026-03-17", "symbol": "AAPL", "contract": "AAPL260321C00230000", "strike": 230.0, "expiration": "2026-03-21", "type": "C", "total_premium": 1250000.0, "total_contracts": 4200, "fill_count": 37, "first_seen": "2026-03-17T09:31:02.000-04:00", "last_seen": "2026-03-17T15:42:18.000-04:00" } ]

Reports

AI-generated market analysis reports produced by CapitalFlow throughout the trading day. Hourly movers highlight the most significant flow during each trading hour. Daily summaries provide an end-of-day recap of key options activity, sentiment shifts, and notable positioning across the market. Report listing endpoints support cursor-based pagination — use the created timestamp of the last result as the before parameter to fetch the next page.

GET/v1/reports/hourlyHourly mover analysis reports
Parameters
Parameter Type Default Description
limit integer 20 Number of reports to return, most recent first (1–50)
before ISO 8601 — Cursor for pagination. Only reports created before this timestamp are returned. Use the created field of the last result to page through older reports
Example Request
# Get the 5 most recent hourly mover reports curl -H "X-API-Key: cfsk-your-key" \ "https://developer.capitalflow.app/v1/reports/hourly?limit=5" # Page through older reports using the created timestamp curl -H "X-API-Key: cfsk-your-key" \ "https://developer.capitalflow.app/v1/reports/hourly?limit=5&before=2026-03-17T10:05:00.000Z"
Response Fields
Field Type Description
id string Unique report identifier (UUID)
title string Report title
description string Brief summary of the report's key findings
slug string URL-friendly slug for linking to the full report
created string Report generation timestamp (ISO 8601)
type string Report type
Example Response
[ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "10:00 AM Hourly Movers", "description": "SPY calls surged with 2.1M in premium. NVDA block trades dominated the session.", "slug": "hourly-movers-2026-03-17-10am", "created": "2026-03-17T10:05:00.000Z", "type": "movers" } ]
GET/v1/reports/dailyDaily market summary reports
Parameters
Parameter Type Default Description
limit integer 20 Number of reports to return, most recent first (1–50)
before ISO 8601 — Cursor for pagination. Only reports created before this timestamp are returned. Use the created field of the last result to page through older reports
Example Request
# Get the latest daily summary curl -H "X-API-Key: cfsk-your-key" \ "https://developer.capitalflow.app/v1/reports/daily?limit=1"
Response Fields
Field Type Description
id string Unique report identifier (UUID)
title string Report title
description string Brief summary of the report's key findings
slug string URL-friendly slug for linking to the full report
created string Report generation timestamp (ISO 8601)
type string Report type
Example Response
[ { "id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321", "title": "Daily Summary — March 17, 2026", "description": "Bullish sentiment dominated with $18.3M in call premium vs $9.1M in puts. TSLA and NVDA led institutional positioning.", "slug": "daily-summary-2026-03-17", "created": "2026-03-17T16:30:00.000Z", "type": "daily-summary" } ]
GET/v1/reports/{slug}/contentFull report analysis content

Retrieves the full analysis content for a specific report. The listing endpoints (/hourly and /daily) return metadata only — use the slug from those responses to fetch the complete analysis here. Content is stored separately to keep list responses lightweight and token-efficient for AI integrations.

Path Parameters
Parameter Type Description
slug string Report slug from the listing endpoint response. Must be alphanumeric and hyphens only (max 200 characters)
Example Request
# Get the full content of a specific report curl -H "X-API-Key: cfsk-your-key" \ "https://developer.capitalflow.app/v1/reports/hourly-movers-2026-03-17-10am/content"
Response Fields
Field Type Description
title string Report title
summary string High-level summary of the report (markdown)
overview string Detailed analysis body (markdown)
conclusion string Concluding remarks and key takeaways
insights array Individual contract-level insights, each with contract, heading, and detail
Example Response
{ "title": "10:00 AM Hourly Movers", "summary": "SPY calls surged with $2.1M in premium...", "overview": "## Market Overview\n\nThe 10 AM hour saw significant...", "conclusion": "Institutional positioning remains bullish...", "insights": [ { "contract": "SPY260320C00575000", "heading": "SPY 575C — Aggressive sweep activity", "detail": "12 sweeps totaling $1.4M in premium..." } ] }

MCP Integration

Model Context Protocol

CapitalFlow exposes an MCP server so your AI coding tools and chat agents can query real-time options flow data. Two transports are available:

Streamable HTTP (recommended): https://developer.capitalflow.app/mcp

SSE (legacy): https://developer.capitalflow.app/mcp/sse

Authentication: Claude Desktop uses OAuth 2.1 (auto-discovered, no manual config needed). All other clients use an API key via the X-API-Key header.

Available Tools:

  • get_trades — Query options trades with symbol, premium, date, and direction filters
  • get_top_contracts — Retrieve the 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 the full analysis content for a report by slug

Setup Instructions

Click any client below to see step-by-step setup. Replace YOUR_API_KEY with your actual key.

Claude DesktopOAuth▶
  1. Open Claude Desktop → Settings → Developer → Add MCP Server
  2. Enter the server URL: https://developer.capitalflow.app/mcp
  3. Claude Desktop will automatically discover OAuth configuration and prompt you to sign in with your CapitalFlow account.
  4. Approve the authorization request, and you're connected — no API key needed.

How it works: Claude Desktop uses OAuth 2.1 with auto-discovery (RFC 9728). It reads the protected resource metadata, registers as an OAuth client with Supabase, and handles token exchange automatically.

Claude Code (CLI)Streamable HTTP▶
  1. Run the following in your terminal:
claude mcp add capitalflow \ --transport http \ --url https://developer.capitalflow.app/mcp \ --header "X-API-Key: YOUR_API_KEY"
  1. Verify with claude mcp list — you should see capitalflow.
  2. Use in any conversation: "Use the capitalflow tools to get SPY trades"
CursorSSE▶
  1. Open Cursor Settings → Features → MCP Servers → Add New
  2. Or add manually to .cursor/mcp.json in your project root:
{ "mcpServers": { "capitalflow": { "url": "https://developer.capitalflow.app/mcp/sse", "headers": { "X-API-Key": "YOUR_API_KEY" } } } }
  1. Restart Cursor. The tools will appear in Composer (Agent mode).
VS Code (Copilot)Streamable HTTP▶
  1. Create or edit .vscode/mcp.json in your workspace:
{ "servers": { "capitalflow": { "type": "http", "url": "https://developer.capitalflow.app/mcp", "headers": { "X-API-Key": "YOUR_API_KEY" } } } }
  1. Open Copilot Chat (Agent mode) — tools will be listed in the tool picker.
WindsurfSSE▶
  1. Open Windsurf Settings → Cascade → MCP → Add Server → Custom
  2. Add to ~/.codeium/windsurf/mcp_config.json:
{ "mcpServers": { "capitalflow": { "serverUrl": "https://developer.capitalflow.app/mcp/sse", "headers": { "X-API-Key": "YOUR_API_KEY" } } } }
  1. Restart Windsurf. Tools will appear in Cascade chat.
AntigravityStreamable HTTP▶
  1. Open Settings → Tools → MCP Servers → Add Server
  2. Configure the server with the following:
Name: capitalflow Transport: Streamable HTTP URL: https://developer.capitalflow.app/mcp Headers: X-API-Key: YOUR_API_KEY
  1. The CapitalFlow tools will be available in your next conversation.
PerplexitySSE▶
  1. Open Perplexity → Settings → MCP Servers → Add
  2. Enter the server details:
Server Name: capitalflow Server URL: https://developer.capitalflow.app/mcp/sse Auth Header: X-API-Key Auth Token: YOUR_API_KEY
  1. Enable the server toggle, then try: "What are the top SPY options trades today?"
ChatGPTStreamable HTTP▶
  1. Open ChatGPT → Settings → Connected Tools → Add MCP Server
  2. Enter the connection details:
Server URL: https://developer.capitalflow.app/mcp Authentication: API Key Header Name: X-API-Key API Key: YOUR_API_KEY
  1. Save and test with: "Get the top contracts for NVDA"

Rate Limits

Default rate limit is 60 requests/minute per API key. Rate limit headers are included in every response:

X-RateLimit-Limit: 60 X-RateLimit-Remaining: 55 Retry-After: 60 # (only on 429)

When the limit is exceeded, the API returns HTTP 429 with a Retry-After header indicating how many seconds to wait. Sustained abuse (10+ violations in 5 minutes) results in a temporary block. Blocked keys receive HTTP 403 until the block expires.

Troubleshooting

401 Unauthorized
Verify your API key is included as the X-API-Key header (not as a query parameter or Bearer token). Make sure the key has not been revoked in the Developer Dashboard.
429 Too Many Requests
You've exceeded your rate limit. Check the Retry-After header for when to retry. Default limit is 60 requests/minute. Wait and retry, or contact support for a higher limit.
MCP tools not appearing in my client
1. Double-check that the server URL is correct — use /mcp for Streamable HTTP or /mcp/sse for SSE.
2. Ensure your API key is set in the headers configuration, not as a URL parameter.
3. Restart your client after editing the config file.
4. Check the client's MCP server status indicator — it should show connected/green.
MCP connection timeout or "transport error"
Some clients only support SSE transport (/mcp/sse), not Streamable HTTP. Try switching transports. If using a VPN or firewall, ensure HTTPS traffic to developer.capitalflow.app is allowed.
Empty results from get_trades
The default premiumMinimum filter is $25,000 — trades below this threshold are excluded. Set premiumMinimum=0 to see all trades. Also verify that the market was open during the time range you're querying.
500 Internal Server Error
An unexpected error occurred on our end. Try again in a few seconds. If the issue persists, check /health to verify service status, or contact support with the response timestamp.
CapitalFlow Developer API · Dashboard · OpenAPI Spec · LLM Docs