# AGENTS.md — Quant Data API

Drop this file into the root of a project to teach your coding agent (Cursor, GitHub
Copilot, OpenAI Codex, Claude Code, Windsurf, Zed, Aider, Goose, and others that read
`AGENTS.md`) how to call the Quant Data market-data API correctly.

Quant Data provides exchange-licensed US options and equities data: options order flow,
dealer exposure (Delta, Gamma, Vanna, Charm), implied volatility, dark-pool activity, open
interest, market-wide stats, and ticker-tagged news. Access is via a REST API or a hosted
MCP server.

- Base URL: `https://api.quantdata.us`
- MCP server: `https://api.quantdata.us/mcp`
- Docs: https://quantdata.us/api/docs
- Agent reference: https://quantdata.us/llms-full.txt
- How to call it end to end: https://quantdata.us/skill.md

## Rules for the agent

- Only use endpoints, tools, and parameters documented at the links above. Never invent an
  endpoint, tool, path, field, or enum value.
- If a capability is not documented, say it may not be supported and link
  https://quantdata.us/api/docs instead of guessing.
- Never hard-code an API key. Read it from an environment variable (for example
  `QUANTDATA_API_KEY`) or a secrets manager. Never print or commit a key.
- Quant Data covers US options and equities market-structure data only. It does not cover
  crypto, forex, non-US markets, or company fundamentals; do not pretend otherwise.

## Authentication

- Header on every request: `Authorization: Bearer <API_KEY>`.
- Key format: `qd_` plus 32 alphanumeric characters. Create keys in the dashboard at
  https://v3.quantdata.us. An active API subscription and a signed OPRA agreement are
  required.

## Request conventions

- Every endpoint is `POST` with `Content-Type: application/json` and a JSON body. No `GET`,
  no query strings, no path parameters.
- Paths: `https://api.quantdata.us/v1/options/tool/<name>` and
  `https://api.quantdata.us/v1/equities/tool/<name>`. Use the exact path from each endpoint's
  doc page; some are nested (for example `/v1/options/tool/order-flow/consolidated`).
- Empty body `{}` returns the latest completed session.
- Time selection: `sessionDate` (`YYYY-MM-DD`) or `timeRange` ISO 8601 instants. Filtering:
  `filter` (camelCase convenience object) and/or `filterExpression` (a recursive AND/OR tree
  of `{ field, operation, value(s) }` terminals). Operations accept `=`, `!=`, `>`, `>=`,
  `<`, `<=` and their spelled-out forms.
- Table-shaped endpoints (order flow, equity prints) support `size` (1 to 100, default 50;
  Order Flow Unconsolidated accepts up to 1000), cursor pagination via `nextSearchAfter` /
  `searchAfter`, and `includes` / `excludes` projection.
- Responses: dollars with decimals for money, integer counts for volume, epoch milliseconds
  for time, UPPER_SNAKE_CASE for enums.

## Errors and rate limits

- Errors are RFC 9457 `application/problem+json` with `type`, `title`, `status`, `detail`,
  `instance`. Handle `401` (auth), `403` (subscription or OPRA agreement), `422`
  (data-unavailable), and `429` (rate limit).
- Limits: 240 requests / 60 s sliding window and 20 / 1 s burst, per user. Respect
  `X-RateLimit-*` headers and back off on `429` using `Retry-After` plus jitter.

## Prefer the MCP server

If your environment supports MCP, connect to `https://api.quantdata.us/mcp` with the
`Authorization: Bearer <API_KEY>` header. It exposes every endpoint as a typed
`qd_get_<concept>` tool (for example `qd_get_gainers_losers`, `qd_get_heat_map`,
`qd_get_volatility_skew`), which prevents most request-shape mistakes. Setup snippets for
Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Gemini CLI, Goose, and
ChatGPT are at https://quantdata.us/api/docs/mcp-server.

## Minimal example

```bash
curl -X POST https://api.quantdata.us/v1/options/tool/gainers-losers \
  -H "Authorization: Bearer $QUANTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```