{"openapi":"3.1.0","info":{"title":"Ulcer Index API","version":"1.0.0","description":"Ranks a cross-asset universe by how painful each market's drawdowns have been, and how much return it paid for that pain, computed live from Yahoo Finance daily closes — no key, nothing stored. Volatility treats an up-move and a down-move as equally risky, but investors only lose sleep over the downside: the depth of the fall from the last high and how long it drags on before recovering. The Ulcer Index (Peter Martin) captures exactly that — the root-mean-square of every day's percentage drawdown from the running peak, so a deep, long drawdown is penalised far more than a brief dip and a market that keeps making new highs scores near zero. From it comes the Martin ratio (the Ulcer Performance Index) — annualised excess return divided by the Ulcer Index — the return earned per unit of drawdown pain, a downside-only cousin of the Sharpe ratio. The asset endpoint returns one instrument's full pain profile: Ulcer Index, maximum, average and current drawdown, longest time underwater, the Martin ratio and the pain ratio. The screener endpoint ranks the 21-instrument universe (equities, sectors, commodities, bonds, crypto; filterable by class) by Martin ratio (best pain-adjusted return) or by Ulcer Index (smoothest ride). This is the drawdown-pain / Ulcer-Index cut — distinct from a current-drawdown monitor (a point-in-time snapshot of how far below peak each market is), the Sharpe/Sortino/Calmar screener (Calmar uses only the single worst drawdown) and the price APIs. It scores the whole shape of the pain, not one point of it.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/ulcerindex-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 Martin ratio or Ulcer Index","description":"","parameters":[{"name":"metric","in":"query","required":false,"description":"martin (best pain-adjusted return) or ulcer (smoothest)","schema":{"type":"string"},"example":"martin"},{"name":"window","in":"query","required":false,"description":"Lookback in trading days (60-756)","schema":{"type":"string"},"example":"252"},{"name":"class","in":"query","required":false,"description":"equity, sector, commodity, bond, crypto or all","schema":{"type":"string"},"example":"all"},{"name":"rf","in":"query","required":false,"description":"Annual risk-free percent (0-20)","schema":{"type":"string"},"example":"0"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Ranked by Martin ratio descending (best pain-adjusted return first) over window_days of daily closes. Ulcer Index = RMS of daily drawdowns from the running peak (a deep, long drawdown is penalised most). Martin ratio = annualised excess return / Ulcer Index. Read fresh per call, nothing cached.","class":"all","count":21,"metric":"martin","source":"Yahoo Finance","results":[{"name":"US Small Caps","rank":1,"class":"equity","symbol":"IWM","available":true,"pain_index":2.15,"pain_ratio":16.768,"ulcer_index":3.17,"martin_ratio":11.407,"observations":252,"ann_return_pct":36.11,"avg_drawdown_pct":-2.62,"max_drawdown_pct":-11.19,"current_drawdown_pct":-0.55,"current_underwater_days":10,"longest_underwater_days":57},{"name":"S&P 500","rank":2,"class":"equity","symbol":"SPY","available":true,"pain_index":1.16,"pain_ratio":19.699,"ulcer_index":2.01,"martin_ratio":11.36,"observations":252,"ann_return_pct":22.78,"avg_drawdown_pct":-1.56,"max_drawdown_pct":-9.13,"current_drawdown_pct":-2.87,"current_underwater_days":7,"longest_underwater_days":53},{"name":"Emerging Markets","rank":3,"class":"equity","symbol":"EEM","available":true,"pain_index":2.27,"pain_ratio":18.271,"ulcer_index":3.71,"martin_ratio":11.161,"observations":252,"ann_return_pct":41.44,"avg_drawdown_pct":-2.98,"max_drawdown_pct":-13.52,"current_drawdown_pct":-4.66,"current_underwater_days":7,"longest_underwater_days":43},{"name":"Nasdaq 100","rank":4,"class":"equity","symbol":"QQQ","available":true,"pain_index":2.18,"pain_ratio":15.978,"ulcer_index":3.26,"martin_ratio":10.693,"observations":252,"ann_return_pct":34.85,"avg_drawdown_pct":-2.82,"max_drawdown_pct":-12.19,"current_drawdown_pct":-3.89,"current_underwater_days":7,"longest_underwater_days":113},{"name":"Technology","rank":5,"class":"sector","symbol":"XLK","available":true,"pain_index":3.47,"pain_ratio":15.187,"ulcer_index":4.98,"martin_ratio":10.592,"observations":252,"ann_return_pct":52.72,"avg_drawdown_pct":-4.44,"max_drawdown_pct":-16.15,"current_drawdown_pct":-7.57,"current_underwater_days":7,"longest_underwater_days":115},{"name":"Broad Commodities","rank":6,"class":"commodity","symbol":"DBC","available":true,"pain_index":2.89,"pain_ratio":10.868,"ulcer_index":3.58,"martin_ratio":8.787,"observations":252,"ann_return_pct":31.46,"avg_drawdown_pct":-3.38,"max_drawdown_pct":-8.96,"current_drawdown_pct":-8.96,"current_underwater_days":21,"longest_underwater_days":99},{"name":"Energy","rank":7,"class":"sector","symbol":"XLE","available":true,"pain_index":3.18,"pain_ratio":10.221,"ulcer_index":4.33,"martin_ratio":7.508,"observations":252,"ann_return_pct":32.54,"avg_drawdown_pct":-3.84,"max_drawdown_pct":-12.05,"current_drawdown_pct":-8.7,"current_underwater_days":52,"longest_underwater_days":52},{"name":"Industrials","rank":8,"class":"sector","symbol":"XLI","available":true,"pain_index":2.21,"pain_ratio":9.751,"ulcer_index":3.18,"martin_ratio":6.759,"observations":252,"ann_return_pct":21.52,"avg_drawdown_pct":-2.6,"max_drawdown_pct":-12.46,"current_drawdown_pct":-2.1,"current_underwater_days":71,"longest_underwater_days":71},{"name":"Crude Oil","rank":9,"class":"commodity","symbol":"USO","available":true,"pain_index":9.7,"pain_ratio":7.482,"ulcer_index":11,"martin_ratio":6.594,"observations":252,"ann_return_pct":72.56,"avg_drawdown_pct":-10.53,"max_drawdown_pct":-20.39,"current_drawdown_pct":-15.78,"current_underwater_days":16,"longest_underwater_days":173},{"name":"Developed ex-US","rank":10,"class":"equity","symbol":"EFA","available":true,"pain_index":2.09,"pain_ratio":8.051,"ulcer_index":3.14,"martin_ratio":5.355,"observations":252,"ann_return_pct":16.83,"avg_drawdown_pct":-2.39,"max_drawdown_pct":-11.42,"current_drawdown_pct":-0.88,"current_underwater_days":74,"longest_underwater_days":74},{"name":"Silver","rank":11,"class":"commodity","symbol":"SLV","available":true,"pain_index":13.89,"pain_ratio":6.124,"ulcer_index":20.71,"martin_ratio":4.105,"observations":252,"ann_return_pct":85.03,"avg_drawdown_pct":-17.41,"max_drawdown_pct":-45.4,"current_drawdown_pct":-42.41,"current_underwater_days":93,"longest_underwater_days":93},{"name":"Gold","rank":12,"class":"commodity","symbol":"GLD","available":true,"pain_index":5.99,"pain_ratio":4.24,"ulcer_index":8.38,"martin_ratio":3.03,"observations":252,"ann_return_pct":25.39,"avg_drawdown_pct":-7.12,"max_drawdown_pct":-24.46,"current_drawdown_pct":-22.1,"current_underwater_days":92,"longest_underwater_days":92},{"name":"Health Care","rank":13,"class":"sector","symbol":"XLV","available":true,"pain_index":3.3,"pain_ratio":4.11,"ulcer_index":4.54,"martin_ratio":2.987,"observations":252,"ann_return_pct":13.57,"avg_drawdown_pct":-3.59,"max_drawdown_pct":-10.84,"current_drawdown_pct":-3.81,"current_underwater_days":72,"longest_underwater_days":72},{"name":"Real Estate","rank":14,"class":"sector","symbol":"XLRE","available":true,"pain_index":2.76,"pain_ratio":2.533,"ulcer_index":3.39,"martin_ratio":2.061,"observations":252,"ann_return_pct":6.98,"avg_drawdown_pct":-2.91,"max_drawdown_pct":-8.94,"current_drawdown_pct":-0.16,"current_underwater_days":1,"longest_underwater_days":140},{"name":"Utilities","rank":15,"class":"sector","symbol":"XLU","available":true,"pain_index":3.61,"pain_ratio":2.472,"ulcer_index":4.55,"martin_ratio":1.961,"observations":252,"ann_return_pct":8.92,"avg_drawdown_pct":-4.03,"max_drawdown_pct":-9.86,"current_drawdown_pct":-7.71,"current_underwater_days":72,"longest_underwater_days":82},{"name":"US Aggregate Bonds","rank":16,"class":"bond","symbol":"AGG","available":true,"pain_index":1.12,"pain_ratio":0.854,"ulcer_index":1.43,"martin_ratio":0.668,"observations":252,"ann_return_pct":0.95,"avg_drawdown_pct":-1.24,"max_drawdown_pct":-3.72,"current_drawdown_pct":-2.49,"current_underwater_days":72,"longest_underwater_days":82},{"name":"Financials","rank":17,"class":"sector","symbol":"XLF","available":true,"pain_index":4.43,"pain_ratio":0.721,"ulcer_index":5.93,"martin_ratio":0.538,"observations":252,"ann_return_pct":3.19,"avg_drawdown_pct":-4.94,"max_drawdown_pct":-15.23,"current_drawdown_pct":-6.7,"current_underwater_days":108,"longest_underwater_days":108},{"name":"High-Yield Credit","rank":18,"class":"bond","symbol":"HYG","available":true,"pain_index":0.9,"pain_ratio":0.606,"ulcer_index":1.14,"martin_ratio":0.475,"observations":252,"ann_return_pct":0.54,"avg_drawdown_pct":-0.96,"max_drawdown_pct":-3.2,"current_drawdown_pct":-1.7,"current_underwater_days":181,"longest_underwater_days":181},{"name":"20Y+ Treasuries","rank":19,"class":"bond","symbol":"TLT","available":true,"pain_index":3.52,"pain_ratio":-0.053,"ulcer_index":4.27,"martin_ratio":-0.044,"observations":252,"ann_return_pct":-0.19,"avg_drawdown_pct":-3.79,"max_drawdown_pct":-9.82,"current_drawdown_pct":-6.6,"current_underwater_days":159,"longest_underwater_days":159},{"name":"Bitcoin","rank":20,"class":"crypto","symbol":"BTC-USD","available":true,"pain_index":32.88,"pain_ratio":-1.465,"ulcer_index":35.04,"martin_ratio":-1.375,"observations":252,"ann_return_pct":-48.16,"avg_drawdown_pct":-33.27,"max_drawdown_pct":-51.21,"current_drawdown_pct":-49,"current_underwater_days":249,"longest_underwater_days":249},{"name":"Ethereum","rank":21,"class":"crypto","symbol":"ETH-USD","available":true,"pain_index":42.72,"pain_ratio":-1.471,"ulcer_index":45.33,"martin_ratio":-1.387,"observations":252,"ann_return_pct":-62.86,"avg_drawdown_pct":-43.24,"max_drawdown_pct":-66.53,"current_drawdown_pct":-64.29,"current_underwater_days":249,"longest_underwater_days":249}],"smoothest":{"symbol":"HYG","ulcer_index":1.14},"sorted_by":"martin_ratio","unavailable":[],"window_days":252,"most_painful":{"symbol":"ETH-USD","ulcer_index":45.33},"risk_free_pct":0},"meta":{"timestamp":"2026-06-12T10:34:51.310Z","request_id":"8cf5dbec-0163-4044-a7a9-a450d361ab72"},"status":"ok","message":"Ulcer Index 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 drawdown-pain profile of one instrument","description":"","parameters":[{"name":"symbol","in":"query","required":true,"description":"Universe symbol","schema":{"type":"string"},"example":"GLD"},{"name":"window","in":"query","required":false,"description":"Lookback in trading days (60-756)","schema":{"type":"string"},"example":"252"},{"name":"rf","in":"query","required":false,"description":"Annual risk-free percent (0-20)","schema":{"type":"string"},"example":"0"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"name":"Gold","note":"Ulcer Index = RMS of daily drawdowns from the running peak over window_days; max/avg drawdown and longest_underwater_days describe the worst and the typical pain. Martin ratio = annualised excess return / Ulcer Index; pain ratio uses the mean absolute drawdown. Read fresh per call, nothing cached.","class":"commodity","reads":{"ulcer":"high drawdown pain","martin":"excellent return per unit of drawdown pain","underwater":"currently -22.1% below peak, 92 trading days underwater"},"source":"Yahoo Finance","symbol":"GLD","pain_index":5.99,"pain_ratio":4.24,"ulcer_index":8.38,"window_days":252,"martin_ratio":3.03,"observations":252,"risk_free_pct":0,"ann_return_pct":25.39,"avg_drawdown_pct":-7.12,"max_drawdown_pct":-24.46,"current_drawdown_pct":-22.1,"current_underwater_days":92,"longest_underwater_days":92},"meta":{"timestamp":"2026-06-12T10:34:51.495Z","request_id":"e96c74b2-f596-4208-a463-a682130afc14"},"status":"ok","message":"Asset pain profile 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":21,"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":"Industrials","class":"sector","symbol":"XLI"},{"name":"Utilities","class":"sector","symbol":"XLU"},{"name":"Real Estate","class":"sector","symbol":"XLRE"},{"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":"Bitcoin","class":"crypto","symbol":"BTC-USD"},{"name":"Ethereum","class":"crypto","symbol":"ETH-USD"}],"source":"Yahoo Finance","classes":["equity","sector","commodity","bond","crypto"]},"meta":{"timestamp":"2026-06-12T10:34:51.620Z","request_id":"a671e8df-2ae1-4a72-b274-dac38cc6f88d"},"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":"metric is martin (default, best pain-adjusted return) or ulcer (least painful). window is 60-756 trading days (default 252). rf is an optional annual risk-free percent (0-20) netted off the Martin/pain ratios. class filters to equity/sector/commodity/bond/crypto (default all). Read fresh per call, nothing cached.","source":"Yahoo Finance daily closes, live","classes":["equity","sector","commodity","bond","crypto"],"metrics":["martin","ulcer"],"service":"ulcerindex-api","endpoints":{"GET /v1/meta":"This document.","GET /v1/asset":"Full drawdown-pain profile of one instrument (symbol=GLD, window=252, rf=0).","GET /v1/screener":"Rank the universe by Martin ratio or Ulcer Index (metric=martin, window=252, class=all, rf=0).","GET /v1/universe":"The cross-asset universe and its classes."},"description":"Ulcer Index & pain-adjusted return — ranks a cross-asset universe by how painful each market's drawdowns have been and how much return it paid for that pain, live from Yahoo Finance daily closes (no key, nothing stored). The Ulcer Index is the RMS of every day's drawdown from the running peak (depth and duration), and the Martin ratio is annualised excess return divided by it. asset returns one instrument's full pain profile (Ulcer Index, max/avg/current drawdown, longest time underwater, Martin and pain ratios); screener ranks the universe by Martin ratio or Ulcer Index. The drawdown-pain cut — distinct from the current-drawdown monitor (a snapshot of how far below peak each market is), the Sharpe/Sortino/Calmar screener (Calmar uses only the single worst drawdown) and the price APIs.","universe_size":21,"smoothest_252d":"HYG","upstream_status":"ok"},"meta":{"timestamp":"2026-06-12T10:34:51.826Z","request_id":"3bb86b21-fca9-4c0f-b22f-ee8c3a53e9ae"},"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":760,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1090,"monthly_call_quota":16400,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":3480,"monthly_call_quota":88000,"rps_limit":16,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":7860,"monthly_call_quota":488000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/ulcerindex-api"}