openapi: "3.1.0"
info:
  title: lookup
  version: "0.1.0"
  description: "Pay-per-call legal (CourtListener) and financial (SEC EDGAR) data APIs for AI agents. Each call settles in USDC via x402; no API keys, no accounts, no subscriptions."
  contact:
    email: "contact@example.com"
servers:
  - url: "https://lookup.bustercall.workers.dev"
paths:
  /legal/cases/search:
    get:
      summary: "Search US federal and state court opinions by query, citation, party name, or judge"
      description: "Search US federal and state court opinions by query, citation, party name, or judge. Returns structured matches with snippets, citations, and dates."
      operationId: _legal_cases_search
      tags:
        - legal
        - case-law
        - research
        - litigation
      x-x402:
        price: $0.10
        network: base
        asset: USDC
      parameters:
        - name: q
            in: query
            required: true
            schema:
              type: string
            description: Free-text search query
        - name: court
            in: query
            required: false
            schema:
              type: string
            description: "Court ID filter (e.g. scotus, ca9)"
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, 1-50, default 20"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /legal/cases/get:
    get:
      summary: Fetch a single court opinion by CourtListener opinion ID
      description: "Fetch a single court opinion by CourtListener opinion ID. Returns full structured opinion text, parties, judges, dates, and citation list."
      operationId: _legal_cases_get
      tags:
        - legal
        - case-law
        - litigation
      x-x402:
        price: $0.05
        network: base
        asset: USDC
      parameters:
        - name: id
            in: query
            required: true
            schema:
              type: string
            description: CourtListener opinion id
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /legal/citations:
    get:
      summary: Citation graph for a case
      description: "Citation graph for a case. Returns both opinions cited by this case and opinions that cite it back, with depth scores."
      operationId: _legal_citations
      tags:
        - legal
        - citations
        - research
      x-x402:
        price: $0.50
        network: base
        asset: USDC
      parameters:
        - name: case_id
            in: query
            required: true
            schema:
              type: string
            description: CourtListener opinion id
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /legal/courts:
    get:
      summary: "List of US courts indexed by CourtListener with jurisdiction, type, dates of operation"
      description: "List of US courts indexed by CourtListener with jurisdiction, type, dates of operation. Useful for resolving court names to CourtListener IDs."
      operationId: _legal_courts
      tags:
        - legal
        - reference
      x-x402:
        price: $0.02
        network: base
        asset: USDC
      parameters:
        - name: jurisdiction
            in: query
            required: false
            schema:
              type: string
            description: "F (federal), S (state), etc."
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 100"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /legal/dockets/search:
    get:
      summary: Search PACER dockets indexed by CourtListener
      description: "Search PACER dockets indexed by CourtListener. Returns docket numbers, parties, court, filing dates, and document counts."
      operationId: _legal_dockets_search
      tags:
        - legal
        - litigation
        - filings
      x-x402:
        price: $0.15
        network: base
        asset: USDC
      parameters:
        - name: q
            in: query
            required: true
            schema:
              type: string
            description: Free-text query against docket entries
        - name: court
            in: query
            required: false
            schema:
              type: string
            description: Court ID filter
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, 1-50, default 20"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /legal/judges/search:
    get:
      summary: Search US federal and state judges by name
      description: "Search US federal and state judges by name. Returns judge profiles with positions, courts, education, political affiliations, and tenure dates."
      operationId: _legal_judges_search
      tags:
        - legal
        - judges
        - research
      x-x402:
        price: $0.05
        network: base
        asset: USDC
      parameters:
        - name: q
            in: query
            required: true
            schema:
              type: string
            description: Judge name (partial match)
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 20"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /legal/judges/get:
    get:
      summary: "Fetch full profile of a specific judge by CourtListener judge ID — positions held, education, appointments, political affiliations, financial disclosures"
      description: "Fetch full profile of a specific judge by CourtListener judge ID — positions held, education, appointments, political affiliations, financial disclosures."
      operationId: _legal_judges_get
      tags:
        - legal
        - judges
        - research
      x-x402:
        price: $0.05
        network: base
        asset: USDC
      parameters:
        - name: id
            in: query
            required: true
            schema:
              type: string
            description: CourtListener person/judge id
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /legal/citation-lookup:
    get:
      summary: Resolve a US case citation string (e
      description: "Resolve a US case citation string (e.g. '410 U.S. 113') to the underlying CourtListener opinion. Useful for verifying citations and following references."
      operationId: _legal_citation_lookup
      tags:
        - legal
        - citations
        - validation
      x-x402:
        price: $0.10
        network: base
        asset: USDC
      parameters:
        - name: citation
            in: query
            required: true
            schema:
              type: string
            description: "Citation string, e.g. '410 U.S. 113'"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /financial/companies/search:
    get:
      summary: Search SEC-registered companies by ticker or name
      description: "Search SEC-registered companies by ticker or name. Returns CIK, ticker, exchange, and filing counts."
      operationId: _financial_companies_search
      tags:
        - financial
        - sec
        - edgar
        - research
      x-x402:
        price: $0.05
        network: base
        asset: USDC
      parameters:
        - name: q
            in: query
            required: true
            schema:
              type: string
            description: Ticker or company name
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 10"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /financial/filings:
    get:
      summary: "List recent SEC filings for a company by CIK with form type, accession number, filing date, and primary document URL"
      description: "List recent SEC filings for a company by CIK with form type, accession number, filing date, and primary document URL."
      operationId: _financial_filings
      tags:
        - financial
        - sec
        - edgar
        - filings
      x-x402:
        price: $0.10
        network: base
        asset: USDC
      parameters:
        - name: cik
            in: query
            required: true
            schema:
              type: string
            description: "10-digit zero-padded SEC CIK"
        - name: type
            in: query
            required: false
            schema:
              type: string
            description: "Form filter (10-K, 10-Q, 8-K, etc.)"
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 50"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /financial/facts:
    get:
      summary: XBRL company facts for a CIK
      description: "XBRL company facts for a CIK. Returns structured GAAP and IFRS line items across all historical filings — revenue, EPS, assets, etc."
      operationId: _financial_facts
      tags:
        - financial
        - xbrl
        - fundamentals
        - sec
      x-x402:
        price: $0.25
        network: base
        asset: USDC
      parameters:
        - name: cik
            in: query
            required: true
            schema:
              type: string
            description: "10-digit zero-padded SEC CIK"
        - name: concept
            in: query
            required: false
            schema:
              type: string
            description: "GAAP concept filter, e.g. Revenues"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /financial/filing:
    get:
      summary: Fetch a specific filing manifest by accession number and CIK
      description: Fetch a specific filing manifest by accession number and CIK. Returns filing metadata and full exhibit list with document URLs.
      operationId: _financial_filing
      tags:
        - financial
        - sec
        - filings
      x-x402:
        price: $0.20
        network: base
        asset: USDC
      parameters:
        - name: accession
            in: query
            required: true
            schema:
              type: string
            description: Filing accession (e.g. 0000320193-24-000123)
        - name: cik
            in: query
            required: true
            schema:
              type: string
            description: "10-digit zero-padded SEC CIK"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /financial/filings/recent:
    get:
      summary: Stream of most recent SEC filings of a given form type across all issuers
      description: "Stream of most recent SEC filings of a given form type across all issuers. Useful for monitoring 8-Ks, S-1s, insider trades."
      operationId: _financial_filings_recent
      tags:
        - financial
        - sec
        - monitoring
      x-x402:
        price: $0.10
        network: base
        asset: USDC
      parameters:
        - name: type
            in: query
            required: true
            schema:
              type: string
            description: "Form type, e.g. 10-K, 8-K, 4, S-1"
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 50"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /financial/insider-trades/recent:
    get:
      summary: Stream of most recent insider trade reports (SEC Form 4) across all issuers
      description: "Stream of most recent insider trade reports (SEC Form 4) across all issuers. Each entry includes filer, issuer, transaction code, shares, and price."
      operationId: _financial_insider_trades_recent
      tags:
        - financial
        - insider-trades
        - monitoring
        - sec
      x-x402:
        price: $0.15
        network: base
        asset: USDC
      parameters:
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 50"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /financial/8k/recent:
    get:
      summary: Stream of most recent 8-K material event filings across all issuers
      description: Stream of most recent 8-K material event filings across all issuers. Useful for monitoring corporate news as it hits SEC.
      operationId: _financial_8k_recent
      tags:
        - financial
        - "8-k"
        - monitoring
        - sec
      x-x402:
        price: $0.10
        network: base
        asset: USDC
      parameters:
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 50"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /financial/concepts/search:
    get:
      summary: Search GAAP / IFRS taxonomy concept names (e
      description: "Search GAAP / IFRS taxonomy concept names (e.g. 'Revenues', 'CostOfGoodsSold'). Returns matching concepts useful as input to /financial/frames or /financial/facts."
      operationId: _financial_concepts_search
      tags:
        - financial
        - xbrl
        - reference
      x-x402:
        price: $0.05
        network: base
        asset: USDC
      parameters:
        - name: q
            in: query
            required: true
            schema:
              type: string
            description: Concept name fragment
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 50"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /financial/frames:
    get:
      summary: Cross-issuer peer comparison for a single GAAP concept in a given period
      description: "Cross-issuer peer comparison for a single GAAP concept in a given period. Returns every issuer's reported value (e.g. Q4 2023 Revenues across all filers)."
      operationId: _financial_frames
      tags:
        - financial
        - xbrl
        - fundamentals
        - comparison
      x-x402:
        price: $0.30
        network: base
        asset: USDC
      parameters:
        - name: concept
            in: query
            required: true
            schema:
              type: string
            description: "GAAP concept, e.g. Revenues"
        - name: period
            in: query
            required: true
            schema:
              type: string
            description: "Fiscal period, e.g. CY2023Q4"
        - name: unit
            in: query
            required: false
            schema:
              type: string
            description: "Unit, e.g. USD (default)"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /financial/mutual-funds/search:
    get:
      summary: "Search registered investment companies (mutual funds, ETFs) by name or ticker"
      description: "Search registered investment companies (mutual funds, ETFs) by name or ticker. Returns CIK, fund name, series, and class."
      operationId: _financial_mutual_funds_search
      tags:
        - financial
        - funds
        - etf
        - sec
      x-x402:
        price: $0.05
        network: base
        asset: USDC
      parameters:
        - name: q
            in: query
            required: true
            schema:
              type: string
            description: Fund name or ticker
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 20"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /economics/treasury/rates/daily:
    get:
      summary: Average interest rates on US Treasury securities
      description: "Average interest rates on US Treasury securities. Source: Treasury FiscalData. Returns recent daily records by security type with average yield."
      operationId: _economics_treasury_rates_daily
      tags:
        - economics
        - treasury
        - rates
        - macro
      x-x402:
        price: $0.05
        network: base
        asset: USDC
      parameters:
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max records, default 30"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /economics/treasury/debt:
    get:
      summary: "US Federal debt 'to the penny' — public, intragovernmental, and total"
      description: "US Federal debt 'to the penny' — public, intragovernmental, and total. Source: Treasury FiscalData. Recent daily snapshots."
      operationId: _economics_treasury_debt
      tags:
        - economics
        - treasury
        - debt
        - macro
      x-x402:
        price: $0.05
        network: base
        asset: USDC
      parameters:
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max records, default 10"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /economics/treasury/auctions/recent:
    get:
      summary: Recent US Treasury auction results
      description: "Recent US Treasury auction results. Source: Treasury FiscalData. Includes auction date, security type, term, CUSIP, high yield, accepted amount."
      operationId: _economics_treasury_auctions_recent
      tags:
        - economics
        - treasury
        - auctions
        - macro
      x-x402:
        price: $0.10
        network: base
        asset: USDC
      parameters:
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max records, default 30"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /economics/bls/cpi:
    get:
      summary: "US Consumer Price Index for All Urban Consumers (CUUR0000SA0), all items, NSA"
      description: "US Consumer Price Index for All Urban Consumers (CUUR0000SA0), all items, NSA. Source: BLS. Returns full available time series."
      operationId: _economics_bls_cpi
      tags:
        - economics
        - bls
        - inflation
        - cpi
        - macro
      x-x402:
        price: $0.05
        network: base
        asset: USDC
      parameters:
[]
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /economics/bls/unemployment:
    get:
      summary: "US Civilian Unemployment Rate (LNS14000000), 16+, seasonally adjusted"
      description: "US Civilian Unemployment Rate (LNS14000000), 16+, seasonally adjusted. Source: BLS. Full available time series."
      operationId: _economics_bls_unemployment
      tags:
        - economics
        - bls
        - unemployment
        - labor
        - macro
      x-x402:
        price: $0.05
        network: base
        asset: USDC
      parameters:
[]
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /patents/search:
    get:
      summary: Search US patents by keywords appearing in titles
      description: "Search US patents by keywords appearing in titles. Source: USPTO PatentsView. Returns patent number, title, date, type, assignees."
      operationId: _patents_search
      tags:
        - patents
        - uspto
        - ip
        - research
      x-x402:
        price: $0.10
        network: base
        asset: USDC
      parameters:
        - name: q
            in: query
            required: true
            schema:
              type: string
            description: Free-text search against patent title
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 20"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /patents/get:
    get:
      summary: Fetch a single patent by ID
      description: "Fetch a single patent by ID. Returns full structured detail — abstract, inventors, assignees, CPC subclass codes, claim count."
      operationId: _patents_get
      tags:
        - patents
        - uspto
        - ip
      x-x402:
        price: $0.10
        network: base
        asset: USDC
      parameters:
        - name: id
            in: query
            required: true
            schema:
              type: string
            description: Patent id (e.g. 10000000)
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /patents/citations:
    get:
      summary: Citation graph for a patent
      description: "Citation graph for a patent. Returns both the patents this patent cites and the patents that cite it back, with dates and category."
      operationId: _patents_citations
      tags:
        - patents
        - uspto
        - citations
        - ip
      x-x402:
        price: $0.30
        network: base
        asset: USDC
      parameters:
        - name: id
            in: query
            required: true
            schema:
              type: string
            description: Patent id
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max per direction, default 50"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /patents/inventors/search:
    get:
      summary: Search patent inventors by first or last name
      description: "Search patent inventors by first or last name. Returns inventor IDs and patent counts. Source: USPTO PatentsView."
      operationId: _patents_inventors_search
      tags:
        - patents
        - inventors
        - ip
      x-x402:
        price: $0.05
        network: base
        asset: USDC
      parameters:
        - name: q
            in: query
            required: true
            schema:
              type: string
            description: Inventor name fragment
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 20"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /patents/assignees/search:
    get:
      summary: Search patent assignees (organizations) by name
      description: Search patent assignees (organizations) by name. Returns assignee ID and patent count. Useful for competitor IP analysis.
      operationId: _patents_assignees_search
      tags:
        - patents
        - assignees
        - competitive-intel
        - ip
      x-x402:
        price: $0.05
        network: base
        asset: USDC
      parameters:
        - name: q
            in: query
            required: true
            schema:
              type: string
            description: Organization name fragment
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 20"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /gov/federal-register/search:
    get:
      summary: "Search the US Federal Register — proposed rules, executive orders, notices, agency actions"
      description: "Search the US Federal Register — proposed rules, executive orders, notices, agency actions. Source: federalregister.gov. Useful for regulatory monitoring."
      operationId: _gov_federal_register_search
      tags:
        - government
        - regulations
        - federal-register
        - monitoring
      x-x402:
        price: $0.10
        network: base
        asset: USDC
      parameters:
        - name: q
            in: query
            required: true
            schema:
              type: string
            description: Free-text search query
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 20"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /gov/federal-register/recent:
    get:
      summary: "Most recent Federal Register documents, optionally filtered by type (rule, proposed_rule, notice, presidential_document)"
      description: "Most recent Federal Register documents, optionally filtered by type (rule, proposed_rule, notice, presidential_document)."
      operationId: _gov_federal_register_recent
      tags:
        - government
        - regulations
        - monitoring
      x-x402:
        price: $0.05
        network: base
        asset: USDC
      parameters:
        - name: type
            in: query
            required: false
            schema:
              type: string
            description: Document type filter
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 20"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /gov/fda/drugs/search:
    get:
      summary: Search FDA-approved drugs by brand or generic name
      description: "Search FDA-approved drugs by brand or generic name. Source: openFDA. Returns sponsor, marketing status, dosage forms, active ingredients."
      operationId: _gov_fda_drugs_search
      tags:
        - government
        - fda
        - drugs
        - healthcare
      x-x402:
        price: $0.10
        network: base
        asset: USDC
      parameters:
        - name: q
            in: query
            required: true
            schema:
              type: string
            description: Brand or generic drug name
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 20"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /gov/fda/drugs/recalls:
    get:
      summary: FDA drug recall enforcement reports
      description: "FDA drug recall enforcement reports. Optionally filter by drug name. Source: openFDA. Returns classification, status, reason, dates."
      operationId: _gov_fda_drugs_recalls
      tags:
        - government
        - fda
        - drugs
        - recalls
        - healthcare
        - monitoring
      x-x402:
        price: $0.10
        network: base
        asset: USDC
      parameters:
        - name: drug
            in: query
            required: false
            schema:
              type: string
            description: Drug name or product description
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 30"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /gov/fda/adverse-events:
    get:
      summary: FDA adverse event reports for a specific drug
      description: "FDA adverse event reports for a specific drug. Source: openFDA FAERS. Returns reactions, patient demographics, drug indication, severity."
      operationId: _gov_fda_adverse_events
      tags:
        - government
        - fda
        - drugs
        - safety
        - healthcare
      x-x402:
        price: $0.15
        network: base
        asset: USDC
      parameters:
        - name: drug
            in: query
            required: true
            schema:
              type: string
            description: Drug brand or generic name
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max events, default 20"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /gov/fda/devices/recalls:
    get:
      summary: FDA medical device recall enforcement reports
      description: "FDA medical device recall enforcement reports. Optionally filter by device name. Source: openFDA. Useful for medical device monitoring."
      operationId: _gov_fda_devices_recalls
      tags:
        - government
        - fda
        - devices
        - recalls
        - healthcare
      x-x402:
        price: $0.10
        network: base
        asset: USDC
      parameters:
        - name: device
            in: query
            required: false
            schema:
              type: string
            description: Device name or product description
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max results, default 30"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /companies/profile:
    get:
      summary: "Composite company profile by ticker — fans out to SEC submissions, XBRL company facts, and Federal Register mentions in parallel"
      description: "Composite company profile by ticker — fans out to SEC submissions, XBRL company facts, and Federal Register mentions in parallel. Returns CIK, name, recent filings, key GAAP metrics (Revenue, NetIncome, EPS, Assets, R&D), and regulatory exposure summary in one synthesized response. Replaces 4+ upstream calls."
      operationId: _companies_profile
      tags:
        - composite
        - companies
        - financial
        - research
        - premium
      x-x402:
        price: $0.40
        network: base
        asset: USDC
      parameters:
        - name: ticker
            in: query
            required: true
            schema:
              type: string
            description: "Stock ticker, e.g. AAPL"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /companies/by-ticker:
    get:
      summary: "Convenience: ticker → CIK + recent SEC filings in one call"
      description: "Convenience: ticker → CIK + recent SEC filings in one call. Optionally filter by form type (10-K, 10-Q, 8-K, etc.). Saves agents the ticker→CIK resolution step."
      operationId: _companies_by_ticker
      tags:
        - composite
        - companies
        - financial
      x-x402:
        price: $0.10
        network: base
        asset: USDC
      parameters:
        - name: ticker
            in: query
            required: true
            schema:
              type: string
            description: Stock ticker
        - name: type
            in: query
            required: false
            schema:
              type: string
            description: "Form filter (10-K, 8-K, etc.)"
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max filings, default 20"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /companies/insiders:
    get:
      summary: Recent Form 4 insider trades for a given ticker
      description: "Recent Form 4 insider trades for a given ticker. Resolves ticker to CIK, queries EDGAR full-text search filtered by issuer CIK and form 4. 90-day window. Saves agents from chaining ticker lookup → filing search."
      operationId: _companies_insiders
      tags:
        - composite
        - companies
        - insider-trades
        - financial
      x-x402:
        price: $0.15
        network: base
        asset: USDC
      parameters:
        - name: ticker
            in: query
            required: true
            schema:
              type: string
            description: Stock ticker
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max trades, default 20"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /drugs/profile:
    get:
      summary: Composite drug safety profile by drug name
      description: "Composite drug safety profile by drug name. Fans out to FDA drugsfda (approval info), drug enforcement (recalls), and adverse event reports in parallel. Returns sponsor + brands + dosage forms + recall list + top-10 most reported adverse reactions with counts."
      operationId: _drugs_profile
      tags:
        - composite
        - drugs
        - healthcare
        - fda
        - premium
      x-x402:
        price: $0.30
        network: base
        asset: USDC
      parameters:
        - name: name
            in: query
            required: true
            schema:
              type: string
            description: Drug brand or generic name
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /companies/intel:
    get:
      summary: Flagship company intelligence brief by ticker
      description: "Flagship company intelligence brief by ticker. Cross-vertical synthesis combining 5 sources in parallel: SEC submissions (identity + recent filings), XBRL company facts (Revenue, NetIncome, Assets, EPS, R&D), EDGAR full-text search for recent insider trades (Form 4) and material events (8-K), and Federal Register regulatory mentions. One call replaces 7+ underlying requests. The premium intel endpoint."
      operationId: _companies_intel
      tags:
        - composite
        - companies
        - intelligence
        - premium
        - research
      x-x402:
        price: $0.50
        network: base
        asset: USDC
      parameters:
        - name: ticker
            in: query
            required: true
            schema:
              type: string
            description: "Stock ticker, e.g. AAPL"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /judges/snapshot:
    get:
      summary: Composite judge profile by CourtListener person ID
      description: "Composite judge profile by CourtListener person ID. Returns full bio (DOB/DOD, education, ABA ratings, political affiliations with timeline) plus the judge's most recent written opinions with citations. Two parallel CourtListener queries synthesized into one structured response."
      operationId: _judges_snapshot
      tags:
        - composite
        - legal
        - judges
        - research
      x-x402:
        price: $0.30
        network: base
        asset: USDC
      parameters:
        - name: id
            in: query
            required: true
            schema:
              type: string
            description: CourtListener person/judge id
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max recent opinions, default 20"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /regulatory/agency-recent:
    get:
      summary: Recent regulatory activity for a federal agency
      description: "Recent regulatory activity for a federal agency. Returns Federal Register entries mentioning the agency, plus (for FDA specifically) recent drug and device recall enforcement reports. Cross-vertical synthesis for compliance/regulatory monitoring agents."
      operationId: _regulatory_agency_recent
      tags:
        - composite
        - government
        - regulatory
        - monitoring
      x-x402:
        price: $0.25
        network: base
        asset: USDC
      parameters:
        - name: agency
            in: query
            required: true
            schema:
              type: string
            description: "Agency name, e.g. FDA, EPA, SEC, FTC"
        - name: limit
            in: query
            required: false
            schema:
              type: string
            description: "Max entries, default 15"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /case-law/by-citation:
    get:
      summary: "Composite case lookup: given a citation string (e"
      description: "Composite case lookup: given a citation string (e.g. '410 U.S. 113'), returns the matching opinion's metadata plus its citation graph (what it cites + what cites it). Single call replaces three CourtListener round trips."
      operationId: _case_law_by_citation
      tags:
        - composite
        - legal
        - case-law
        - citations
      x-x402:
        price: $0.25
        network: base
        asset: USDC
      parameters:
        - name: citation
            in: query
            required: true
            schema:
              type: string
            description: "Citation string, e.g. '410 U.S. 113'"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /util/ping:
    get:
      summary: Cheap heartbeat endpoint
      description: "Cheap heartbeat endpoint. Pure compute, no upstream call. Returns service name, network, timestamp, and a unique nonce. Designed for stress tests and high-volume agent probes."
      operationId: _util_ping
      tags:
        - util
        - ping
        - stress-test
        - health
      x-x402:
        price: $0.001
        network: base
        asset: USDC
      parameters:
[]
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
  /util/echo:
    get:
      summary: "Echoes back the request's query parameters with a timestamp and unique nonce"
      description: "Echoes back the request's query parameters with a timestamp and unique nonce. Useful for testing agent payment flows and round-trip verification. Pure compute."
      operationId: _util_echo
      tags:
        - util
        - echo
        - stress-test
        - testing
      x-x402:
        price: $0.001
        network: base
        asset: USDC
      parameters:
[]
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad request — missing or invalid parameters.
        402:
          description: Payment required. The X-PAYMENT response header contains payment details per the x402 spec.
        502:
          description: Upstream error from public data source.
components:
  securitySchemes:
    x402:
      type: http
      scheme: x402
      description: Pay-per-request stablecoin micropayment per the x402 spec.
security:
  - x402:
  []