Slippage Cost

slippage-cost

You hand over a fill log. The skill walks every line against the NBBO at the fill timestamp, computes slippage in basis points, and emits an exception report listing only the fills that deserve scrutiny.

This is not a true best-execution audit and not true Implementation Shortfall. IS compares each fill against the decision-time (arrival) benchmark price; this skill compares against the NBBO at fill time. The input CSV doesn't carry an arrival timestamp, so arrival-price IS isn't computable here. See tier_caveats for the bias direction introduced by the Tier B aggregate proxy.

The output answers two questions the regulator asks (off-NBBO prints, wide-spread fills) and two questions the PM asks (VWAP slippage, adverse selection). Same data, different audiences.

When to invoke

• Execution desk says "run slippage on yesterday's fills" or "check this CSV for fill quality"
• A PM asks "did we get good fills" or "how much did we leak versus the inside"
• Compliance review of a month's executions for Reg NMS off-NBBO prints
• A broker performance review where you're comparing fill-vs-NBBO slippage across venues. (Note: this is not arrival-price IS; if you need that, the input CSV needs to carry a decision/arrival timestamp and the methodology changes.)

What you need

• A fill CSV with columns: ticker, side (BUY/SELL), qty, price, timestamp (ISO-8601 with timezone, Eastern recommended)
• MASSIVE_API_KEY exported. Stocks Developer or higher unlocks Tier A (full historical NBBO). Stocks Starter falls back to Tier B (1-second aggregate band as NBBO proxy).

Tiers

Tier A: full NBBO tick history

GET /v3/quotes/{ticker} returns every NBBO update at microsecond precision. The skill pulls the inside quote at the fill timestamp, flags crossed-spread fills against the exact inside, and detects off-NBBO prints precisely. This is the default path on Developer+ tier keys.

Verified 2026-06-25 on a Stocks Business + Options Business + Benzinga key: the endpoint returns full NBBO ticks. This contrasts with the WebSocket Q channel, which returns not_authorized on the same key (see portfolio-mark's references/live-vs-delayed.md). REST quote history and live quote streaming are entitled separately.

Tier B: 1-second aggregate band as NBBO proxy

When /v3/quotes returns 403, the skill walks GET /v2/aggs/ticker/{ticker}/range/1/second/{from}/{to} for a ±2-second window around each fill. The "reference NBBO" at time T becomes low of the [T, T+1s] bar as the proxy bid, high of the same bar as the proxy ask. Defensible but lossy: a quote that updated mid-second is invisible; a violent intra-second move is squashed into the bar high/low.

See references/nbbo-proxy-via-aggregates.md for the precision tradeoffs and what gets lost.

What you get back

Two output layers.

Layer 1: canonical JSON matching output-schema.json. Per flagged fill: ticker, side, qty, price, timestamp, slippage_bps, spread_bps_at_fill, vwap_slippage_bps, reasons[], adverse_selection_bps, suggested_next_action. Per run: scan_params, fills_checked, tier, quote_source, summary (counts by reason, total implementation shortfall in dollars). UI dashboards and downstream agents consume this.

Layer 2: rendered exception report. Header with the run metadata. One BREAK block per flagged fill. Summary block at the bottom. See references/rendering.md for the full format. Claude Code users read this.

A short example:

TCA: 18 fills checked · 6 BREAKS flagged · run 2026-06-25 15:32 UTC

BREAK 1: AAPL BUY 1,000 @ $300.85 · 2026-06-23 10:14:18 ET
  Slippage:    +18.0 bps vs reference ask $300.31 at 10:14:18
  Spread:      $300.25 × $300.31 (2 bps inside, normal)
  VWAP slip:   +18.4 bps vs session VWAP $296.88
  Reasons:     crossed_spread, high_vwap_slippage
  Adverse:     +4.2 bps within 30s of fill (mild adverse)
  Suggest:     Investigate venue routing; price improvement opportunity missed

How it works

1. Probe quote-data availability. Call /v3/quotes/{ticker}?limit=1 on the first ticker in the CSV. 200 means Tier A; 403 means Tier B. Print the tier in the report header so the operator sees the confidence level.
2. For each fill, pull the reference NBBO at the fill timestamp:
   • Tier A: /v3/quotes/{ticker} with timestamp.gte/timestamp.lte wrapping the fill time. Take the most recent quote before the fill timestamp.
   • Tier B: /v2/aggs/ticker/{ticker}/range/1/second/{from}/{to} for the second-bar straddling the fill. Reference bid = bar low, reference ask = bar high.
3. Compute slippage per references/slippage-methodology.md: bps = (fill_price - reference_price) / reference_price × 10000. Signed by side: positive on a BUY means paid more than reference (bad); negative on a SELL means sold below reference (bad).
4. Pull session VWAP from /v2/aggs/ticker/{ticker}/range/1/minute/{date}/{date}, compute weighted average across all minutes up to the fill timestamp. The fill's VWAP slippage is the same bp formula, sign-adjusted.
5. Check adverse selection by pulling 30 seconds of post-fill second-aggregates and measuring price drift. A BUY followed by price decline is adverse; a SELL followed by price rise is adverse. See references/adverse-selection.md.
6. Apply flag categories per references/flag-categories.md. A fill that hits zero categories is dropped. A fill that hits one or more becomes a BREAK in the exception report.
7. Emit JSON and rendered output. Only flagged fills appear. Summary block shows counts by category and total estimated implementation shortfall in dollars.

Foundations used

• massive-api-patterns for REST auth, rate limiting, and timestamp handling

Endpoints used

• GET /v3/quotes/{ticker} (Tier A; primary)
• GET /v2/aggs/ticker/{ticker}/range/1/second/{from}/{to} (Tier B primary; also used for adverse-selection check on both tiers)
• GET /v2/aggs/ticker/{ticker}/range/1/minute/{date}/{date} (session VWAP)

Example

# Fill log with 18 trades from a session
cat examples/sample-fills.csv

# Invoke from Claude Code
# > /slippage-cost examples/sample-fills.csv

The skill processes fills in order and emits flagged ones immediately, so a long fill log streams findings instead of waiting for completion.

Doesn't handle (yet)

• Options fills. OCC contract NBBO lives at /v3/quotes/O:{occ_ticker}; the endpoint shape is the same but the contract-specific liquidity model and 1-second-aggs-for-options fallback are different. A v2 of this skill will add an options-aware path.
• Block-trade carveouts. A 100,000-share block fill on a $50 stock is expected to print outside the NBBO and shouldn't be flagged as off_nbbo without context. v1 flags it as a BREAK with reason off_nbbo; the operator overrides on review.
• Average-price fills (VWAP execution, TWAP execution, ISO orders). These are best evaluated against the parent order's benchmark, not the inside quote at the child-fill print. v1 evaluates every fill as an arrival-price comparison; an extended schema can add parent_strategy to the input CSV and switch the benchmark.
• Cross-venue dark-pool prints. Flagged as off_nbbo in v1 (which is correct from a Reg NMS view), but the operator may want a separate dark_print reason. Add to the flag categories file if needed.

Add these in a PR if you need them. The slippage and adverse-selection math carry over.