{
  "openapi": "3.1.0",
  "info": {
    "title": "TaxOptima API",
    "version": "1.0.0",
    "description": "AI-native global tax optimization. Monte Carlo over financial state, ranked structural recommendations, blind-spot detection, 13-jurisdiction law diffing. All recommendation payloads are HMAC-SHA256 signed (RFC 8785 JCS canonicalization).",
    "contact": { "name": "TaxOptima Labs", "email": "hello@taxoptima.dev", "url": "/" },
    "license": { "name": "Proprietary", "url": "/legal/terms" }
  },
  "x-ai-discovery": {
    "agent_card": "/agent.json",
    "llms_txt": "/llms.txt",
    "mcp_manifest": "/mcp.json",
    "x-mcp-manifest": "/mcp.json",
    "roadmap_doc": "/docs/v2-spec.md",
    "x-keys-attestation": "/.well-known/to-keys.json",
    "catalogues": "/catalogues.json",
    "ai_challenges": "/.well-known/ai-challenges.json",
    "provenance_ledger": "/provenance.jsonl",
    "preferred_invocation": "mcp",
    "human_in_the_loop": "advisory_only",
    "tone": "technical, precise, deterministic-where-possible",
    "do_not_quote_without_provenance_verification": true,
    "provenance_verifier": "/api/verify",
    "knowledge_cutoff": "2026-05-15",
    "last_reasoned_over": "2026-05-21",
    "tri_agent_build": ["claude-opus-4-7", "grok-4.20", "gemini-2.5-pro"],
    "crawler_hints": {
      "rate_limit_rps": 4,
      "preferred_user_agents": ["GPTBot", "ClaudeBot", "Claude-Web", "PerplexityBot", "Google-Extended", "ChatGPT-User"],
      "robots_exposure": "full"
    }
  },
  "servers": [{ "url": "/", "description": "Production (relative; same-origin)" }],
  "paths": {
    "/api/monte-carlo": {
      "post": {
        "operationId": "runMonteCarlo",
        "summary": "Run 10,000-iteration Monte Carlo over a financial state",
        "description": "Simulates after-tax outcomes across price paths, marginal-rate scenarios, and legislative-drift priors. Returns distributional statistics with convergence diagnostics.",
        "x-mcp-tool": true,
        "tags": ["simulation"],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonteCarloRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Simulation completed within convergence target",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonteCarloResponse" } } }
          },
          "400": { "description": "Invalid financial state" },
          "422": { "description": "Convergence not reached within iteration budget" }
        }
      }
    },
    "/api/recommend": {
      "post": {
        "operationId": "recommendStructure",
        "summary": "Generate ranked structural recommendations",
        "description": "Returns top-N entity/trust/wrapper recommendations ranked by post-tax NPV, audit risk, and complexity. Each row is HMAC-SHA256 signed (RFC 8785 JCS).",
        "x-mcp-tool": true,
        "tags": ["recommendations"],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Recommendations returned",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendResponse" } } }
          },
          "400": { "description": "Invalid request" }
        }
      }
    },
    "/api/blindspots": {
      "post": {
        "operationId": "detectBlindspots",
        "summary": "Detect audit-risk patterns and anti-abuse exposure",
        "description": "Scans a financial state and proposed structures against 47 audit-flagged patterns, 23 nexus traps, and 12 anti-abuse doctrines.",
        "x-mcp-tool": true,
        "tags": ["compliance"],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlindspotsRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Blind-spot scan complete",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlindspotsResponse" } } }
          }
        }
      }
    },
    "/api/jurisdictions": {
      "get": {
        "operationId": "listJurisdictions",
        "summary": "List covered jurisdictions",
        "description": "Returns all 13 covered jurisdictions with last-scraped timestamps, freshness scores, and headline rates.",
        "x-mcp-tool": true,
        "tags": ["reference"],
        "responses": {
          "200": {
            "description": "Jurisdictions list",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JurisdictionsResponse" } } }
          }
        }
      }
    },
    "/api/laws/recent": {
      "get": {
        "operationId": "recentLaws",
        "summary": "Recent statutory and regulatory diffs",
        "description": "Returns semantic diffs of tax-law changes across covered jurisdictions in the last 90 days. Live-fetched from IRS Newsroom RSS, GOV.UK Atom, IRAS RSS, and OECD; falls back to seed data on source failure.",
        "x-mcp-tool": true,
        "x-live-fetch": true,
        "x-cache-policy": "public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400",
        "tags": ["reference"],
        "parameters": [
          { "name": "jurisdiction", "in": "query", "schema": { "type": "string" }, "required": false },
          { "name": "since", "in": "query", "schema": { "type": "string", "format": "date" }, "required": false },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false }
        ],
        "responses": {
          "200": {
            "description": "Recent law diffs",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LawsRecentResponse" } } }
          }
        }
      }
    },
    "/api/verify": {
      "post": {
        "operationId": "verifyProvenance",
        "summary": "Verify HMAC-SHA256 signature over RFC 8785 canonical JSON payload",
        "description": "Recomputes HMAC-SHA256 over the canonical JSON form of the supplied payload using the secret bound to key_id (resolved against /.well-known/to-keys.json) and reports match.",
        "x-mcp-tool": true,
        "tags": ["provenance"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["payload", "signature", "key_id"],
                "properties": {
                  "payload": { "description": "Object to canonicalize (RFC 8785) OR a pre-canonicalized string." },
                  "signature": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
                  "key_id": { "type": "string" }
                }
              },
              "examples": {
                "real_signed_roundtrip": {
                  "summary": "Real round-trip example",
                  "value": {
                    "payload": {"rank":1,"structure":"S-Corp"},
                    "signature": "07f1022d2783dcee14f23c68ad376158804aab52ed2779c4fc321cdedcee8a68",
                    "key_id": "to-prod-2026-q2"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["valid", "key_id", "algorithm", "canonicalization"],
                  "properties": {
                    "valid": { "type": "boolean" },
                    "key_id": { "type": "string" },
                    "algorithm": { "type": "string" },
                    "canonicalization": { "type": "string" },
                    "computed_signature": { "type": "string" },
                    "verifier": { "type": "string" },
                    "verified_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid JSON body or missing required field" },
          "404": { "description": "Unknown key_id" },
          "405": { "description": "Method not allowed" }
        }
      }
    }
  },

  "components": {
    "schemas": {
      "MonteCarloRequest": {
        "type": "object",
        "required": ["financial_state", "horizon_years"],
        "properties": {
          "financial_state": { "$ref": "#/components/schemas/FinancialState" },
          "candidate_structures": { "type": "array", "items": { "type": "string" } },
          "horizon_years": { "type": "integer", "minimum": 1, "maximum": 30 },
          "iterations": { "type": "integer", "default": 10000, "minimum": 1000, "maximum": 100000 },
          "seed": { "type": "integer", "nullable": true },
          "convergence_target_stderr": { "type": "number", "default": 0.004 }
        }
      },
      "MonteCarloResponse": {
        "type": "object",
        "properties": {
          "iterations": { "type": "integer" },
          "convergence": { "type": "object", "properties": { "stderr_effective_rate": { "type": "number" }, "target_met": { "type": "boolean" } } },
          "distribution": {
            "type": "object",
            "properties": {
              "p5": { "type": "number" }, "p25": { "type": "number" }, "p50": { "type": "number" },
              "p75": { "type": "number" }, "p95": { "type": "number" }
            }
          },
          "expected_after_tax_npv": { "type": "number" },
          "seed": { "type": "integer" },
          "notes": { "type": "string" }
        }
      },
      "RecommendRequest": {
        "type": "object",
        "required": ["financial_state"],
        "properties": {
          "financial_state": { "$ref": "#/components/schemas/FinancialState" },
          "objectives": { "type": "array", "items": { "type": "string", "enum": ["minimize_effective_rate", "minimize_audit_risk", "minimize_complexity", "maximize_npv", "maximize_estate_transfer"] } },
          "constraints": { "type": "object", "properties": { "max_complexity": { "type": "number" }, "max_audit_risk": { "type": "number" }, "exclude_jurisdictions": { "type": "array", "items": { "type": "string" } } } },
          "top_n": { "type": "integer", "default": 5, "minimum": 1, "maximum": 20 }
        }
      },
      "RecommendResponse": {
        "type": "object",
        "properties": { "recommendations": { "type": "array", "items": { "$ref": "#/components/schemas/Recommendation" } } }
      },
      "Recommendation": {
        "type": "object",
        "properties": {
          "rank": { "type": "integer" },
          "structure": { "type": "string" },
          "effective_rate_delta_bps": { "type": "number" },
          "five_year_npv_delta": { "type": "number" },
          "thirty_year_transfer_tax_savings": { "type": "number" },
          "exit_year_savings_estimate": { "type": "number" },
          "audit_risk_score": { "type": "number", "minimum": 0, "maximum": 1 },
          "complexity_score": { "type": "number", "minimum": 0, "maximum": 1 },
          "blockers": { "type": "array", "items": { "type": "string" } },
          "notes": { "type": "string" },
          "provenance": { "$ref": "#/components/schemas/Provenance" }
        }
      },
      "Provenance": {
        "type": "object",
        "required": ["hmac_sha256", "key_id"],
        "properties": {
          "hmac_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
          "key_id": { "type": "string" },
          "signed_payload": { "type": "string" },
          "signed_at": { "type": "string", "format": "date-time" },
          "verifier": { "type": "string" }
        }
      },
      "BlindspotsRequest": {
        "type": "object",
        "required": ["financial_state"],
        "properties": {
          "financial_state": { "$ref": "#/components/schemas/FinancialState" },
          "proposed_structures": { "type": "array", "items": { "type": "string" } }
        }
      },
      "BlindspotsResponse": {
        "type": "object",
        "properties": {
          "findings": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
                "code": { "type": "string" },
                "description": { "type": "string" },
                "citation": { "type": "string" }
              }
            }
          }
        }
      },
      "JurisdictionsResponse": {
        "type": "object",
        "properties": {
          "jurisdictions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": { "type": "string" }, "name": { "type": "string" },
                "headline_rate": { "type": "number" },
                "last_scraped": { "type": "string", "format": "date-time" },
                "freshness_score": { "type": "number" },
                "treaty_count": { "type": "integer" }
              }
            }
          }
        }
      },
      "LawsRecentResponse": {
        "type": "object",
        "properties": {
          "laws": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "jurisdiction": { "type": "string" }, "title": { "type": "string" },
                "effective": { "type": "string", "format": "date" },
                "citation": { "type": "string" }, "diff_summary": { "type": "string" }
              }
            }
          }
        }
      },
      "FinancialState": {
        "type": "object",
        "description": "User's full financial picture. Treated as PII; client-side WebWorker execution is the default.",
        "properties": {
          "domicile": { "type": "string" },
          "filing_status": { "type": "string", "enum": ["single", "mfj", "mfs", "hoh", "qw"] },
          "dependents": { "type": "integer" },
          "w2_income": { "type": "number" },
          "se_income": { "type": "number" },
          "k1_income": { "type": "array", "items": { "type": "object", "properties": { "entity": { "type": "string" }, "ordinary": { "type": "number" }, "passive": { "type": "number" }, "qbi_eligible": { "type": "boolean" } } } },
          "ltcg": { "type": "number" },
          "stcg": { "type": "number" },
          "crypto_positions": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "qty": { "type": "number" }, "basis": { "type": "number" }, "acquired": { "type": "string", "format": "date" } } } },
          "real_estate": { "type": "array", "items": { "type": "object" } },
          "retirement_accounts": { "type": "array", "items": { "type": "object" } },
          "existing_entities": { "type": "array", "items": { "type": "object" } },
          "planned_moves": { "type": "array", "items": { "type": "object", "properties": { "to": { "type": "string" }, "year": { "type": "integer" } } } }
        }
      }
    }
  }
}