# Quant Data API — Cursor rules
#
# Drop this file in your project root to teach Cursor how to call the Quant Data
# market-data API. Newer Cursor versions prefer per-rule files under
# .cursor/rules/*.mdc; this single-file .cursorrules still works and is the
# easiest drop-in. To use the modern format, copy these rules into
# .cursor/rules/quantdata-api.mdc with frontmatter `alwaysApply: true`.
#
# Canonical, always-current sources (read these, do not rely on memory):
#   https://quantdata.us/llms-full.txt   full API reference for agents
#   https://quantdata.us/skill.md        how to call the API end to end
#   https://quantdata.us/api/docs         human documentation

You are integrating the Quant Data API: exchange-licensed US options and equities
data (options order flow, dealer exposure, implied volatility, dark pool, open
interest, market-wide stats, news).

Hard rules:
- Only use endpoints, MCP tools, parameters, and enum values documented at the
  links above. Never invent an endpoint name, path, field, or parameter.
- If a capability is not documented, tell the user it may not be supported and link
  https://quantdata.us/api/docs. Do not guess.
- Never hard-code an API key. Read it from an environment variable such as
  QUANTDATA_API_KEY. Never print or commit a key.
- Quant Data is US options and equities market-structure data only: no crypto,
  forex, non-US markets, or company fundamentals.

API shape:
- Base URL https://api.quantdata.us. Every endpoint is POST with
  Content-Type: application/json and a JSON body. No GET, query strings, or path params.
- Paths: /v1/options/tool/<name> and /v1/equities/tool/<name>. Use the exact path from
  the docs; some are nested (e.g. /v1/options/tool/order-flow/consolidated).
- Auth header on every request: Authorization: Bearer <API_KEY>, where the key is
  qd_ followed by 32 alphanumeric characters.
- Empty body {} returns the latest completed session. Select time with sessionDate
  (YYYY-MM-DD) or timeRange (ISO 8601). Filter with `filter` or `filterExpression`
  (recursive AND/OR tree of { field, operation, value(s) }).
- Order-flow and equity-prints endpoints are table-shaped: size (1-100, default 50;
  Order Flow Unconsolidated accepts up to 1000), cursor pagination via
  nextSearchAfter/searchAfter, and includes/excludes projection.
- Errors are RFC 9457 problem+json. Rate limit is 240 req / 60 s plus 20 / 1 s burst
  per user; respect X-RateLimit-* headers and back off on 429.

Prefer the MCP server when available: https://api.quantdata.us/mcp with the same
Bearer header. It exposes every endpoint as a typed qd_get_<concept> tool, which avoids
most request-shape mistakes. Setup: https://quantdata.us/api/docs/mcp-server