{"openapi":"3.1.0","info":{"title":"Mercurius","description":"Agentic Risk Firewall — pre-execution margin validation for AI trading agents","version":"1.0.0"},"paths":{"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/ready":{"get":{"summary":"Ready","operationId":"ready_ready_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/info":{"get":{"summary":"Info","operationId":"info_v1_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/evaluate":{"post":{"summary":"Evaluate","description":"Evaluate a proposed trade via the Airlock pipeline.\n\nFlow:\n1. Gate A — LLM semantic intent check (if enabled)\n2. Gate B — math-based firewall evaluation\n3. Sign token if APPROVED\n4. Append to audit log\n5. Return FirewallResponse","operationId":"evaluate_v1_evaluate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentIntent"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirewallResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/schwab/auth-url":{"get":{"tags":["schwab"],"summary":"Get Auth Url","operationId":"get_auth_url_v1_schwab_auth_url_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/schwab/callback":{"get":{"tags":["schwab"],"summary":"Callback Redirect","description":"Handle Schwab's browser redirect (GET with ?code=).","operationId":"callback_redirect_v1_schwab_callback_get","parameters":[{"name":"code","in":"query","required":true,"schema":{"type":"string","title":"Code"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["schwab"],"summary":"Exchange Code","operationId":"exchange_code_v1_schwab_callback_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallbackRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallbackResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/schwab/refresh":{"post":{"tags":["schwab"],"summary":"Refresh Token","operationId":"refresh_token_v1_schwab_refresh_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallbackResponse"}}}}}}},"/v1/schwab/status":{"get":{"tags":["schwab"],"summary":"Token Status","operationId":"token_status_v1_schwab_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}}}}},"/robots.txt":{"get":{"summary":"Robots Txt","description":"Return robots.txt for AI crawler discoverability.","operationId":"robots_txt_robots_txt_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/llms.txt":{"get":{"summary":"Llms Txt","description":"Return machine-readable service description.","operationId":"llms_txt_llms_txt_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/v1/ucp/link":{"post":{"summary":"Link Identity","description":"Direct identity linking (simplified, no OAuth flow).","operationId":"link_identity_v1_ucp_link_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Revoke Link","description":"Revoke a broker identity link.","operationId":"revoke_link_v1_ucp_link_delete","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/ucp/identities/{agent_id}":{"get":{"summary":"Get Identities","description":"List linked broker identities for an agent.","operationId":"get_identities_v1_ucp_identities__agent_id__get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/ucp/authorize":{"get":{"summary":"Authorize","description":"OAuth authorize endpoint — returns an authorization code.","operationId":"authorize_v1_ucp_authorize_get","parameters":[{"name":"agent_id","in":"query","required":true,"schema":{"type":"string","title":"Agent Id"}},{"name":"broker","in":"query","required":true,"schema":{"type":"string","title":"Broker"}},{"name":"account_id","in":"query","required":true,"schema":{"type":"string","title":"Account Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/ucp/token":{"post":{"summary":"Exchange Token","description":"Exchange an authorization code for an access token.","operationId":"exchange_token_v1_ucp_token_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/ucp/capabilities":{"get":{"summary":"Get Capabilities","description":"Discover Mercurius capabilities and tier structure.","operationId":"get_capabilities_v1_ucp_capabilities_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/ucp/negotiate":{"post":{"summary":"Negotiate","description":"Negotiate capabilities for a proposed request.","operationId":"negotiate_v1_ucp_negotiate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NegotiateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/ucp/agent/{agent_id}/credential":{"get":{"summary":"Get Credential","description":"Resolve an agent's current tier and capabilities.","operationId":"get_credential_v1_ucp_agent__agent_id__credential_get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AccountSnapshot":{"properties":{"account_id":{"type":"string","title":"Account Id"},"account_type":{"$ref":"#/components/schemas/AccountType","default":"MARGIN"},"option_level":{"type":"integer","maximum":5.0,"minimum":0.0,"title":"Option Level","default":3},"cash_balance":{"type":"number","title":"Cash Balance","default":0.0},"sma":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sma"},"day_trading_buying_power":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Day Trading Buying Power"},"positions":{"items":{"$ref":"#/components/schemas/PositionSnapshot"},"type":"array","title":"Positions"}},"type":"object","required":["account_id"],"title":"AccountSnapshot","description":"Account state provided by the agent."},"AccountType":{"type":"string","enum":["CASH","MARGIN","DAY_TRADER","PORTFOLIO_MARGIN","FUTURES","IRA_MARGIN"],"title":"AccountType"},"AgentIntent":{"properties":{"agent_id":{"type":"string","title":"Agent Id","description":"Unique agent identifier"},"account":{"$ref":"#/components/schemas/AccountSnapshot"},"order_legs":{"items":{"$ref":"#/components/schemas/OrderLeg"},"type":"array","minItems":1,"title":"Order Legs"},"stated_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stated Reason","description":"Agent's stated reason for the trade (used by Gate A)"},"order_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Type"},"net_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Price"}},"type":"object","required":["agent_id","account","order_legs"],"title":"AgentIntent","description":"Top-level request from an AI trading agent."},"AssetType":{"type":"string","enum":["EQUITY","OPTION","FUTURE"],"title":"AssetType"},"CallbackRequest":{"properties":{"code":{"type":"string","title":"Code"}},"type":"object","required":["code"],"title":"CallbackRequest"},"CallbackResponse":{"properties":{"status":{"type":"string","title":"Status"},"message":{"type":"string","title":"Message"}},"type":"object","required":["status","message"],"title":"CallbackResponse"},"Decision":{"type":"string","enum":["AUTHORIZED","BLOCKED","DEGRADED"],"title":"Decision"},"FirewallResponse":{"properties":{"decision":{"$ref":"#/components/schemas/Decision"},"processing_mode":{"type":"string","title":"Processing Mode","default":"RegT"},"projected_equity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Projected Equity"},"projected_maintenance_requirement":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Projected Maintenance Requirement"},"projected_reg_t_requirement":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Projected Reg T Requirement"},"projected_buying_power_change":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Projected Buying Power Change"},"dtbp_impact":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Dtbp Impact"},"current_equity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current Equity"},"current_maintenance_requirement":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current Maintenance Requirement"},"current_reg_t_requirement":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current Reg T Requirement"},"current_buying_power":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current Buying Power"},"exceeds_maintenance_call":{"type":"boolean","title":"Exceeds Maintenance Call","default":false},"exceeds_reg_t_call":{"type":"boolean","title":"Exceeds Reg T Call","default":false},"exceeds_dtbp":{"type":"boolean","title":"Exceeds Dtbp","default":false},"is_naked_option":{"type":"boolean","title":"Is Naked Option","default":false},"triggers_concentration_risk":{"type":"boolean","title":"Triggers Concentration Risk","default":false},"matched_strategies":{"items":{"type":"string"},"type":"array","title":"Matched Strategies"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"},"errors":{"items":{"type":"string"},"type":"array","title":"Errors"},"auth_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth Token"},"gate_a_passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Gate A Passed"},"gate_a_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gate A Reason"},"ucp_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ucp Tier"},"ucp_capabilities_used":{"items":{"type":"string"},"type":"array","title":"Ucp Capabilities Used"},"ucp_violations":{"items":{"type":"string"},"type":"array","title":"Ucp Violations"}},"type":"object","required":["decision"],"title":"FirewallResponse","description":"Response from POST /v1/evaluate."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Instruction":{"type":"string","enum":["BUY","SELL","BUY_TO_OPEN","BUY_TO_CLOSE","SELL_TO_OPEN","SELL_TO_CLOSE","SELL_SHORT","BUY_TO_COVER"],"title":"Instruction"},"LinkRequest":{"properties":{"agent_id":{"type":"string","title":"Agent Id"},"broker":{"type":"string","title":"Broker"},"broker_account_id":{"type":"string","title":"Broker Account Id"}},"type":"object","required":["agent_id","broker","broker_account_id"],"title":"LinkRequest"},"NegotiateRequest":{"properties":{"agent_id":{"type":"string","title":"Agent Id"},"requested_capabilities":{"items":{"type":"string"},"type":"array","title":"Requested Capabilities"},"account_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Type"},"order_leg_count":{"type":"integer","title":"Order Leg Count","default":1}},"type":"object","required":["agent_id","requested_capabilities"],"title":"NegotiateRequest"},"OrderLeg":{"properties":{"symbol":{"type":"string","title":"Symbol"},"asset_type":{"$ref":"#/components/schemas/AssetType","default":"EQUITY"},"instruction":{"$ref":"#/components/schemas/Instruction"},"quantity":{"type":"number","title":"Quantity"},"limit_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Limit Price"},"underlying_symbol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Underlying Symbol"},"put_call":{"anyOf":[{"$ref":"#/components/schemas/PutCall"},{"type":"null"}]},"strike_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Strike Price"},"expiration_epoch_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expiration Epoch Ms"},"cusip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cusip"},"root_symbol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Root Symbol"},"multiplier":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Multiplier"}},"type":"object","required":["symbol","instruction","quantity"],"title":"OrderLeg","description":"One leg of the proposed order."},"PositionSnapshot":{"properties":{"symbol":{"type":"string","title":"Symbol"},"asset_type":{"$ref":"#/components/schemas/AssetType","default":"EQUITY"},"quantity":{"type":"number","title":"Quantity","description":"Positive=long, negative=short"},"average_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Price"},"market_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Market Value"},"underlying_symbol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Underlying Symbol"},"put_call":{"anyOf":[{"$ref":"#/components/schemas/PutCall"},{"type":"null"}]},"strike_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Strike Price"},"expiration_epoch_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expiration Epoch Ms"},"cusip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cusip"},"root_symbol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Root Symbol"},"multiplier":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Multiplier"}},"type":"object","required":["symbol","quantity"],"title":"PositionSnapshot","description":"An existing position in the account."},"PutCall":{"type":"string","enum":["PUT","CALL"],"title":"PutCall"},"RevokeRequest":{"properties":{"agent_id":{"type":"string","title":"Agent Id"},"broker":{"type":"string","title":"Broker"}},"type":"object","required":["agent_id","broker"],"title":"RevokeRequest"},"StatusResponse":{"properties":{"connected":{"type":"boolean","title":"Connected"},"expired":{"type":"boolean","title":"Expired"},"saved_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Saved At"}},"type":"object","required":["connected","expired"],"title":"StatusResponse"},"TokenRequest":{"properties":{"code":{"type":"string","title":"Code"},"client_id":{"type":"string","title":"Client Id"},"client_secret":{"type":"string","title":"Client Secret"}},"type":"object","required":["code","client_id","client_secret"],"title":"TokenRequest"},"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"}}}}