Quickstart

Before you start

You'll go from zero to a usable response in four steps. Every endpoint is built on the same structure, so the pattern you learn here applies across the entire API.

Generate an API key

Your key is the only credential the API needs. Treat it like a password.

Send your first request

The simplest possible request hits an endpoint with an empty JSON body. Most parameters have defaults, so {} is enough to return data for the latest session on tools like Gainers / Losers.

Replace <YOUR_API_KEY> with your real key and run this in your terminal. It calls Gainers / Losers, which ranks tickers by their bullish and bearish option premium for the most recent completed trading session.

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

Every endpoint follows the same shape: POST, JSON body, Bearer auth. There are no query strings and no path parameters. The request body is the entire input surface.

Read the response

The response is a JSON object. For Gainers / Losers, the top-level datafield is a map keyed by ticker, sorted alphabetically. Each entry summarizes that ticker's option-trade premium and volume for the requested window.

{
  "data": {
    "AAPL": {
      "bearishPremium": 4821330.50,
      "bullishPremium": 6128974.25,
      "premium": 11402108.75,
      "premiumRatio": 0.787,
      "tradeCount": 18472,
      "volume": 41208
    },
    "NVDA": {
      "bearishPremium": 9120448.10,
      "bullishPremium": 12880102.80,
      "premium": 23104550.90,
      "premiumRatio": 0.708,
      "tradeCount": 25319,
      "volume": 58844
    }
  }
}

Premium values are in dollars, not cents. tradeCount is the number of trades that contributed; volume is the total contract count across those trades. premiumRatio is bearishPremium / bullishPremium, with 0 reserved for the case where the denominator is zero.

Narrow the query

Two ways to scope a request: the convenience filter for common queries, and the filter expression DSL for boolean composition. The two approaches can be combined. When both are present, they are evaluated as AND.

Convenience filter · single ticker, specific session

curl -X POST https://api.quantdata.us/v1/options/tool/gainers-losers \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionDate": "2026-05-13",
    "filter": {
      "ticker": "AAPL"
    }
  }'

Plural collection fields accept the singular form as an alias, so ticker is interchangeable with tickers. Both a scalar and an array are accepted under either spelling.

Filter expression · AND composition

curl -X POST https://api.quantdata.us/v1/options/tool/gainers-losers \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionDate": "2026-05-13",
    "filterExpression": {
      "conjunction": "AND",
      "filters": [
        { "field": "ticker", "operation": "=", "values": ["AAPL", "NVDA"] },
        { "field": "dte", "operation": "<=", "value": 7 }
      ]
    }
  }'

The filter expression is a recursive boolean tree. The example above uses an AND conjunction: both conditions must be true. To match multiple values for the same field, pass them as an array in values. Operations accept symbolic, abbreviated, and full-name spellings: =, EQ, and EQUALS are equivalent. See Filter Expression for the full grammar.

Where to go next