CuteMarkets Docs

API Reference

Everything you need to integrate market data, build faster, and scale.

Docs

Tip: open /docs/options-flow-false-positives.md directly for raw markdown (easy copy/paste into an LLM).

Options flow is easy to overread. A contract can show high volume, large premium, volume above open interest, and a dramatic price move without proving informed directional demand. The job of an options-flow workflow is to surface contracts for review, then reject weak rows with clear evidence.

Use this page with Unusual Options Activity, Unusual Options Activity Scanner Model, Options Volume and Open Interest, Options Chain API, Historical Options Quotes API, and Options Trades API.

The main false positives

False positiveWhy it looks interestingWhy it may be weak
Cheap far-OTM weeklyLarge volume and high ticket countSmall premium and poor probability
Wide-spread contractLarge last price or dramatic moveBid/ask market is expensive or stale
Routine ETF activityHigh volume in SPY, QQQ, IWM, or TLTBaseline liquidity is already high
Earnings-week crowdingMany contracts light up near the eventActivity can be routine event hedging
Roll or spread legLarge prints in one contractSingle-leg view misses the structure
Closing activityVolume above OI appears meaningfulFlow may reduce exposure, not create it
Stale last tradeLast price implies activityNo fresh quote supports the row

The Options Chain Scanner Architecture and Options Data Provider Evaluation docs explain how to keep scanner outputs tied to endpoint evidence.

Direction is hard

A chain snapshot can show calls versus puts. It can show last trade, latest quote, volume, OI, IV, Greeks, and underlying price. It cannot reliably tell whether a trade was buyer-initiated or seller-initiated without deeper trade classification, quote timing, and sometimes multi-leg reconstruction.

Avoid claims such as:

  • "big call buying" when the scanner only sees call volume
  • "bearish put sweep" when the scanner has no order-routing or aggressor-side evidence
  • "new position" when volume is above OI but OI has not updated
  • "smart money" when the flow may be hedge, roll, or close

Safer labels are:

  • high call volume
  • high put volume
  • large estimated premium
  • volume above prior open interest
  • tight quote context
  • short-dated activity
  • requires trade/quote review

These labels keep the workflow honest and easier to support.

Quote filters

Quote quality is the first rejection gate. A high-volume contract with a wide or stale quote may be interesting for observation, but it is weak as a trade candidate or backtest candidate.

Use these filters:

FilterPurpose
Minimum bidAvoids zero-bid exits and weak fill assumptions
Maximum spread percentRejects expensive-to-cross contracts
Quote age limitAvoids stale bid/ask context
Midpoint availabilitySupports premium and slippage estimates
Bid/ask consistencyPrevents invalid or crossed quote rows

The Quotes docs, Why Option Quotes Matter More Than Last Price, Options Slippage Modeling, and Bid/Ask Spread Backtesting pages cover this layer in more depth.

Trade filters

Trades are useful for validating activity, but prints still need context. A print can be part of a spread, a roll, a hedge, a close, or routine market-making activity.

When a scanner row is important, inspect:

  • trade timestamps
  • print prices
  • print size concentration
  • prints versus nearby bid/ask
  • activity before and after the alert
  • whether the contract had fresh quotes
  • whether related strikes and expirations also printed

Use Trades, Quote vs Trade Timeline, and Historical Options Replay Runbook for this follow-up.

Event context

Unusual activity often clusters around events:

  • earnings
  • FDA decisions
  • index rebalance
  • macro releases
  • merger headlines
  • product launches
  • volatility shocks
  • monthly or weekly OpEx

Event context does not make a row invalid. It changes the interpretation. A high-volume line during earnings week may be normal relative to the event. A quieter line outside an obvious event window may deserve more attention. Store the event label beside the scanner artifact.

For event-driven review, continue with:

Reject reasons

False positives become manageable when they are logged as rejects instead of hidden.

Common reject reasons:

  • wide_spread
  • stale_quote
  • zero_bid
  • tiny_premium
  • routine_liquid_contract
  • event_crowding
  • far_otm_lottery_ticket
  • missing_quote
  • missing_trade_context
  • ambiguous_roll_or_spread
  • plan_quote_unavailable

Rejects belong in scanner exports, backtest artifacts, paper-trading logs, and customer-facing support notes. The Backtesting Data Quality Checklist, Backtesting Execution Realism, and Paper Trading Bot Data Stack explain the same discipline for research systems.

Review workflow

Use this sequence before escalating a scanner row:

  1. Check DTE, moneyness, IV, and delta.
  2. Check volume, open interest, volume/OI ratio, and premium.
  3. Check bid, ask, midpoint, spread percent, and quote age.
  4. Pull trades around the alert timestamp.
  5. Compare prints with nearby quotes.
  6. Look for related activity across nearby strikes and expirations.
  7. Add event context.
  8. Assign a label: monitor, reject, research, alert, or paper-candidate.

That is the difference between a scanner and a headline generator.

Related pages

False-positive review notes

Unusual options activity is noisy. Cheap far-OTM contracts, rolls, spreads, closing trades, stale prints, earnings hedges, and wide quotes can all create impressive volume without a clean directional signal. A scanner needs to preserve the contract, score inputs, quote state, trade conditions, volume/OI pressure, premium estimate, DTE bucket, moneyness, and reject reason.

Pair this page with Options Volume and Open Interest, Option Quote and Trade Conditions, Quotes, and Unusual Options Activity Scanner Model. The best scanner is often the one that says no clearly before it says yes loudly.

Terminology

Terms to keep straight on this page

Market-data APIs use similar words for different objects. These links keep the docs page connected to the precise CuteMarkets workflow and related reference material.

OPRA-originating data

The listed-options source context behind quotes, trades, participant records, exchange context, and consolidated option-market data.

SIP and direct feed

Market-data delivery paths that explain where consolidated equities and options records originate before a normalized API returns them.

Quote, trade, aggregate

Three different price semantics: executable bid/ask market, printed transaction, and bar-level summary.

Quote/trade condition

The sale condition, quote condition, exchange id, correction, sequence, and timestamp context attached to market-data rows.

Contract identity

The OCC symbol, expiration, strike, side, root, and reference data needed to preserve the exact option being studied.

Entitlement gate

A plan-aware check that prevents live, quote, WebSocket, or historical behavior from being implied when the product does not include it.

Access method

The delivery mode for data, such as REST request, WebSocket stream, historical window, flat file, or local cache.

Backfill window

A timestamp-bounded REST request used to repair or complete data after a stream gap, retry, deploy, or cache miss.

Session label

A premarket, regular, after-hours, closed, half-day, holiday, or unknown tag attached to a market-data timestamp.

Data-quality reject

A logged reason for skipping a candidate because required contracts, quotes, timestamps, pagination, or entitlements failed policy.

Commercial-use boundary

The product, plan, display, redistribution, and customer-facing use context that must be reviewed before shipping market data.

Adjusted option deliverable

The changed deliverable or contract terms that can appear after splits, mergers, special dividends, or other corporate actions.

Next steps

Move from the docs into the product workflow

If you are evaluating the API rather than implementing a specific endpoint right now, the product pages map live and historical workflows for stocks, options, and WebSockets.