{
  "openapi": "3.1.0",
  "info": {
    "title": "Margin of Insight API",
    "version": "1.0.0",
    "description": "Analyst-quality equity research for AI agents and LLMs. Pre-computed, structured JSON. Company primers free; fundamental analysis $1.00; full investment memos $2.00. US-listed SEC filers only.",
    "contact": {
      "url": "https://marginofinsight.com"
    },
    "x-llms-txt": "https://marginofinsight.com/llms.txt"
  },
  "servers": [
    {
      "url": "https://marginofinsight.com/api/v1",
      "description": "Production"
    }
  ],
  "x-api-status": "coming-soon",
  "x-coverage": "US-listed SEC filers only. Foreign private issuers and non-US listings are not supported.",
  "x-pricing": {
    "primer": { "price_usd": 0, "auth": false, "steps": 3 },
    "fundamental": { "price_usd": 1.00, "auth": true, "steps": 11 },
    "memo": { "price_usd": 2.00, "auth": true, "steps": 19 }
  },
  "security": [
    { "ApiKeyAuth": [] }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key obtained from marginofinsight.com/account. Not required for free-tier endpoints."
      },
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Payment",
        "description": "Autonomous agent payment via x402 protocol (HTTP 402 + USDC on Base). Call the endpoint without auth; server returns 402 with payment terms; sign and retry."
      }
    },
    "schemas": {
      "ResponseEnvelope": {
        "type": "object",
        "required": ["ticker", "company", "exchange", "report_type", "tier", "generated_at", "coverage_as_of", "freshness_days", "data", "metadata"],
        "properties": {
          "ticker": { "type": "string", "example": "AAPL", "description": "Uppercase ticker symbol" },
          "company": { "type": "string", "example": "Apple Inc." },
          "exchange": { "type": "string", "example": "NASDAQ" },
          "report_type": { "type": "string", "enum": ["primer", "fundamental", "memo"] },
          "tier": { "type": "string", "enum": ["free", "fundamental", "full"] },
          "generated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when this report was generated" },
          "coverage_as_of": { "type": "string", "example": "2025-Q4", "description": "Most recent quarter reflected in the research" },
          "freshness_days": { "type": "integer", "example": 12, "description": "Days since report was generated" },
          "steps_included": { "type": "array", "items": { "type": "integer" }, "example": [1, 2, 3] },
          "data": { "$ref": "#/components/schemas/ResearchData" },
          "metadata": { "$ref": "#/components/schemas/ResponseMetadata" }
        }
      },
      "ResearchData": {
        "type": "object",
        "description": "Research content. Fields present depend on tier requested.",
        "properties": {
          "overview": {
            "type": "object",
            "description": "Step 1 — Business Overview",
            "properties": {
              "description": { "type": "string" },
              "sector": { "type": "string" },
              "industry": { "type": "string" },
              "exchange": { "type": "string" },
              "market_cap_usd": { "type": "number" },
              "employees": { "type": "integer" },
              "business_model": { "type": "string" },
              "revenue_model": { "type": "string" },
              "core_products": { "type": "array", "items": { "type": "string" } }
            }
          },
          "financial_snapshot": {
            "type": "object",
            "description": "Step 2 — Financial Snapshot",
            "properties": {
              "revenue_ttm": { "type": "number" },
              "net_income_ttm": { "type": "number" },
              "eps_ttm": { "type": "number" },
              "gross_margin_pct": { "type": "number" },
              "operating_margin_pct": { "type": "number" },
              "fcf_ttm": { "type": "number" },
              "pe_ratio": { "type": "number" },
              "ps_ratio": { "type": "number" },
              "ev_ebitda": { "type": "number" },
              "quarterly": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "period": { "type": "string", "example": "2025-Q4" },
                    "revenue": { "type": "number" },
                    "net_income": { "type": "number" },
                    "eps": { "type": "number" },
                    "yoy_revenue_growth_pct": { "type": "number" }
                  }
                }
              }
            }
          },
          "catalysts": {
            "type": "object",
            "description": "Step 3 — Recent Catalysts",
            "properties": {
              "recent": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "date": { "type": "string", "format": "date" },
                    "type": { "type": "string", "enum": ["earnings", "guidance", "news", "filing"] },
                    "summary": { "type": "string" },
                    "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] }
                  }
                }
              },
              "upcoming": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "date": { "type": "string", "format": "date" },
                    "event": { "type": "string" }
                  }
                }
              }
            }
          },
          "revenue_breakdown": {
            "type": "object",
            "description": "Step 4 — Revenue Breakdown ($1 tier and above)",
            "properties": {
              "segments": { "type": "array", "items": { "type": "object" } },
              "geographic": { "type": "array", "items": { "type": "object" } },
              "concentration_risk": { "type": "string" }
            }
          },
          "earnings_analysis": {
            "type": "object",
            "description": "Step 5 — Earnings Transcript Analysis ($1 tier and above)",
            "properties": {
              "quarters_analyzed": { "type": "array", "items": { "type": "string" } },
              "management_tone": { "type": "string", "enum": ["confident", "cautious", "mixed"] },
              "key_quotes": { "type": "array", "items": { "type": "string" } },
              "guidance_credibility": { "type": "string" },
              "analyst_pushback_themes": { "type": "array", "items": { "type": "string" } }
            }
          },
          "competitive_positioning": {
            "type": "object",
            "description": "Step 6 — Competitive Positioning ($1 tier and above)"
          },
          "financial_trends": {
            "type": "object",
            "description": "Step 7 — Financial Trends ($1 tier and above)"
          },
          "risk_register": {
            "type": "array",
            "description": "Step 8 — Risk Register ($1 tier and above)",
            "items": {
              "type": "object",
              "properties": {
                "risk": { "type": "string" },
                "severity": { "type": "string", "enum": ["high", "medium", "low"] },
                "likelihood": { "type": "string", "enum": ["high", "medium", "low"] },
                "source": { "type": "string" }
              }
            }
          },
          "balance_sheet": {
            "type": "object",
            "description": "Step 9 — Balance Sheet Health ($1 tier and above)"
          },
          "capital_allocation": {
            "type": "object",
            "description": "Step 10 — Capital Allocation ($1 tier and above)"
          },
          "industry_context": {
            "type": "object",
            "description": "Step 11 — Industry Context ($1 tier and above)"
          },
          "moat_analysis": {
            "type": "object",
            "description": "Step 12 — Moat Analysis ($2 tier only)"
          },
          "management_quality": {
            "type": "object",
            "description": "Step 13 — Management Quality ($2 tier only)"
          },
          "dcf_valuation": {
            "type": "object",
            "description": "Step 14 — DCF Valuation ($2 tier only)",
            "properties": {
              "implied_price": { "type": "number", "example": 198.40 },
              "current_price": { "type": "number", "example": 212.50 },
              "upside_pct": { "type": "number", "example": -6.6 },
              "wacc_pct": { "type": "number" },
              "terminal_growth_rate_pct": { "type": "number" },
              "assumptions": { "type": "object" }
            }
          },
          "comp_analysis": {
            "type": "object",
            "description": "Step 15 — Comparable Analysis ($2 tier only)"
          },
          "sensitivity_matrix": {
            "type": "object",
            "description": "Step 16 — Sensitivity Analysis ($2 tier only)",
            "properties": {
              "axes": {
                "type": "object",
                "properties": {
                  "x": { "type": "string", "description": "Variable on X axis, e.g. revenue growth rate" },
                  "y": { "type": "string", "description": "Variable on Y axis, e.g. terminal margin" }
                }
              },
              "matrix": {
                "type": "array",
                "description": "3x3 grid of implied prices",
                "items": { "type": "array", "items": { "type": "number" } }
              }
            }
          },
          "scenarios": {
            "type": "object",
            "description": "Step 17 — Scenario Analysis ($2 tier only)",
            "properties": {
              "bear": {
                "type": "object",
                "properties": {
                  "price_target": { "type": "number" },
                  "probability": { "type": "number" },
                  "thesis": { "type": "string" },
                  "catalysts": { "type": "array", "items": { "type": "string" } }
                }
              },
              "base": {
                "type": "object",
                "properties": {
                  "price_target": { "type": "number" },
                  "probability": { "type": "number" },
                  "thesis": { "type": "string" },
                  "catalysts": { "type": "array", "items": { "type": "string" } }
                }
              },
              "bull": {
                "type": "object",
                "properties": {
                  "price_target": { "type": "number" },
                  "probability": { "type": "number" },
                  "thesis": { "type": "string" },
                  "catalysts": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          },
          "investment_thesis": {
            "type": "string",
            "description": "Step 18 — 3-sentence investment thesis: company characterization, key assumption, primary risk ($2 tier only)",
            "example": "Apple is a mature platform business with exceptional capital return discipline. The thesis rests on services mix-shift sustaining margin expansion through the next cycle. Key risk: AI device transition disrupts the current upgrade cadence."
          },
          "structured_memo": {
            "type": "string",
            "description": "Step 19 — Full prose investment memo in Markdown, optimized for LLM downstream consumption ($2 tier only)"
          }
        }
      },
      "ResponseMetadata": {
        "type": "object",
        "properties": {
          "data_sources": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["SEC EDGAR XBRL", "earnings transcripts", "Tavily web search"]
          },
          "model": { "type": "string", "example": "claude-sonnet-4-6" },
          "steps_run": { "type": "integer", "example": 19 },
          "estimated_self_research_cost_usd": { "type": "number", "example": 8.50 },
          "api_version": { "type": "string", "example": "v1" }
        }
      },
      "CoverageTicker": {
        "type": "object",
        "required": ["ticker", "company", "exchange", "coverage_as_of", "freshness_days", "tiers_available"],
        "properties": {
          "ticker": { "type": "string", "example": "AAPL" },
          "company": { "type": "string", "example": "Apple Inc." },
          "exchange": { "type": "string", "example": "NASDAQ" },
          "sector": { "type": "string", "example": "Technology" },
          "coverage_as_of": { "type": "string", "example": "2025-Q4" },
          "freshness_days": { "type": "integer", "example": 12 },
          "tiers_available": {
            "type": "array",
            "items": { "type": "string", "enum": ["free", "fundamental", "full"] }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string", "example": "not_covered" },
          "message": { "type": "string" },
          "ticker": { "type": "string" },
          "request_url": { "type": "string" },
          "estimated_ready_hours": { "type": "integer" },
          "topup_url": { "type": "string" }
        }
      },
      "x402PaymentRequired": {
        "type": "object",
        "description": "Returned as HTTP 402 for autonomous agent payment flow",
        "properties": {
          "x402Version": { "type": "string", "example": "1" },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "scheme": { "type": "string", "example": "exact" },
                "network": { "type": "string", "example": "base" },
                "maxAmountRequired": { "type": "string", "example": "2000000", "description": "Amount in USDC base units (6 decimals)" },
                "asset": { "type": "string", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "description": "USDC contract on Base" },
                "payTo": { "type": "string", "description": "Payment destination address" },
                "memo": { "type": "string", "example": "AAPL memo" }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/research/{ticker}/primer": {
      "get": {
        "operationId": "getCompanyPrimer",
        "summary": "Get Company Primer",
        "x-agent-summary": "Free: returns business overview, financial snapshot, and recent catalysts for a US-listed ticker. No auth required.",
        "description": "Returns a 3-step company primer: business overview, financial snapshot (last 4 quarters), and recent catalysts including upcoming earnings. No authentication required.",
        "tags": ["Research"],
        "security": [],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "description": "Uppercase US exchange ticker symbol (e.g. AAPL, MSFT, NVDA)",
            "schema": { "type": "string", "example": "AAPL" }
          }
        ],
        "responses": {
          "200": {
            "description": "Company primer — free, no auth",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ResponseEnvelope" },
                "example": {
                  "ticker": "AAPL",
                  "company": "Apple Inc.",
                  "exchange": "NASDAQ",
                  "report_type": "primer",
                  "tier": "free",
                  "generated_at": "2026-04-28T09:14:22Z",
                  "coverage_as_of": "2025-Q4",
                  "freshness_days": 12,
                  "steps_included": [1, 2, 3],
                  "data": {
                    "overview": {
                      "description": "Apple Inc. designs and sells consumer electronics, software, and services.",
                      "sector": "Technology",
                      "market_cap_usd": 3200000000000
                    },
                    "financial_snapshot": {
                      "revenue_ttm": 391000000000,
                      "gross_margin_pct": 46.2,
                      "pe_ratio": 33.1
                    },
                    "catalysts": {
                      "recent": [],
                      "upcoming": [{ "date": "2026-05-01", "event": "Q2 FY2026 Earnings" }]
                    }
                  },
                  "metadata": {
                    "data_sources": ["SEC EDGAR XBRL", "earnings transcripts", "Tavily web search"],
                    "estimated_self_research_cost_usd": 0.50,
                    "api_version": "v1"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Ticker not covered",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": {
                  "error": "not_covered",
                  "ticker": "XYZ",
                  "message": "XYZ is not in the coverage universe.",
                  "request_url": "POST /api/v1/coverage/request",
                  "estimated_ready_hours": 24
                }
              }
            }
          }
        }
      }
    },
    "/research/{ticker}/fundamental": {
      "get": {
        "operationId": "getFundamentalAnalysis",
        "summary": "Get Fundamental Analysis",
        "x-agent-summary": "Paid ($1.00): returns 11-step fundamental analysis including earnings transcripts, competitive positioning, risk register, and balance sheet. API key required.",
        "description": "Returns an 11-step fundamental analysis. Deducts $1.00 from the authenticated user's credit balance. Includes all Company Primer content plus revenue breakdown, earnings transcript analysis, competitive positioning, financial trends, risk register, balance sheet health, capital allocation, and industry context.",
        "tags": ["Research"],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "example": "AAPL" }
          }
        ],
        "responses": {
          "200": {
            "description": "Fundamental analysis — $1.00 charged",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ResponseEnvelope" }
              }
            }
          },
          "402": {
            "description": "Payment required (x402 autonomous agent flow — coming soon)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/x402PaymentRequired" }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": { "error": "unauthorized", "message": "Valid API key required. Get one at https://marginofinsight.com/signup" }
              }
            }
          },
          "402 (insufficient_credits)": {
            "description": "Insufficient credit balance",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": { "error": "insufficient_credits", "message": "Balance $0.50, required $1.00", "topup_url": "https://marginofinsight.com/account" }
              }
            }
          },
          "404": {
            "description": "Ticker not covered",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/research/{ticker}/memo": {
      "get": {
        "operationId": "getInvestmentMemo",
        "summary": "Get Full Investment Memo",
        "x-agent-summary": "Paid ($2.00): returns complete 19-step investment memo including DCF valuation, moat analysis, scenario analysis, and a full prose memo. API key required. Equivalent research costs ~$7–9 to self-produce.",
        "description": "Returns a complete 19-step investment memo. Deducts $2.00 from the authenticated user's credit balance. Includes all Fundamental Analysis content plus moat analysis, management quality assessment, DCF valuation, comparable analysis, sensitivity matrix, scenario analysis (bear/base/bull), investment thesis, and a full prose memo in Markdown.",
        "tags": ["Research"],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "example": "AAPL" }
          }
        ],
        "responses": {
          "200": {
            "description": "Full investment memo — $2.00 charged",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ResponseEnvelope" }
              }
            }
          },
          "402": {
            "description": "Payment required (x402 autonomous agent flow — coming soon)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/x402PaymentRequired" }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "404": {
            "description": "Ticker not covered"
          }
        }
      }
    },
    "/coverage": {
      "get": {
        "operationId": "listCoverage",
        "summary": "List Coverage Universe",
        "x-agent-summary": "Free: returns all covered tickers with freshness timestamps. Use this to check availability before making a paid call.",
        "description": "Returns all covered tickers with coverage metadata. No authentication required. Use this to verify a ticker is covered before making a paid research call.",
        "tags": ["Coverage"],
        "security": [],
        "responses": {
          "200": {
            "description": "Coverage universe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": { "type": "integer", "example": 75 },
                    "tickers": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/CoverageTicker" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/coverage/{ticker}": {
      "get": {
        "operationId": "getCoverageMetadata",
        "summary": "Get Coverage Metadata",
        "x-agent-summary": "Free: check whether a specific ticker is covered and how fresh the research is.",
        "description": "Returns coverage metadata for a single ticker. No authentication required.",
        "tags": ["Coverage"],
        "security": [],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "example": "AAPL" }
          }
        ],
        "responses": {
          "200": {
            "description": "Coverage metadata",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CoverageTicker" }
              }
            }
          },
          "404": {
            "description": "Ticker not in coverage universe",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": { "error": "not_covered", "ticker": "XYZ", "request_url": "POST /api/v1/coverage/request", "estimated_ready_hours": 24 }
              }
            }
          }
        }
      }
    },
    "/coverage/request": {
      "post": {
        "operationId": "requestCoverage",
        "summary": "Request Coverage",
        "x-agent-summary": "Free: request research coverage for a ticker not yet in the universe. Fulfilled in 24–48 hours. No auth required.",
        "description": "Queue a coverage request for a US-listed company not yet covered. Free, no authentication required. Fulfilled in 24–48 hours. Optional email for notification when ready.",
        "tags": ["Coverage"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["ticker"],
                "properties": {
                  "ticker": { "type": "string", "example": "PLTR", "description": "Uppercase US exchange ticker symbol" },
                  "email": { "type": "string", "format": "email", "description": "Optional — receive email when coverage is ready" }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Coverage request accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ticker": { "type": "string", "example": "PLTR" },
                    "status": { "type": "string", "example": "queued" },
                    "estimated_ready_hours": { "type": "integer", "example": 24 },
                    "check_url": { "type": "string", "example": "https://marginofinsight.com/api/v1/coverage/PLTR" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/account/balance": {
      "get": {
        "operationId": "getAccountBalance",
        "summary": "Get Credit Balance",
        "x-agent-summary": "Returns the current credit balance for the authenticated API key.",
        "tags": ["Account"],
        "responses": {
          "200": {
            "description": "Current balance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "balance_usd": { "type": "number", "example": 8.00 },
                    "auto_topup_enabled": { "type": "boolean" },
                    "auto_topup_threshold_usd": { "type": "number", "example": 2.00 }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/account/usage": {
      "get": {
        "operationId": "getUsageHistory",
        "summary": "Get Usage History",
        "x-agent-summary": "Returns recent API call history and credit transactions for the authenticated key.",
        "tags": ["Account"],
        "responses": {
          "200": {
            "description": "Usage history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "transactions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "created_at": { "type": "string", "format": "date-time" },
                          "description": { "type": "string", "example": "AAPL memo -$2.00" },
                          "amount_usd": { "type": "number", "example": -2.00 },
                          "balance_after_usd": { "type": "number" },
                          "ticker": { "type": "string" },
                          "report_type": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Research",
      "description": "Equity research endpoints. Free primer requires no auth. Fundamental ($1) and memo ($2) require an API key or x402 payment."
    },
    {
      "name": "Coverage",
      "description": "Coverage universe management. All coverage endpoints are free and require no auth."
    },
    {
      "name": "Account",
      "description": "Credit balance and usage history. All account endpoints require an API key."
    }
  ]
}