{"openapi":"3.1.0","info":{"title":"Half on a Double public data API","version":"1.1.0","description":"Read-only, end-of-day options-positioning snapshots, screens, rankings and historical CSV. Null means unavailable, never zero. Outputs are descriptive and are not investment advice.","license":{"name":"Personal, non-commercial research terms","url":"https://halfonadouble.com/terms"}},"externalDocs":{"description":"Agent directory and interpretation guidance","url":"https://halfonadouble.com/llms.txt"},"servers":[{"url":"https://halfonadouble.com"}],"paths":{"/api/v1/series.json":{"get":{"operationId":"getPublicationMetadata","summary":"Get the active publication and endpoint templates","responses":{"200":{"description":"Publication metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicationMetadata"}}}}}}},"/api/v1/tickers.json":{"get":{"operationId":"listTickers","summary":"List symbols with built canonical pages","responses":{"200":{"description":"Compact ticker inventory; each ticker row is symbol, page tier and Markdown availability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TickerInventory"}}}}}}},"/api/v1/tickers/{symbol}.json":{"get":{"operationId":"getTickerSnapshot","summary":"Get the current published snapshot and displayed historical summaries for one symbol","parameters":[{"$ref":"#/components/parameters/Symbol"}],"responses":{"200":{"description":"Ticker snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TickerSnapshot"}}}},"404":{"description":"The symbol does not have a built site page; consult the ticker inventory."}}}},"/api/v1/history/{symbol}.csv":{"get":{"operationId":"getTickerHistory","summary":"Download the active public historical series for one symbol","description":"The same-origin edge route follows the active generation atomically. Empty CSV fields mean unavailable. Range and conditional requests are supported.","parameters":[{"$ref":"#/components/parameters/Symbol"}],"responses":{"200":{"description":"Ticker history from 2020-12-01 when available","headers":{"ETag":{"schema":{"type":"string"}},"Last-Modified":{"schema":{"type":"string"}}},"content":{"text/csv":{"schema":{"type":"string"},"example":"date,close,delta_neutral,gamma_neutral,gamma_max,gamma_max_value,n_contracts,total_calls,total_puts,total_open_interest,oi_calls,oi_puts,max_pain_near,max_pain_near_expiry,max_pain_all,gex_total,gex_flip,call_wall,put_wall"}}},"404":{"description":"No published historical file exists for the symbol."},"502":{"description":"The active publication or upstream data object could not be resolved."}}},"head":{"operationId":"headTickerHistory","summary":"Inspect historical CSV metadata without downloading the body","parameters":[{"$ref":"#/components/parameters/Symbol"}],"responses":{"200":{"description":"Historical CSV metadata"},"404":{"description":"Not found"}}}},"/api/v1/analysis/{symbol}.json":{"get":{"operationId":"getAdvancedOptionsAnalysis","summary":"Get the complete derived advanced-options analysis for one symbol","description":"Same-date analysis supplied by the options analytics pipeline. The response contains rankable scalar features plus all derived curve, surface, strike and expiration analyses. The licensed contract-level option chain is intentionally excluded.","parameters":[{"$ref":"#/components/parameters/Symbol"},{"$ref":"#/components/parameters/AnalysisDate"}],"responses":{"200":{"description":"Versioned advanced-options analysis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvancedOptionsAnalysis"}}}},"404":{"description":"No advanced analysis is published for the symbol."},"502":{"description":"The advanced-options feed is temporarily unavailable."}}},"head":{"operationId":"headAdvancedOptionsAnalysis","summary":"Inspect advanced-analysis metadata without downloading the body","parameters":[{"$ref":"#/components/parameters/Symbol"},{"$ref":"#/components/parameters/AnalysisDate"}],"responses":{"200":{"description":"Advanced-analysis metadata"},"404":{"description":"Not found"}}}},"/api/v1/screens/{screen}.json":{"get":{"operationId":"getDailyScreen","summary":"Get one dated daily screen","parameters":[{"name":"screen","in":"path","required":true,"schema":{"type":"string","enum":["gamma-max-crosses","delta-neutral-crosses","nearest-gamma-max","nearest-max-pain","gex-extremes","most-open-interest","call-put-contract-extremes","put-call-open-interest-extremes","open-interest-surge","unusual-open-interest-accumulation","call-oi-growth-1d","call-oi-growth-5d","put-oi-growth-1d","put-oi-growth-5d","unusual-call-oi-accumulation","unusual-put-oi-accumulation","unusual-call-oi-growth-shift","unusual-put-oi-growth-shift","options-catalyst-watch","iv-rank-extremes","iv-term-structure-extremes","expected-move-extremes","straddle-implied-move","risk-reversal-extremes","option-volume-activity","net-delta-positioning","dealer-delta-positioning","vanna-exposure-extremes","charm-exposure-extremes","volatility-smile-convexity","iv-surface-dispersion","volatility-forecast-discount","historical-payoff-value","breakout-with-inexpensive-options","historically-cheap-calls-puts","iv-expansion-low-base","unusual-activity-without-repricing","inexpensive-forward-volatility","long-option-scenario-value"]}}],"responses":{"200":{"description":"Screen definition and ordered matches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Screen"}}}},"404":{"description":"Unknown screen."}}}},"/api/v1/rankings/level-distance.json":{"get":{"operationId":"getLevelDistanceRankings","summary":"Get gamma-max and delta-neutral distance ranking tails","responses":{"200":{"description":"The same top-100 ranking sections shown on the canonical page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rankings"}}}}}}}},"components":{"parameters":{"Symbol":{"name":"symbol","in":"path","required":true,"description":"Uppercase ticker symbol from the ticker inventory; dots and hyphens are supported.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._^-]{0,14}$","example":"SPY"}},"AnalysisDate":{"name":"date","in":"query","required":false,"description":"Trading date to pin. A stale static page receives 409 rather than silently loading a newer analysis publication.","schema":{"type":"string","format":"date"}}},"schemas":{"PublicationMetadata":{"type":"object","required":["schema_version","data_through","methodology","url_templates"],"properties":{"schema_version":{"type":"integer","const":1},"publisher":{"type":"string","const":"Half on a Double"},"data_through":{"type":"string","format":"date","description":"Trading session represented by the values."},"frequency":{"type":"string","const":"end-of-day"},"methodology":{"type":"string"},"generation":{"type":["string","null"]},"advanced_options_feed":{"type":["object","null"],"description":"Coverage and analysis inventory for the exact-date advanced-options feed, when loaded."},"url_templates":{"type":"object"}}},"TickerInventory":{"type":"object","required":["schema_version","data_through","fields","tickers"],"properties":{"schema_version":{"type":"integer","const":1},"publisher":{"type":"string","const":"Half on a Double"},"data_through":{"type":"string","format":"date","description":"Trading session represented by the values."},"frequency":{"type":"string","const":"end-of-day"},"methodology":{"type":"string"},"fields":{"type":"array","items":{"type":"string"}},"tickers":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string","description":"symbol"},{"type":"string","enum":["A","B"],"description":"page tier"},{"type":"boolean","description":"Markdown snapshot available"}],"minItems":3,"maxItems":3}}}},"TickerSnapshot":{"type":"object","required":["schema_version","data_through","methodology","generation","symbol","page_tier","snapshot","history_summary","history_url"],"properties":{"schema_version":{"type":"integer","const":1},"publisher":{"type":"string","const":"Half on a Double"},"data_through":{"type":"string","format":"date","description":"Trading session represented by the values."},"frequency":{"type":"string","const":"end-of-day"},"methodology":{"type":"string"},"generation":{"type":["string","null"]},"symbol":{"type":"string"},"page_tier":{"type":"string","enum":["A","B"]},"canonical_url":{"type":"string","format":"uri"},"markdown_url":{"type":["string","null"],"format":"uri"},"history_url":{"type":"string","format":"uri"},"advanced_analysis_url":{"type":["string","null"],"format":"uri"},"units":{"type":"object"},"snapshot":{"$ref":"#/components/schemas/TickerCurrentSnapshot"},"history_summary":{"oneOf":[{"$ref":"#/components/schemas/TickerHistorySummary"},{"type":"null"}],"description":"Full-history statistics for Tier A pages; null for snapshot-only Tier B pages."},"gamma_max_cross_outcomes":{"type":"array","items":{"type":"object"}},"advanced_options":{"oneOf":[{"$ref":"#/components/schemas/AdvancedOptionsSummary"},{"type":"null"}]}}},"AdvancedOptionsSummary":{"type":"object","description":"Rankable scalar projection joined only when the advanced feed and core publication have the same trading date.","required":["data_through","analysis_coverage","catalyst_score","directional_score","catalyst_reasons","features","complete_analysis_url"],"properties":{"data_through":{"type":["string","null"],"format":"date"},"analysis_coverage":{"type":["number","null"]},"catalyst_score":{"type":["number","null"]},"directional_score":{"type":["number","null"]},"catalyst_reasons":{"type":"array","items":{"type":"string"}},"features":{"type":"object","additionalProperties":true},"complete_analysis_url":{"type":"string","format":"uri"},"interpretation":{"type":"string"}}},"AdvancedOptionsAnalysis":{"type":"object","description":"Producer-owned schema. Every named analysis is derived from the end-of-day chain; raw contract rows are not redistributed.","required":["feed","schema_version","data_date","symbol","summary","features","analyses"],"properties":{"feed":{"type":"string","const":"hoad_options_analytics"},"schema_version":{"type":"integer","const":1},"data_date":{"type":"string","format":"date"},"generated_at":{"type":"string","format":"date-time"},"source_file":{"type":"string"},"symbol":{"type":"string"},"summary":{"type":"object","additionalProperties":true},"features":{"type":"object","additionalProperties":true},"analyses":{"type":"object","description":"Gamma walls, pain by strike, volatility surface and smile, term structure, expected move, put/call skew, dealer positioning, Greeks heatmap, risk reversal, vanna, charm, net delta, straddle pricing, volume profile, IV contours, butterfly spread and IV history.","additionalProperties":true}}},"TickerCurrentSnapshot":{"type":"object","description":"Current end-of-day values. Nullable values are unavailable, never zero. Prices are USD per share, open interest is contracts and gamma exposure uses the units map on the parent response.","required":["close","previous_close","delta_neutral","gamma_neutral","gamma_max","total_open_interest","previous_open_interest","listed_contracts","listed_calls","listed_puts","gamma_max_distance_pct","delta_neutral_distance_pct","gamma_neutral_distance_pct","open_interest_change_1d_pct","call_open_interest","put_open_interest","put_call_open_interest_ratio","nearest_expiration_max_pain","nearest_expiration_max_pain_expiry","nearest_expiration_max_pain_distance_pct","all_expiration_max_pain","net_gamma_exposure","net_gamma_exposure_per_100k_open_interest","gamma_exposure_flip","gamma_exposure_flip_distance_pct","call_wall","call_wall_distance_pct","put_wall","put_wall_distance_pct","gamma_max_cross_direction","delta_neutral_cross_direction","open_interest_rank"],"properties":{"close":{"type":"number"},"previous_close":{"type":["number","null"]},"delta_neutral":{"type":["number","null"]},"gamma_neutral":{"type":["number","null"]},"gamma_max":{"type":["number","null"]},"total_open_interest":{"type":"integer","minimum":0},"previous_open_interest":{"type":["integer","null"]},"listed_contracts":{"type":["integer","null"]},"listed_calls":{"type":["integer","null"]},"listed_puts":{"type":["integer","null"]},"gamma_max_distance_pct":{"type":["number","null"]},"delta_neutral_distance_pct":{"type":["number","null"]},"gamma_neutral_distance_pct":{"type":["number","null"]},"open_interest_change_1d_pct":{"type":["number","null"]},"call_open_interest":{"type":["integer","null"],"description":"Open interest summed across listed call contracts."},"put_open_interest":{"type":["integer","null"],"description":"Open interest summed across listed put contracts."},"put_call_open_interest_ratio":{"type":["number","null"]},"nearest_expiration_max_pain":{"type":["number","null"]},"nearest_expiration_max_pain_expiry":{"type":["string","null"],"format":"date"},"nearest_expiration_max_pain_distance_pct":{"type":["number","null"]},"all_expiration_max_pain":{"type":["number","null"]},"net_gamma_exposure":{"type":["number","null"],"description":"Signed modeled gamma exposure; call-positive and put-negative by convention."},"net_gamma_exposure_per_100k_open_interest":{"type":["number","null"]},"gamma_exposure_flip":{"type":["number","null"]},"gamma_exposure_flip_distance_pct":{"type":["number","null"]},"call_wall":{"type":["number","null"]},"call_wall_distance_pct":{"type":["number","null"]},"put_wall":{"type":["number","null"]},"put_wall_distance_pct":{"type":["number","null"]},"gamma_max_cross_direction":{"type":["string","null"],"enum":["above","below",null]},"delta_neutral_cross_direction":{"type":["string","null"],"enum":["above","below",null]},"open_interest_rank":{"type":"integer","minimum":1}}},"CallPutOiWindow":{"type":"object","properties":{"call_change_contracts":{"type":["number","null"]},"put_change_contracts":{"type":["number","null"]},"call_growth_pct":{"type":["number","null"]},"put_growth_pct":{"type":["number","null"]},"call_minus_put_growth_pp":{"type":["number","null"]}}},"OiChangeSurprise":{"type":"object","properties":{"z_score":{"type":["number","null"]},"comparison_sessions":{"type":"integer"}}},"CallPutOiChanges":{"type":"object","description":"Displayed call/put OI changes and separately standardized daily surprises. Positive growth gaps favor calls. Does not identify buying direction or IV skew.","properties":{"one_session":{"$ref":"#/components/schemas/CallPutOiWindow"},"five_sessions":{"$ref":"#/components/schemas/CallPutOiWindow"},"call_change_surprise":{"$ref":"#/components/schemas/OiChangeSurprise"},"put_change_surprise":{"$ref":"#/components/schemas/OiChangeSurprise"},"call_minus_put_growth_surprise":{"$ref":"#/components/schemas/OiChangeSurprise"}}},"TickerHistorySummary":{"type":"object","required":["first_date","last_date","session_count","trailing_window_sessions","open_interest_change_1d_contracts","open_interest_change_z_252","open_interest_change_z_comparison_sessions"],"properties":{"first_date":{"type":"string","format":"date"},"last_date":{"type":"string","format":"date"},"session_count":{"type":"integer","minimum":1},"trailing_window_sessions":{"type":"integer","minimum":1},"sessions_above_gamma_max_pct":{"type":["number","null"]},"gamma_max_cross_count":{"type":"integer","minimum":0},"delta_neutral_cross_count":{"type":"integer","minimum":0},"gamma_max_prior_sessions_closer_pct":{"type":["number","null"]},"gamma_max_prior_comparison_sessions":{"type":"integer","minimum":0},"delta_neutral_prior_sessions_closer_pct":{"type":["number","null"]},"delta_neutral_prior_comparison_sessions":{"type":"integer","minimum":0},"open_interest_percentile_1y":{"type":["number","null"]},"open_interest_change_1d_contracts":{"type":["integer","null"],"description":"Latest session-to-session change in total option open interest, in contracts."},"open_interest_change_z_252":{"type":["number","null"],"description":"Latest daily open-interest change expressed as standard deviations from up to 252 preceding daily changes; the current change is excluded from the baseline."},"open_interest_change_z_comparison_sessions":{"type":"integer","minimum":0,"maximum":252},"open_interest_change_5_sessions_pct":{"type":["number","null"]},"open_interest_change_21_sessions_pct":{"type":["number","null"]},"call_put_open_interest_changes":{"$ref":"#/components/schemas/CallPutOiChanges"}}},"ScreenRow":{"type":"object","required":["symbol","canonical_url","close_usd_per_share","level_usd_per_share","distance_pct","total_open_interest_contracts","detail"],"properties":{"symbol":{"type":"string"},"canonical_url":{"type":"string","format":"uri"},"close_usd_per_share":{"type":"number"},"level_usd_per_share":{"type":["number","null"]},"distance_pct":{"type":["number","null"]},"total_open_interest_contracts":{"type":"integer","minimum":0},"detail":{"type":["string","null"]}}},"Screen":{"type":"object","required":["schema_version","data_through","slug","definition","rows"],"properties":{"schema_version":{"type":"integer","const":1},"publisher":{"type":"string","const":"Half on a Double"},"data_through":{"type":"string","format":"date","description":"Trading session represented by the values."},"frequency":{"type":"string","const":"end-of-day"},"methodology":{"type":"string"},"slug":{"type":"string"},"availability":{"type":"string","enum":["ready","unavailable"]},"unavailable_reason":{"type":["string","null"]},"evaluated_ticker_count":{"type":["integer","null"],"minimum":1,"description":"Tickers with usable research inputs, whether or not they qualified; null when unreported or unavailable."},"match_count":{"type":["integer","null"],"minimum":0,"description":"Published row count; null when unavailable, not zero matches."},"definition":{"type":"string"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/ScreenRow"}}}},"Rankings":{"type":"object","required":["schema_version","data_through","distance_formula","rankings"],"properties":{"schema_version":{"type":"integer","const":1},"publisher":{"type":"string","const":"Half on a Double"},"data_through":{"type":"string","format":"date","description":"Trading session represented by the values."},"frequency":{"type":"string","const":"end-of-day"},"methodology":{"type":"string"},"distance_formula":{"type":"string"},"historical_comparison":{"type":"string"},"rankings":{"type":"array"}}}}}}