{"openapi":"3.1.0","info":{"title":"Tail Correlation API","version":"1.0.0","description":"Measures the thing that destroys portfolios: correlations that look comfortably low in calm markets but spike toward 1 exactly when the market crashes, so the diversifiers you were counting on all fall together — computed live from Yahoo Finance daily closes, no key, nothing stored. A normal full-sample correlation hides this by averaging the calm days with the crisis days; this API instead conditions on the benchmark's extremes. For each asset it returns the ordinary correlation to the benchmark, the crash correlation (measured only on the benchmark's worst days — its lower tail), the rally correlation (on its best days), and the breakdown: how much the correlation rises in a crash versus normal. A bond, gold or commodity position with a low normal correlation but a high crash correlation is a false diversifier; one whose correlation stays low or falls in the tail is a genuine hedge. The asset endpoint returns one instrument's full tail-correlation profile; the screener endpoint ranks the cross-asset universe by crash correlation, surfacing which holdings actually fail when you need them. This is the conditional / tail-correlation cut — distinct from the unconditional cross-asset, sector and FX correlation matrices (which average all days together), the up/down capture API (magnitudes, not co-movement) and the price APIs. It is correlation when it matters: in the crash.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/tailcorr-api","description":"oanor gateway"}],"tags":[{"name":"Screener"},{"name":"Asset"},{"name":"Universe"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/screener":{"get":{"operationId":"get_v1_screener","tags":["Screener"],"summary":"Rank the universe by crash correlation + diversification breakdown","description":"","parameters":[{"name":"benchmark","in":"query","required":false,"description":"Universe symbol used as benchmark","schema":{"type":"string"},"example":"SPY"},{"name":"tail","in":"query","required":false,"description":"Extreme-day percentile (5-25)","schema":{"type":"string"},"example":"10"},{"name":"window","in":"query","required":false,"description":"Lookback in trading days (90-756)","schema":{"type":"string"},"example":"252"},{"name":"class","in":"query","required":false,"description":"equity, sector, commodity, bond, fx, crypto or all","schema":{"type":"string"},"example":"all"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Computed vs SPY over window_days. normal_correlation uses all days; crash_correlation only the benchmark's worst 10% of days (its lower tail); rally_correlation only its best 10%. breakdown = crash - normal: positive means the asset correlates MORE in a crash (a false diversifier); a low or negative crash_correlation is a genuine crisis hedge. Read fresh per call, nothing cached.","class":"all","count":20,"source":"Yahoo Finance","results":[{"name":"S&P 500","rank":1,"class":"equity","symbol":"SPY","tail_pct":10,"available":true,"breakdown":0,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":1,"rally_correlation":1,"normal_correlation":1},{"name":"Nasdaq 100","rank":2,"class":"equity","symbol":"QQQ","tail_pct":10,"available":true,"breakdown":-0.077,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.864,"rally_correlation":0.841,"normal_correlation":0.942},{"name":"Technology","rank":3,"class":"sector","symbol":"XLK","tail_pct":10,"available":true,"breakdown":-0.092,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.78,"rally_correlation":0.779,"normal_correlation":0.872},{"name":"US Small Caps","rank":4,"class":"equity","symbol":"IWM","tail_pct":10,"available":true,"breakdown":-0.226,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.607,"rally_correlation":0.557,"normal_correlation":0.833},{"name":"High-Yield Credit","rank":5,"class":"bond","symbol":"HYG","tail_pct":10,"available":true,"breakdown":-0.19,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.518,"rally_correlation":0.632,"normal_correlation":0.708},{"name":"Emerging Markets","rank":6,"class":"equity","symbol":"EEM","tail_pct":10,"available":true,"breakdown":-0.327,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.447,"rally_correlation":0.674,"normal_correlation":0.774},{"name":"Ethereum","rank":7,"class":"crypto","symbol":"ETH-USD","tail_pct":10,"available":true,"breakdown":-0.094,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.432,"rally_correlation":0.064,"normal_correlation":0.526},{"name":"Developed ex-US","rank":8,"class":"equity","symbol":"EFA","tail_pct":10,"available":true,"breakdown":-0.427,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.348,"rally_correlation":0.616,"normal_correlation":0.775},{"name":"Broad Commodities","rank":9,"class":"commodity","symbol":"DBC","tail_pct":10,"available":true,"breakdown":0.522,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.345,"rally_correlation":-0.027,"normal_correlation":-0.176},{"name":"Energy","rank":10,"class":"sector","symbol":"XLE","tail_pct":10,"available":true,"breakdown":0.437,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.338,"rally_correlation":-0.19,"normal_correlation":-0.098},{"name":"Crude Oil","rank":11,"class":"commodity","symbol":"USO","tail_pct":10,"available":true,"breakdown":0.645,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.3,"rally_correlation":-0.086,"normal_correlation":-0.345},{"name":"Bitcoin","rank":12,"class":"crypto","symbol":"BTC-USD","tail_pct":10,"available":true,"breakdown":-0.298,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.211,"rally_correlation":0.1,"normal_correlation":0.508},{"name":"Financials","rank":13,"class":"sector","symbol":"XLF","tail_pct":10,"available":true,"breakdown":-0.463,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.158,"rally_correlation":0.576,"normal_correlation":0.621},{"name":"US Aggregate Bonds","rank":14,"class":"bond","symbol":"AGG","tail_pct":10,"available":true,"breakdown":-0.189,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.136,"rally_correlation":0.043,"normal_correlation":0.325},{"name":"Health Care","rank":15,"class":"sector","symbol":"XLV","tail_pct":10,"available":true,"breakdown":-0.285,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.074,"rally_correlation":0.432,"normal_correlation":0.359},{"name":"Silver","rank":16,"class":"commodity","symbol":"SLV","tail_pct":10,"available":true,"breakdown":-0.284,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.042,"rally_correlation":0.56,"normal_correlation":0.326},{"name":"Gold","rank":17,"class":"commodity","symbol":"GLD","tail_pct":10,"available":true,"breakdown":-0.235,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.029,"rally_correlation":0.466,"normal_correlation":0.264},{"name":"20Y+ Treasuries","rank":18,"class":"bond","symbol":"TLT","tail_pct":10,"available":true,"breakdown":-0.169,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":0.025,"rally_correlation":-0.055,"normal_correlation":0.194},{"name":"Utilities","rank":19,"class":"sector","symbol":"XLU","tail_pct":10,"available":true,"breakdown":-0.233,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":-0.053,"rally_correlation":0.109,"normal_correlation":0.18},{"name":"EUR/USD","rank":20,"class":"fx","symbol":"EURUSD=X","tail_pct":10,"available":true,"breakdown":-0.409,"crash_days":26,"rally_days":26,"observations":252,"crash_correlation":-0.412,"rally_correlation":-0.365,"normal_correlation":-0.003}],"tail_pct":10,"benchmark":"SPY","unavailable":[],"window_days":252,"benchmark_name":"S&P 500","best_crash_hedge":{"symbol":"EURUSD=X","crash_correlation":-0.412},"biggest_breakdown":{"symbol":"USO","breakdown":0.645}},"meta":{"timestamp":"2026-06-12T10:34:44.793Z","request_id":"2734ab3d-389c-4ac4-941b-86ab0ba2dc2e"},"status":"ok","message":"Tail correlation screener retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/asset":{"get":{"operationId":"get_v1_asset","tags":["Asset"],"summary":"Full tail-correlation profile of one instrument","description":"","parameters":[{"name":"symbol","in":"query","required":true,"description":"Universe symbol","schema":{"type":"string"},"example":"HYG"},{"name":"benchmark","in":"query","required":false,"description":"Benchmark symbol","schema":{"type":"string"},"example":"SPY"},{"name":"tail","in":"query","required":false,"description":"Extreme-day percentile (5-25)","schema":{"type":"string"},"example":"10"},{"name":"window","in":"query","required":false,"description":"Lookback in trading days (90-756)","schema":{"type":"string"},"example":"252"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"name":"High-Yield Credit","note":"normal_correlation over all days vs crash_correlation on the benchmark's worst 10% of days and rally_correlation on its best. breakdown = crash - normal. A false diversifier has low normal but high crash correlation. Read fresh per call, nothing cached.","class":"bond","reads":{"crash":"partial diversification in a crash","breakdown":"correlation is stable across regimes"},"source":"Yahoo Finance","symbol":"HYG","tail_pct":10,"benchmark":"SPY","breakdown":-0.19,"crash_days":26,"rally_days":26,"window_days":252,"observations":252,"benchmark_name":"S&P 500","crash_correlation":0.518,"rally_correlation":0.632,"normal_correlation":0.708},"meta":{"timestamp":"2026-06-12T10:34:44.986Z","request_id":"f5bdc3e4-19b7-4110-ba47-bd48be7c19b0"},"status":"ok","message":"Asset tail correlation retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/universe":{"get":{"operationId":"get_v1_universe","tags":["Universe"],"summary":"The cross-asset universe and its classes","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"The cross-asset universe the screener ranks. Pass class= to a screener call to rank within one class.","count":20,"assets":[{"name":"S&P 500","class":"equity","symbol":"SPY"},{"name":"Nasdaq 100","class":"equity","symbol":"QQQ"},{"name":"US Small Caps","class":"equity","symbol":"IWM"},{"name":"Developed ex-US","class":"equity","symbol":"EFA"},{"name":"Emerging Markets","class":"equity","symbol":"EEM"},{"name":"Technology","class":"sector","symbol":"XLK"},{"name":"Financials","class":"sector","symbol":"XLF"},{"name":"Energy","class":"sector","symbol":"XLE"},{"name":"Health Care","class":"sector","symbol":"XLV"},{"name":"Utilities","class":"sector","symbol":"XLU"},{"name":"Gold","class":"commodity","symbol":"GLD"},{"name":"Silver","class":"commodity","symbol":"SLV"},{"name":"Crude Oil","class":"commodity","symbol":"USO"},{"name":"Broad Commodities","class":"commodity","symbol":"DBC"},{"name":"20Y+ Treasuries","class":"bond","symbol":"TLT"},{"name":"High-Yield Credit","class":"bond","symbol":"HYG"},{"name":"US Aggregate Bonds","class":"bond","symbol":"AGG"},{"name":"EUR/USD","class":"fx","symbol":"EURUSD=X"},{"name":"Bitcoin","class":"crypto","symbol":"BTC-USD"},{"name":"Ethereum","class":"crypto","symbol":"ETH-USD"}],"source":"Yahoo Finance","classes":["equity","sector","commodity","bond","fx","crypto"]},"meta":{"timestamp":"2026-06-12T10:34:45.091Z","request_id":"52b0fe75-031d-4a43-915d-aa7a6fef13c0"},"status":"ok","message":"Universe retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Service metadata","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"benchmark is any universe symbol (default SPY). window is 90-756 trading days (default 252). tail is the extreme-day percentile, 5-25 (default 10). class filters to equity/sector/commodity/bond/fx/crypto (default all). Correlations are Pearson on daily returns. Read fresh per call, nothing cached.","source":"Yahoo Finance daily closes, live","classes":["equity","sector","commodity","bond","fx","crypto"],"service":"tailcorr-api","endpoints":{"GET /v1/meta":"This document.","GET /v1/asset":"Full tail-correlation profile of one instrument (symbol=HYG, benchmark=SPY, tail=10, window=252).","GET /v1/screener":"Rank the universe by crash correlation, with the diversification breakdown (benchmark=SPY, tail=10, window=252, class=all).","GET /v1/universe":"The cross-asset universe and its classes."},"description":"Tail correlation / diversification breakdown — correlations that look low in calm markets but spike toward 1 when the market crashes, live from Yahoo Finance daily closes (no key, nothing stored). For each asset it returns the ordinary correlation to the benchmark, the crash correlation (only the benchmark's worst days), the rally correlation (its best days) and the breakdown (crash minus normal). A low normal but high crash correlation marks a false diversifier; a low or negative crash correlation is a genuine hedge. asset returns one instrument's tail-correlation profile; screener ranks the cross-asset universe by crash correlation. The conditional / tail-correlation cut — distinct from the unconditional cross-asset, sector and FX correlation matrices, the up/down capture API and the price APIs.","universe_size":20,"upstream_status":"ok","biggest_breakdown_vs_spy":"USO"},"meta":{"timestamp":"2026-06-12T10:34:45.595Z","request_id":"fb252421-3115-4213-aec7-ba71f5915cce"},"status":"ok","message":"Meta","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":675,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1280,"monthly_call_quota":15100,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":3700,"monthly_call_quota":84500,"rps_limit":16,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":8120,"monthly_call_quota":472000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/tailcorr-api"}