openapi: 3.1.0
info:
  title: SEC EDGAR MCP (x402)
  version: 0.1.0
  description: |
    Pay-per-call x402 endpoints for SEC EDGAR. Full-text search, by-CIK
    filing history, and primary-document text fetch across every public-company
    filing since 1993. No signup, no API key — pay USDC on Base. Each first
    call returns HTTP 402 with an x402 envelope; sign X-PAYMENT and retry.
  contact:
    name: 
    url: 
    email: hello@
servers:
  - url: https://edgar-mcp.mtree.workers.dev
x-pricing:
  - path: /v1/filings/search
    method: POST
    price: $0.04
    amount: "0.04"
    asset: USDC
    network: base
  - path: /v1/filings/by_cik
    method: POST
    price: $0.05
    amount: "0.05"
    asset: USDC
    network: base
  - path: /v1/filings/full_text
    method: POST
    price: $0.10
    amount: "0.10"
    asset: USDC
    network: base
paths:
  /v1/filings/search:
    post:
      operationId: filingsSearch
      summary: Full-text search across SEC EDGAR filings
      description: |
        $0.04/call. Search every EDGAR filing since 1993 by free-text query,
        form type, CIKs, and date range.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                query:
                  type: string
                  description: Free-text query (optional if forms or ciks supplied)
                  example: artificial intelligence risk factors
                forms:
                  type: string
                  description: Comma-separated form types
                  example: "10-K,10-Q"
                ciks:
                  type: string
                  description: Comma-separated CIKs (digits or zero-padded)
                  example: "0000320193"
                fromDays:
                  type: number
                  description: Look back N days (1–3650)
                  example: 365
                startDate:
                  type: string
                  description: Start date YYYY-MM-DD (overrides fromDays)
                  example: "2024-01-01"
                endDate:
                  type: string
                  description: End date YYYY-MM-DD
                  example: "2024-12-31"
                limit:
                  type: number
                  description: Max results (1–50)
                  example: 25
      responses:
        "200":
          description: Search results
        "402":
          description: x402 payment required
        "502":
          description: SEC upstream error
  /v1/filings/by_cik:
    post:
      operationId: filingsByCik
      summary: Recent filing history for a company by CIK
      description: |
        $0.05/call. Returns up to 50 most recent filings for a CIK with form,
        filing date, accession number, and primary-document URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [cik]
              properties:
                cik:
                  type: string
                  description: Company CIK (digits or zero-padded)
                  example: "320193"
                forms:
                  type: string
                  description: Comma-separated form filter (optional)
                  example: "10-K,10-Q,8-K"
                limit:
                  type: number
                  description: Max results (1–50)
                  example: 25
      responses:
        "200":
          description: Filing history
        "402":
          description: x402 payment required
        "404":
          description: CIK not found
        "502":
          description: SEC upstream error
  /v1/filings/full_text:
    post:
      operationId: filingsFullText
      summary: De-tagged primary-document text for a filing
      description: |
        $0.10/call. Fetch the primary document of a specific filing and
        return de-tagged text content (truncated to maxChars). Pass cik +
        accession; primaryDocument is auto-resolved if omitted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [cik, accession]
              properties:
                cik:
                  type: string
                  description: Company CIK
                  example: "320193"
                accession:
                  type: string
                  description: Accession number with dashes
                  example: "0000320193-25-000073"
                primaryDocument:
                  type: string
                  description: Primary document filename (optional — auto-resolved)
                  example: "aapl-20250628.htm"
                maxChars:
                  type: number
                  description: Maximum characters to return (1000–120000)
                  example: 20000
      responses:
        "200":
          description: De-tagged document text
        "402":
          description: x402 payment required
        "404":
          description: Filing or primary document not found
        "502":
          description: SEC upstream error
components:
  securitySchemes:
    x402:
      type: http
      scheme: x402
      description: |
        Pay-per-call via x402 (USDC on Base). On first request, the API returns
        HTTP 402 with an "accepts" array. Sign and submit X-PAYMENT to retry.
security:
  - x402: []
