# AGENTS.md — Trading Volatility

> How AI agents should authenticate and use Trading Volatility
> (stocks.tradingvolatility.net). Trading Volatility turns large option-chain
> datasets into structured, deterministic market-state signals — gamma exposure
> (GEX), gamma flip levels, dealer positioning, volatility skew, max pain, and
> expected-move levels — for individual equities and ETFs.

This file is the contract for agent consumers. For the full machine-readable
spec, fetch the **API LLM Spec** first:
<https://stocks.tradingvolatility.net/api/v2/llm-spec>.

## MCP server

Prefer tools over raw HTTP? Trading Volatility ships a **Model Context Protocol
(MCP) server** exposing 16 verb-first tools (e.g. `get_ticker_state`,
`get_market_structure`, `get_trade_setup`, `rank_top_setups`,
`get_gex_by_strike`) plus the `tv://llm-spec` resource.

- Remote endpoint (streamable HTTP): `https://tv-mcp-avhwfkn5gq-uc.a.run.app/mcp`
- Server card: <https://stocks.tradingvolatility.net/.well-known/mcp-server-card.json>
- Auth: forward your API key as `Authorization: Bearer <key>` (the demo subset
  below works without a key).

Works with Claude, ChatGPT, Cursor, and any MCP-capable client. If you cannot use
MCP, the equivalent REST endpoints are below.

## Base URL

```
https://stocks.tradingvolatility.net/api/v2
```

## Authentication

Send your key as a bearer token on every request:

```
Authorization: Bearer <YOUR_API_KEY>
```

A key is issued on subscription and shown once at
<https://stocks.tradingvolatility.net/api/v2/docs>.

### Demo access (no key)

A small ticker set can be queried without a key by sending the header
`X-TV-Demo: 1`: **AAPL, VIX, KO, META, AMZN, XOM, GM, MCD**. Rate limits apply.
Use this to prototype before subscribing.

## Recommended flow

1. `GET /tickers/{ticker}` — canonical compact state snapshot. Start here.
2. `GET /tickers/{ticker}/market-structure` — assembled interpretation
   (headline, bias, regime, key levels, drivers, expected behavior).
3. `GET /agent/trade-setup/{ticker}` — compact, trader-facing recommendation
   (direction, thesis, risk framing, state labels).
4. `GET /top-setups` — rank the universe first, then drill into a ticker.

## Endpoints (all GET, base `/api/v2`)

| Path | Purpose |
|------|---------|
| `/tickers/{ticker}` | Canonical ticker state snapshot (default starting point). |
| `/tickers/{ticker}/explain` | Deterministic plain-English regime/positioning read. |
| `/tickers/{ticker}/market-structure` | Assembled interpretation layer. |
| `/tickers/{ticker}/signals` | Lightweight labels/scores for filtering + alert logic. |
| `/tickers/{ticker}/series` | Historical metric time series (`metrics`, `window`). |
| `/tickers/{ticker}/levels` | Key price levels for overlays / exported level lists. |
| `/tickers/{ticker}/curves/gamma` | Net gamma per strike (`exp`, optional `realtime`). |
| `/tickers/{ticker}/curves/gamma/expirations` | Gamma decomposition by expiration bucket. |
| `/tickers/{ticker}/curves/gex_by_strike` | Gamma-exposure curve by strike. |
| `/tickers/{ticker}/options/volume` | Expiration-specific strike-by-strike option volume. |
| `/top-setups` | Rank the universe by opportunity score (supports filter params). |
| `/top-setups/screener/{name}` | Run a named screener preset. |
| `/agent/trade-setup/{ticker}` | Compact trade recommendation payload. |

## Conventions

- **Tickers:** uppercase recommended; the server normalizes.
- **Percent fields:** names ending in `_pct` are in percent units (`1.78` = 1.78%).
- **IV fields:** decimals (`atm_iv` `0.28` = 28%).
- **Curve `exp` param:** `combined|nearest|first_weekly|first_monthly|YYYY-MM-DD`.
- Numbers are computed deterministically from option-chain data; the API exposes
  both raw snapshots and pre-assembled interpretation layers so agents do not
  have to derive meaning themselves.

## Related resources

- Machine-readable API spec: `/api/v2/llm-spec`
- OpenAPI document: `/openapi.json`
- Human + LLM site guide: `/llms.txt`
- Human API docs: `/api/v2/docs`
- Reference integration (example agent app): <https://github.com/jwolberg/volscan>

## Not financial advice

Output describes options-market structure and positioning. It is data and
deterministic interpretation, not a recommendation to buy or sell any security.