{"openapi":"3.0.3","info":{"title":"IRL Engine","description":"Cryptographic pre-execution compliance gateway for AI trading agents. Seals reasoning traces with SHA-256 proof before orders reach the exchange.","contact":{"name":"IRL Engine","url":"https://github.com/GabrielGauss/irl-engine"},"license":{"name":"BSL 1.1","url":"https://mariadb.com/bsl11/"},"version":"1.1.0"},"paths":{"/irl/admin/audit-log":{"get":{"tags":["Admin"],"operationId":"audit_log_query","parameters":[{"name":"action","in":"query","description":"Filter by action type","required":false,"schema":{"type":"string","nullable":true}},{"name":"target_id","in":"query","description":"Filter by target UUID","required":false,"schema":{"type":"string","nullable":true}},{"name":"from","in":"query","description":"ISO 8601 start datetime","required":false,"schema":{"type":"string","nullable":true}},{"name":"to","in":"query","description":"ISO 8601 end datetime","required":false,"schema":{"type":"string","nullable":true}},{"name":"before_id","in":"query","description":"Cursor (UUID of last seen entry)","required":false,"schema":{"type":"string","nullable":true}},{"name":"limit","in":"query","description":"Max results (default 100, max 1000)","required":false,"schema":{"type":"integer","format":"int64","nullable":true}}],"responses":{"200":{"description":"Audit log entries"}},"security":[{"bearer_token":[]}]}},"/irl/admin/gdpr-erase/{agent_id}":{"post":{"tags":["Admin"],"operationId":"gdpr_erase_handler","parameters":[{"name":"agent_id","in":"path","description":"Agent UUID to erase","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Erasure complete"},"412":{"description":"KMS_PROVIDER not configured"}},"security":[{"bearer_token":[]}]}},"/irl/admin/shadow-mode":{"get":{"tags":["Admin"],"operationId":"shadow_mode_get","responses":{"200":{"description":"Current shadow mode state"}},"security":[{"bearer_token":[]}]},"post":{"tags":["Admin"],"operationId":"shadow_mode_set","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShadowModeRequest"}}},"required":true},"responses":{"200":{"description":"Shadow mode updated"}},"security":[{"bearer_token":[]}]}},"/irl/admin/tokens":{"post":{"tags":["Admin"],"operationId":"token_issue","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenIssueRequest"}}},"required":true},"responses":{"200":{"description":"Token issued — save immediately, not stored server-side"}},"security":[{"bearer_token":[]}]}},"/irl/admin/tokens/{token_id}":{"delete":{"tags":["Admin"],"operationId":"token_revoke","parameters":[{"name":"token_id","in":"path","description":"Token UUID to revoke","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Token revoked"},"404":{"description":"Token not found"}},"security":[{"bearer_token":[]}]}},"/irl/authorize":{"post":{"tags":["Core"],"operationId":"authorize","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizeRequest"}}},"required":true},"responses":{"200":{"description":"Authorized — reasoning_hash issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizeResponse"}}}},"403":{"description":"Policy violation or mTLS CN mismatch"},"422":{"description":"Validation error"}},"security":[{"bearer_token":[]}]}},"/irl/bind-execution":{"post":{"tags":["Core"],"operationId":"bind_execution","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindExecutionRequest"}}},"required":true},"responses":{"200":{"description":"Bound — final_proof computed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindExecutionResult"}}}},"404":{"description":"Trace not found"},"409":{"description":"Trace already bound"},"422":{"description":"Validation error"}},"security":[{"bearer_token":[]}]}},"/irl/health":{"get":{"tags":["Operations"],"operationId":"health","responses":{"200":{"description":"Engine healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"Engine not ready"}}}},"/irl/orphans":{"get":{"tags":["Traces"],"operationId":"get_orphans","responses":{"200":{"description":"DIVERGENT and EXPIRED traces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceListResponse"}}}}},"security":[{"bearer_token":[]}]}},"/irl/pending":{"get":{"tags":["Traces"],"operationId":"get_pending","parameters":[{"name":"age_seconds","in":"query","description":"Only return traces older than this many seconds (default 3600)","required":false,"schema":{"type":"integer","format":"int64","nullable":true}}],"responses":{"200":{"description":"Stale PENDING traces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceListResponse"}}}}},"security":[{"bearer_token":[]}]}},"/irl/shadow-violations":{"get":{"tags":["Operations"],"operationId":"get_shadow_violations","responses":{"200":{"description":"SHADOW_HALTED traces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceListResponse"}}}}},"security":[{"bearer_token":[]}]}},"/irl/trace/{trace_id}":{"get":{"tags":["Traces"],"operationId":"get_trace","parameters":[{"name":"trace_id","in":"path","description":"UUID of the reasoning trace","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Reasoning_Trace_v1","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasoningTrace"}}}},"404":{"description":"Trace not found"}},"security":[{"bearer_token":[]}]}},"/irl/traces":{"get":{"tags":["Traces"],"operationId":"list_traces","parameters":[{"name":"agent_id","in":"query","description":"Filter by agent UUID","required":false,"schema":{"type":"string","nullable":true}},{"name":"from","in":"query","description":"Start of time range (Unix ms)","required":false,"schema":{"type":"integer","format":"int64","nullable":true}},{"name":"to","in":"query","description":"End of time range (Unix ms)","required":false,"schema":{"type":"integer","format":"int64","nullable":true}},{"name":"status","in":"query","description":"PENDING|MATCHED|DIVERGENT|ORPHAN|EXPIRED|SHADOW_HALTED","required":false,"schema":{"type":"string","nullable":true}},{"name":"limit","in":"query","description":"Max results (default 500, max 5000)","required":false,"schema":{"type":"integer","format":"int64","nullable":true}}],"responses":{"200":{"description":"Filtered trace list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceListResponse"}}}}},"security":[{"bearer_token":[]}]}}},"components":{"schemas":{"AgentBlock":{"type":"object","required":["agent_id","latent_fingerprint","feature_schema_id"],"properties":{"agent_id":{"type":"string","format":"uuid"},"feature_schema_id":{"type":"string"},"latent_fingerprint":{"type":"string"}}},"AuthorizeRequest":{"type":"object","description":"The request body sent by an agent to POST /irl/authorize.","required":["agent_id","model_hash_hex","model_id","prompt_version","feature_schema_id","hyperparameter_checksum","action","asset","order_type","venue_id","quantity","notional","client_order_id","agent_valid_time"],"properties":{"action":{"$ref":"#/components/schemas/TradeAction"},"agent_id":{"type":"string","format":"uuid","description":"Registered agent identity (UUID from POST /irl/agents)."},"agent_valid_time":{"type":"integer","format":"int64","description":"Unix ms: the timestamp of the MTA regime the agent used."},"asset":{"type":"string"},"client_order_id":{"type":"string"},"feature_schema_id":{"type":"string"},"heartbeat":{"allOf":[{"$ref":"#/components/schemas/SignedHeartbeat"}],"nullable":true},"hyperparameter_checksum":{"type":"string","description":"Checksum of hyperparameters — 4th component of L_t fingerprint."},"limit_price":{"type":"number","format":"double","nullable":true},"model_hash_hex":{"type":"string","description":"Hex-encoded SHA-256 of the running model version + config — verified against MAR."},"model_id":{"type":"string"},"multiplier":{"type":"number","format":"double","description":"Contract multiplier. Defaults to 1.0 if not provided."},"notional":{"type":"number","format":"double"},"notional_currency":{"type":"string","description":"ISO 4217 currency of the notional. Defaults to \"USD\" if not provided."},"order_type":{"$ref":"#/components/schemas/OrderType"},"prompt_version":{"type":"string"},"quantity":{"type":"number","format":"double"},"reduce_only":{"type":"boolean","description":"When true, this order is reducing an existing position (not opening a new one).\nThe `allowed_sides` regime constraint is bypassed — a trader must be able to\nexit positions even during a kill-switch regime. Notional cap still applies.\nThe agent asserts reduce-only intent; IRL seals and audits the claim."},"regulatory":{"allOf":[{"$ref":"#/components/schemas/RegulatoryBlock"}],"nullable":true},"stop_price":{"type":"number","format":"double","nullable":true},"venue_id":{"type":"string"}}},"AuthorizeResponse":{"type":"object","description":"Response for POST /irl/authorize.","required":["trace_id","reasoning_hash","authorized","shadow_blocked"],"properties":{"authorized":{"type":"boolean"},"reasoning_hash":{"type":"string"},"shadow_blocked":{"type":"boolean"},"trace_id":{"type":"string","format":"uuid"}}},"BiTemporalBlock":{"type":"object","required":["valid_time","txn_time","time_source"],"properties":{"time_source":{"type":"string"},"txn_time":{"type":"string","format":"date-time"},"valid_time":{"type":"string","format":"date-time"}}},"BindExecutionRequest":{"type":"object","description":"Request body for POST /irl/bind-execution.\nCalled by the agent after receiving the exchange confirmation.","required":["trace_id","exchange_tx_id","execution_status"],"properties":{"asset":{"type":"string","description":"Asset actually traded (for mismatch detection).","nullable":true},"exchange_tx_id":{"type":"string"},"executed_quantity":{"type":"number","format":"double","description":"Quantity actually executed (for tolerance check).","nullable":true},"executed_side":{"type":"string","description":"Trade direction as reported by the exchange: \"Long\" or \"Short\".\nOptional — if provided, verified against the authorized intent to detect\nside mismatches (e.g. Long authorized but Short executed). Omit if the\nexchange does not return direction in the fill report.","nullable":true},"execution_price":{"type":"number","format":"double","description":"Execution price at the exchange (for forensic PnL correlation).","nullable":true},"execution_status":{"$ref":"#/components/schemas/ExecutionStatus"},"execution_time_ms":{"type":"integer","format":"int64","description":"Unix milliseconds of the actual exchange fill.\nOptional — if provided, stored as execution_time for accurate PnL timestamps.\nDefaults to IRL wall clock at bind time if not supplied.","nullable":true},"trace_id":{"type":"string","format":"uuid"}}},"BindExecutionResult":{"type":"object","description":"The result of binding a reasoning trace to an exchange execution.","required":["trace_id","final_proof","verification_status","execution_status","execution_time"],"properties":{"divergence_reason":{"type":"string","description":"Non-None when verification_status is Divergent — explains what differed.","nullable":true},"execution_status":{"type":"string"},"execution_time":{"type":"string","format":"date-time"},"final_proof":{"type":"string","description":"SHA-256(reasoning_hash || \"||\" || exchange_tx_id).\nThis is the terminal proof that closes the chain:\nAgent Reasoning → IRL Snapshot → Exchange Order"},"trace_id":{"type":"string","format":"uuid"},"verification_status":{"$ref":"#/components/schemas/VerificationStatus"}}},"ExecutionBlock":{"type":"object","required":["action","asset","order_type","venue_id","quantity","notional","notional_currency","multiplier","client_order_id"],"properties":{"action":{"type":"string"},"asset":{"type":"string"},"client_order_id":{"type":"string"},"limit_price":{"type":"number","format":"double","nullable":true},"multiplier":{"type":"number","format":"double"},"notional":{"type":"number","format":"double"},"notional_currency":{"type":"string"},"order_type":{"type":"string"},"quantity":{"type":"number","format":"double"},"stop_price":{"type":"number","format":"double","nullable":true},"venue_id":{"type":"string"}}},"HealthResponse":{"type":"object","required":["status","db_ok"],"properties":{"cert_expiry_status":{"type":"string","nullable":true},"db_ok":{"type":"boolean"},"status":{"type":"string"}}},"HeartbeatBlock":{"type":"object","required":["sequence_id","signature_valid","drift_ms"],"properties":{"drift_ms":{"type":"integer","format":"int64"},"sequence_id":{"type":"integer","format":"int64","minimum":0},"signature_valid":{"type":"boolean"}}},"IntegrityBlock":{"type":"object","required":["reasoning_hash","verification_status"],"properties":{"execution_status":{"type":"string","nullable":true},"final_proof":{"type":"string","nullable":true},"reasoning_hash":{"type":"string"},"verification_status":{"type":"string"}}},"MtaBlock":{"type":"object","required":["regime_id","regime_label","risk_level","max_notional_scale","allowed_sides","version","hash","signature_valid"],"properties":{"allowed_sides":{"type":"array","items":{"type":"string"},"description":"Trade directions that were permitted."},"hash":{"type":"string"},"max_notional_scale":{"type":"number","format":"double","description":"Regime-level notional multiplier that was in effect."},"regime_id":{"type":"integer","format":"int32","minimum":0},"regime_label":{"type":"string"},"risk_level":{"type":"number","format":"double","description":"Normalized risk level at time of decision (0.0–1.0)."},"signature_valid":{"type":"boolean"},"version":{"type":"string"}}},"PolicyBlock":{"type":"object","required":["id","version","hash","result"],"properties":{"hash":{"type":"string"},"id":{"type":"string"},"result":{"type":"string"},"version":{"type":"string"}}},"ReasoningTrace":{"type":"object","description":"The full Reasoning_Trace_v1 object returned to callers and stored in DB.","required":["trace_id","version","bitemporal","mta","agent","execution","heartbeat","policy","integrity"],"properties":{"agent":{"$ref":"#/components/schemas/AgentBlock"},"bitemporal":{"$ref":"#/components/schemas/BiTemporalBlock"},"execution":{"$ref":"#/components/schemas/ExecutionBlock"},"heartbeat":{"$ref":"#/components/schemas/HeartbeatBlock"},"integrity":{"$ref":"#/components/schemas/IntegrityBlock"},"mta":{"$ref":"#/components/schemas/MtaBlock"},"policy":{"$ref":"#/components/schemas/PolicyBlock"},"regulatory":{"allOf":[{"$ref":"#/components/schemas/RegulatoryBlock"}],"nullable":true},"trace_id":{"type":"string","format":"uuid"},"version":{"type":"string"}}},"RegulatoryBlock":{"type":"object","description":"Optional regulatory metadata — included when the agent operates under a\nreporting regime that requires structured fields in the audit trace.\n\nAll fields are optional. The block itself is absent (`None`) when no\nregulatory context is provided by the agent.\n\nMiFID II (EU): algorithmic trading identifier + decision-maker identity.\nCFTC (US): Commodity Trading Advisor Code + special account code.\nSEC/FINRA: optional order-tracking reference number (CAT NMS).\n\nIRL seals and persists whatever the agent supplies — it does not validate\nagainst any external regulatory schema. Compliance teams are responsible\nfor verifying that the values satisfy their specific reporting obligations.","properties":{"cat_order_id":{"type":"string","description":"SEC CAT NMS: Consolidated Audit Trail order-tracking reference number.","nullable":true},"cftc_account_type":{"type":"string","description":"CFTC: special account type designator (e.g. \"H\" = hedge, \"S\" = speculator).","nullable":true},"cftc_cti_code":{"type":"string","description":"CFTC: Commodity Trading Advisor (CTA) code for the account.","nullable":true},"jurisdiction":{"type":"string","description":"Free-form jurisdiction tag (e.g. \"EU\", \"US\", \"UK\", \"APAC\").\nAllows downstream compliance tooling to route the trace for the right rulebook.","nullable":true},"mifid_algo_id":{"type":"string","description":"MiFID II Annex I Table 2: algorithm identifier assigned by the firm.\nRequired for algorithmic orders under Art. 17 of MiFID II.","nullable":true},"mifid_decision_maker":{"type":"string","description":"MiFID II: identifier of the person or system that made the investment decision.","nullable":true}}},"ShadowModeRequest":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"},"reason":{"type":"string","nullable":true}}},"SignedHeartbeat":{"type":"object","description":"A signed pulse from MacroPulse, broadcast every ~100ms.\nActs as an anti-replay anchor: proves the agent used a fresh, authentic regime.\n\n§9.2: signature is Ed25519 over (seq_id || timestamp || regime_id || mta_ref)","required":["sequence_id","timestamp_ms","regime_id","signature"],"properties":{"mta_ref":{"type":"string","description":"Hex-encoded SHA-256 of the current MTA broadcast — binds heartbeat to a specific MTA state.\nMust match `MtaState.hash` for the regime the agent is acting on."},"regime_id":{"type":"integer","format":"int32","description":"The regime ID active at broadcast time (must match MTA response).","minimum":0},"sequence_id":{"type":"integer","format":"int64","description":"Monotonically increasing counter. Ensures no replay.","minimum":0},"signature":{"type":"string","format":"binary","description":"Ed25519 signature over: seq_id_be || timestamp_ms_be || regime_id || mta_ref_bytes\nSigned by the MTA operator's private key. Verified against Config.mta_pubkey."},"timestamp_ms":{"type":"integer","format":"int64","description":"Unix ms when MacroPulse broadcast this heartbeat.","minimum":0}}},"TokenIssueRequest":{"type":"object","required":["client_name"],"properties":{"client_name":{"type":"string"}}},"TraceListResponse":{"type":"object","required":["count","traces"],"properties":{"count":{"type":"integer","format":"int64"},"traces":{"type":"array","items":{}}}},"VerificationStatus":{"type":"string","description":"Full lifecycle of a reasoning trace — whitepaper v3 §11.2.","enum":["Pending","Matched","Divergent","Orphan","Expired","Mismatch"]}},"securitySchemes":{"bearer_token":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"Core","description":"Core IRL workflow: authorize → bind-execution"},{"name":"Traces","description":"Trace inspection and filtering"},{"name":"Operations","description":"Health, metrics, shadow violations"},{"name":"Admin","description":"Owner-level admin — require owner token"}]}