CapitalFlow Developer API

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/trades Query options trades with filters

Parameters

Parameter	Type	Default	Description
symbols	string[]	—	Filter by one or more ticker symbols. Pass multiple via `?symbols=SPY&symbols=AAPL`
premiumMinimum	number	25000	Minimum total premium spent (price × size × 100). Filters out small retail trades
minCreated	ISO 8601	7 days ago	Start of time window, e.g. `2026-03-10T09:30:00Z`
maxCreated	ISO 8601	now	End of time window
tradeDirectionType	string	—	`C` for calls, `P` for puts
unusual	boolean	false	When `true`, returns only trades flagged as unusual activity (volume > open interest)
limit	integer	100	Results per page (1–500)
offset	integer	0	Pagination offset for scrolling through large result sets

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-contracts Highest premium contracts today

Parameters

Parameter	Type	Default	Description
symbol	string	—	Filter by a single ticker symbol (e.g. `AAPL`). Omit for all symbols
limit	integer	50	Number of top contracts to return (1–500)

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.

GET /v1/reports/hourly Hourly mover analysis reports

Parameters

Parameter	Type	Default	Description
limit	integer	20	Number of reports to return (most recent first)

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"

Response Fields

Field	Type	Description
id	string	Unique report identifier (UUID)
title	string	Report title (e.g. "10:00 AM Hourly Movers")
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 — always `movers`

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/daily Daily market summary reports

Parameters

Parameter	Type	Default	Description
limit	integer	20	Number of reports to return (most recent first)

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 (e.g. "Daily Summary — March 17, 2026")
description	string	Summary of the day's key options activity and sentiment
slug	string	URL-friendly slug for linking to the full report
created	string	Report generation timestamp (ISO 8601)
type	string	Report type — always `daily-summary`

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}/content Full 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

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

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

Setup Instructions

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

Claude Desktop SSE ▶

Open Claude Desktop → Settings → Developer → Edit Config
Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "capitalflow": {
      "url": "https://developer.capitalflow.app/mcp/sse",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop. Look for the 🔧 tools icon in the chat input.

Claude Code (CLI) Streamable HTTP ▶

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"

Verify with claude mcp list — you should see capitalflow.
Use in any conversation: "Use the capitalflow tools to get SPY trades"

Cursor SSE ▶

Open Cursor Settings → Features → MCP Servers → Add New
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"
      }
    }
  }
}

Restart Cursor. The tools will appear in Composer (Agent mode).

VS Code (Copilot) Streamable HTTP ▶

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"
      }
    }
  }
}

Open Copilot Chat (Agent mode) — tools will be listed in the tool picker.

Windsurf SSE ▶

Open Windsurf Settings → Cascade → MCP → Add Server → Custom
Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "capitalflow": {
      "serverUrl": "https://developer.capitalflow.app/mcp/sse",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Restart Windsurf. Tools will appear in Cascade chat.

Antigravity Streamable HTTP ▶

Open Settings → Tools → MCP Servers → Add Server
Configure the server with the following:

Name: capitalflow
Transport: Streamable HTTP
URL: https://developer.capitalflow.app/mcp
Headers:   X-API-Key: YOUR_API_KEY

The CapitalFlow tools will be available in your next conversation.

Perplexity SSE ▶

Open Perplexity → Settings → MCP Servers → Add
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

Enable the server toggle, then try: "What are the top SPY options trades today?"

ChatGPT Streamable HTTP ▶

Open ChatGPT → Settings → Connected Tools → Add MCP Server
Enter the connection details:

Server URL: https://developer.capitalflow.app/mcp
Authentication: API Key
Header Name: X-API-Key
API Key: YOUR_API_KEY

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.