{"openapi":"3.1.0","info":{"title":"Nephyr Risk API","summary":"Prediction market risk management — Kelly sizing, EV, drawdown protection.","contact":{"name":"CLM Studios","url":"https://github.com/clm-studios/nephyr-risk"},"license":{"name":"MIT"},"version":"0.1.0"},"paths":{"/v1/health":{"get":{"tags":["meta"],"summary":"Health check","description":"Returns 200 when the API is up. Includes library version.","operationId":"health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/kelly":{"post":{"tags":["sizing"],"summary":"Kelly position sizing","description":"Calculate the recommended position size using the Kelly criterion.\n\nUses quarter-Kelly (default `kelly_fraction=0.25`) with a hard bankroll-percentage cap.\nReturns `size=0` with a descriptive `cap_reason` when there is no edge or inputs are invalid.","operationId":"kelly_v1_kelly_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KellyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KellyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/ev":{"post":{"tags":["analysis"],"summary":"Expected value calculation","description":"Calculate the expected value of a YES contract after platform fees.\n\nFee models:\n- **Polymarket**: flat 2% of price per leg (`fee = 0.02 × price`)\n- **Kalshi**: non-linear `fee = 0.07 × P × (1−P)` (peaks at P=0.50)\n\nA positive `ev` means the trade has edge after fees.","operationId":"ev_v1_ev_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EVRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EVResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/risk-status":{"post":{"tags":["risk"],"summary":"Current risk status","description":"Check current risk management status against configured limits.\n\nReturns one of three statuses:\n- **ACTIVE** — All limits clear, trading allowed.\n- **PAUSED** — Daily loss limit hit, resume tomorrow.\n- **SHUTDOWN** — Drawdown limit hit, manual review required.\n\nNon-blocking warnings are raised at 70% of each limit.","operationId":"risk_status_v1_risk_status_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskStatusRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/validate-trade":{"post":{"tags":["risk"],"summary":"Pre-trade risk validation","description":"Validate whether a proposed trade passes all pre-trade risk checks.\n\nProjects the worst case (full loss of `proposed_size`) and checks whether\nit would breach the daily loss or drawdown limits.\n\nReturns `approved=True` when the trade is safe to take.","operationId":"validate_trade_endpoint_v1_validate_trade_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateTradeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateTradeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/exposure":{"post":{"tags":["portfolio"],"summary":"Portfolio exposure analysis","description":"Summarise portfolio exposure relative to bankroll.\n\nPass a list of open positions (each with a `size` in USD).\nReturns total and largest position percentages, and a concentration risk flag\n(triggered when any single position exceeds 10% of bankroll).","operationId":"exposure_v1_exposure_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExposureRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExposureResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/drawdown":{"post":{"tags":["analysis"],"summary":"Drawdown simulation","description":"Simulate a hypothetical sequence of losses and report when risk limits trigger.\n\nPass a `loss_sequence` (positive values = losses, negative = gains).\nThe simulation walks through each event, tracking the running bankroll\nand flagging when daily loss or drawdown limits would be breached.","operationId":"drawdown_v1_drawdown_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrawdownRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrawdownResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/fee":{"post":{"tags":["analysis"],"summary":"Platform fee calculation","description":"Calculate the fee per leg for a given platform and contract price.\n\n- **Polymarket**: `fee = 0.02 × price`\n- **Kalshi**: `fee = 0.07 × P × (1−P)`\n\nReturns both `fee_per_leg` and `round_trip_fee` (entry + exit).","operationId":"fee_v1_fee_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"DrawdownEventItem":{"properties":{"n":{"type":"integer","title":"N","description":"1-indexed step number in the loss sequence."},"loss_usd":{"type":"number","title":"Loss Usd","description":"Dollar loss for this step (negative = gain)."},"bankroll":{"type":"number","title":"Bankroll","description":"Running bankroll after this step."},"cumulative_loss_usd":{"type":"number","title":"Cumulative Loss Usd","description":"Total cumulative loss after this step."},"daily_loss_pct":{"type":"number","title":"Daily Loss Pct","description":"Daily loss as % of peak bankroll after this step."},"drawdown_pct":{"type":"number","title":"Drawdown Pct","description":"Drawdown from peak as % after this step."},"status":{"type":"string","title":"Status","description":"'ACTIVE', 'PAUSED', or 'SHUTDOWN' after this step."}},"type":"object","required":["n","loss_usd","bankroll","cumulative_loss_usd","daily_loss_pct","drawdown_pct","status"],"title":"DrawdownEventItem"},"DrawdownRequest":{"properties":{"bankroll":{"type":"number","exclusiveMinimum":0.0,"title":"Bankroll","description":"Starting bankroll in USD.","examples":[1000.0]},"loss_sequence":{"items":{"type":"number"},"type":"array","minItems":1,"title":"Loss Sequence","description":"List of loss amounts in USD (positive = loss, negative = gain).","examples":[[30,40,50,60,70]]},"daily_loss_limit_pct":{"type":"number","maximum":100.0,"exclusiveMinimum":0.0,"title":"Daily Loss Limit Pct","description":"Daily loss ceiling as % of peak bankroll.","default":10.0},"drawdown_limit_pct":{"type":"number","maximum":100.0,"exclusiveMinimum":0.0,"title":"Drawdown Limit Pct","description":"Drawdown ceiling as % of peak bankroll.","default":25.0}},"type":"object","required":["bankroll","loss_sequence"],"title":"DrawdownRequest","examples":[{"bankroll":1000,"daily_loss_limit_pct":10.0,"drawdown_limit_pct":25.0,"loss_sequence":[30,40,50,60,70]}]},"DrawdownResponse":{"properties":{"final_bankroll":{"type":"number","title":"Final Bankroll","description":"Bankroll after all events in the sequence."},"max_drawdown_pct":{"type":"number","title":"Max Drawdown Pct","description":"Highest drawdown % reached during the simulation."},"max_daily_loss_pct":{"type":"number","title":"Max Daily Loss Pct","description":"Highest daily loss % reached during the simulation."},"total_loss_usd":{"type":"number","title":"Total Loss Usd","description":"Net total loss in USD across all events."},"would_pause":{"type":"boolean","title":"Would Pause","description":"True if daily loss limit was breached at any point."},"would_shutdown":{"type":"boolean","title":"Would Shutdown","description":"True if drawdown limit was breached at any point."},"pause_after_n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pause After N","description":"Step number that triggered PAUSE, null if never triggered."},"shutdown_after_n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Shutdown After N","description":"Step number that triggered SHUTDOWN, null if never triggered."},"events":{"items":{"$ref":"#/components/schemas/DrawdownEventItem"},"type":"array","title":"Events","description":"Per-step detail for each loss event."}},"type":"object","required":["final_bankroll","max_drawdown_pct","max_daily_loss_pct","total_loss_usd","would_pause","would_shutdown","pause_after_n","shutdown_after_n","events"],"title":"DrawdownResponse"},"EVRequest":{"properties":{"model_probability":{"type":"number","exclusiveMaximum":1.0,"exclusiveMinimum":0.0,"title":"Model Probability","description":"Your model's probability of YES resolving (exclusive: 0 < p < 1).","examples":[0.65]},"market_price":{"type":"number","exclusiveMaximum":1.0,"exclusiveMinimum":0.0,"title":"Market Price","description":"Current YES price on the exchange (exclusive: 0 < price < 1).","examples":[0.5]},"platform":{"type":"string","pattern":"^(polymarket|kalshi)$","title":"Platform","description":"Fee model: 'polymarket' (flat 2%) or 'kalshi' (7% × P × (1−P)).","default":"polymarket"}},"type":"object","required":["model_probability","market_price"],"title":"EVRequest","examples":[{"market_price":0.5,"model_probability":0.65,"platform":"polymarket"}]},"EVResponse":{"properties":{"ev":{"type":"number","title":"Ev","description":"Expected value per dollar risked (can be negative)."},"edge":{"type":"number","title":"Edge","description":"Model probability minus market price (before fees)."},"fee_per_leg":{"type":"number","title":"Fee Per Leg","description":"Fee per leg in probability units."},"round_trip_fee":{"type":"number","title":"Round Trip Fee","description":"Total fees for entry + exit (2 × fee_per_leg)."},"is_positive":{"type":"boolean","title":"Is Positive","description":"True when EV > 0."}},"type":"object","required":["ev","edge","fee_per_leg","round_trip_fee","is_positive"],"title":"EVResponse"},"ExposureRequest":{"properties":{"positions":{"items":{"$ref":"#/components/schemas/PositionItem"},"type":"array","title":"Positions","description":"List of open positions. Each must have a 'size' (dollar amount at risk)."},"bankroll":{"type":"number","exclusiveMinimum":0.0,"title":"Bankroll","description":"Total capital in USD.","examples":[1000.0]}},"type":"object","required":["positions","bankroll"],"title":"ExposureRequest","examples":[{"bankroll":1000,"positions":[{"market":"ETH-USD","size":80},{"size":60},{"size":40}]}]},"ExposureResponse":{"properties":{"total_exposure_usd":{"type":"number","title":"Total Exposure Usd","description":"Sum of all position sizes in USD."},"total_exposure_pct":{"type":"number","title":"Total Exposure Pct","description":"Total exposure as % of bankroll."},"largest_position_usd":{"type":"number","title":"Largest Position Usd","description":"Largest single position in USD."},"largest_position_pct":{"type":"number","title":"Largest Position Pct","description":"Largest single position as % of bankroll."},"num_positions":{"type":"integer","title":"Num Positions","description":"Number of open positions."},"concentration_risk":{"type":"boolean","title":"Concentration Risk","description":"True if any single position exceeds 10% of bankroll."},"positions_above_5pct":{"type":"integer","title":"Positions Above 5Pct","description":"Number of positions above 5% of bankroll."}},"type":"object","required":["total_exposure_usd","total_exposure_pct","largest_position_usd","largest_position_pct","num_positions","concentration_risk","positions_above_5pct"],"title":"ExposureResponse"},"FeeRequest":{"properties":{"price":{"type":"number","exclusiveMaximum":1.0,"exclusiveMinimum":0.0,"title":"Price","description":"Contract price as a probability (exclusive: 0 < price < 1).","examples":[0.5]},"platform":{"type":"string","pattern":"^(polymarket|kalshi)$","title":"Platform","description":"Fee model: 'polymarket' or 'kalshi'."}},"type":"object","required":["price","platform"],"title":"FeeRequest","examples":[{"platform":"polymarket","price":0.5}]},"FeeResponse":{"properties":{"fee_per_leg":{"type":"number","title":"Fee Per Leg","description":"Fee for one direction (entry or exit) in probability units."},"round_trip_fee":{"type":"number","title":"Round Trip Fee","description":"Total fee for entry + exit (2 × fee_per_leg)."},"platform":{"type":"string","title":"Platform","description":"Platform used for the calculation."},"price":{"type":"number","title":"Price","description":"Contract price that was evaluated."}},"type":"object","required":["fee_per_leg","round_trip_fee","platform","price"],"title":"FeeResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Always 'ok' when the server is up."},"version":{"type":"string","title":"Version","description":"API version string."},"library":{"type":"string","title":"Library","description":"Core nephyr_risk library version."}},"type":"object","required":["status","version","library"],"title":"HealthResponse"},"KellyRequest":{"properties":{"probability":{"type":"number","exclusiveMaximum":1.0,"exclusiveMinimum":0.0,"title":"Probability","description":"Model probability of the YES outcome (exclusive: 0 < p < 1).","examples":[0.6]},"entry_price":{"type":"number","exclusiveMaximum":1.0,"exclusiveMinimum":0.0,"title":"Entry Price","description":"Current market price for the YES contract (exclusive: 0 < price < 1).","examples":[0.4]},"bankroll":{"type":"number","exclusiveMinimum":0.0,"title":"Bankroll","description":"Available capital in USD.","examples":[1000.0]},"kelly_fraction":{"type":"number","maximum":1.0,"exclusiveMinimum":0.0,"title":"Kelly Fraction","description":"Fraction of full Kelly to use (0.25 = quarter-Kelly, recommended).","default":0.25},"max_position_pct":{"type":"number","exclusiveMinimum":0.0,"title":"Max Position Pct","description":"Hard cap as percentage of bankroll per trade.","default":5.0},"min_size":{"type":"number","minimum":0.0,"title":"Min Size","description":"Minimum position size in USD. Returns size=0 if below this.","default":1.0}},"type":"object","required":["probability","entry_price","bankroll"],"title":"KellyRequest","examples":[{"bankroll":1000,"entry_price":0.4,"kelly_fraction":0.25,"max_position_pct":5.0,"min_size":1.0,"probability":0.6}]},"KellyResponse":{"properties":{"size":{"type":"number","title":"Size","description":"Recommended position size in USD (0 if no edge or invalid)."},"full_kelly":{"type":"number","title":"Full Kelly","description":"Raw (full) Kelly fraction before scaling."},"quarter_kelly":{"type":"number","title":"Quarter Kelly","description":"Scaled Kelly fraction (full_kelly × kelly_fraction)."},"capped":{"type":"boolean","title":"Capped","description":"True if the size was capped by the bankroll-pct limit."},"cap_reason":{"type":"string","title":"Cap Reason","description":"'bankroll_pct' if capped, 'none' if not, or an error code."}},"type":"object","required":["size","full_kelly","quarter_kelly","capped","cap_reason"],"title":"KellyResponse"},"PositionItem":{"properties":{"size":{"type":"number","exclusiveMinimum":0.0,"title":"Size","description":"Dollar amount committed to this position."},"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market","description":"Market identifier (informational)."},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price","description":"Contract price (informational)."},"side":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Side","description":"YES or NO (informational)."}},"type":"object","required":["size"],"title":"PositionItem"},"RiskStatusRequest":{"properties":{"bankroll":{"type":"number","title":"Bankroll","description":"Current bankroll in USD.","examples":[950.0]},"daily_pnl":{"type":"number","title":"Daily Pnl","description":"Today's realised profit/loss in USD (negative = loss).","examples":[-50.0]},"peak_bankroll":{"type":"number","exclusiveMinimum":0.0,"title":"Peak Bankroll","description":"Highest bankroll ever reached in USD.","examples":[1000.0]},"daily_loss_limit_pct":{"type":"number","maximum":100.0,"exclusiveMinimum":0.0,"title":"Daily Loss Limit Pct","description":"Maximum allowable daily loss as % of peak bankroll.","default":10.0},"drawdown_limit_pct":{"type":"number","maximum":100.0,"exclusiveMinimum":0.0,"title":"Drawdown Limit Pct","description":"Maximum allowable drawdown from peak as % of peak bankroll.","default":25.0}},"type":"object","required":["bankroll","daily_pnl","peak_bankroll"],"title":"RiskStatusRequest","examples":[{"bankroll":950,"daily_loss_limit_pct":10.0,"daily_pnl":-50,"drawdown_limit_pct":25.0,"peak_bankroll":1000}]},"RiskStatusResponse":{"properties":{"status":{"type":"string","title":"Status","description":"'ACTIVE', 'PAUSED' (daily limit hit), or 'SHUTDOWN' (drawdown limit hit)."},"can_trade":{"type":"boolean","title":"Can Trade","description":"False when status is PAUSED or SHUTDOWN."},"daily_loss_pct":{"type":"number","title":"Daily Loss Pct","description":"Current daily loss as % of peak bankroll."},"drawdown_pct":{"type":"number","title":"Drawdown Pct","description":"Current drawdown from peak bankroll as %."},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Non-blocking warnings (e.g. approaching a limit)."}},"type":"object","required":["status","can_trade","daily_loss_pct","drawdown_pct","warnings"],"title":"RiskStatusResponse"},"ValidateTradeRequest":{"properties":{"proposed_size":{"type":"number","exclusiveMinimum":0.0,"title":"Proposed Size","description":"Dollar amount of the proposed position.","examples":[50.0]},"bankroll":{"type":"number","exclusiveMinimum":0.0,"title":"Bankroll","description":"Current bankroll in USD.","examples":[1000.0]},"daily_pnl":{"type":"number","title":"Daily Pnl","description":"Today's realised P&L in USD (negative = loss).","examples":[0.0]},"peak_bankroll":{"type":"number","exclusiveMinimum":0.0,"title":"Peak Bankroll","description":"Highest bankroll ever reached in USD.","examples":[1000.0]},"daily_loss_limit_pct":{"type":"number","maximum":100.0,"exclusiveMinimum":0.0,"title":"Daily Loss Limit Pct","description":"Daily loss ceiling as % of peak bankroll.","default":10.0},"drawdown_limit_pct":{"type":"number","maximum":100.0,"exclusiveMinimum":0.0,"title":"Drawdown Limit Pct","description":"Drawdown ceiling as % of peak bankroll.","default":25.0}},"type":"object","required":["proposed_size","bankroll","daily_pnl","peak_bankroll"],"title":"ValidateTradeRequest","examples":[{"bankroll":1000,"daily_pnl":0,"peak_bankroll":1000,"proposed_size":50}]},"ValidateTradeResponse":{"properties":{"approved":{"type":"boolean","title":"Approved","description":"True if the trade passes all risk checks."},"rejection_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rejection Reason","description":"Human-readable reason if rejected, null if approved."},"projected_daily_loss_pct":{"type":"number","title":"Projected Daily Loss Pct","description":"Worst-case daily loss % if this trade loses entirely."},"projected_drawdown_pct":{"type":"number","title":"Projected Drawdown Pct","description":"Worst-case drawdown % if this trade loses entirely."}},"type":"object","required":["approved","rejection_reason","projected_daily_loss_pct","projected_drawdown_pct"],"title":"ValidateTradeResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}