openapi: "3.1.0"
info:
  title: Verilex Data API
  version: "0.2.0"
  description: |
    Public datasets (NPI healthcare providers, SEC EDGAR filings, weather
    observations, PACER court records, OTC company analytics, USPTO patents
    & trademarks) and Crypto Intelligence (DeFi liquidation risk, market stress)
    accessible via REST API with pay-per-request pricing through the x402
    payment protocol.
    
    Free endpoints require no authentication. Paid endpoints return HTTP 402 with
    payment requirements (USDC via x402 protocol on Base, Polygon, Avalanche, Sei, Solana, Aptos, Stellar).
  contact:
    name: Verilex Data
    url: https://verilexdata.com
    email: support@verilexdata.com

servers:
  - url: https://api.verilexdata.com
    description: Production

paths:
  /health:
    get:
      summary: Health check
      tags: [System]
      responses:
        "200":
          description: System healthy

  # ── NPI ─────────────────────────────────────────────────────────────────

  /api/v1/npi:
    get:
      summary: Query NPI providers
      description: "Paid: $0.018 USDC via x402"
      tags: [NPI]
      parameters:
        - name: state
          in: query
          schema: { type: string }
          description: Two-letter state code
        - name: specialty
          in: query
          schema: { type: string }
          description: Specialty/taxonomy keyword
        - name: name
          in: query
          schema: { type: string }
          description: Provider name search
        - name: limit
          in: query
          schema: { type: integer, default: 100, maximum: 1000 }
        - name: offset
          in: query
          schema: { type: integer, default: 0 }
      responses:
        "200":
          description: Query results
        "402":
          description: Payment required (x402)

  /api/v1/npi/{npi}:
    get:
      summary: Look up a single NPI provider
      description: "Paid: $0.018 USDC via x402"
      tags: [NPI]
      parameters:
        - name: npi
          in: path
          required: true
          schema: { type: string, pattern: "^\\d{10}$" }
      responses:
        "200":
          description: Provider data
        "402":
          description: Payment required
        "404":
          description: NPI not found

  /api/v1/npi/sample:
    get:
      summary: Free sample NPI data (100 records)
      tags: [NPI]
      responses:
        "200":
          description: Sample data

  /api/v1/npi/stats:
    get:
      summary: NPI dataset statistics
      tags: [NPI]
      responses:
        "200":
          description: Dataset stats

  /api/v1/npi/export:
    get:
      summary: Download full NPI dataset (Parquet)
      description: "Paid: $89.99 USDC via x402"
      tags: [NPI]
      responses:
        "200":
          description: Pre-signed download links
        "402":
          description: Payment required

  # ── SEC ─────────────────────────────────────────────────────────────────

  /api/v1/sec/filings:
    get:
      summary: Search SEC filings
      description: "Paid: $0.018 USDC via x402"
      tags: [SEC]
      parameters:
        - name: cik
          in: query
          schema: { type: string }
        - name: form_type
          in: query
          schema: { type: string }
        - name: company_name
          in: query
          schema: { type: string }
        - name: date_from
          in: query
          schema: { type: string, format: date }
        - name: date_to
          in: query
          schema: { type: string, format: date }
        - name: limit
          in: query
          schema: { type: integer, default: 100, maximum: 1000 }
      responses:
        "200":
          description: Filing results
        "402":
          description: Payment required

  /api/v1/sec/filings/{accession}:
    get:
      summary: Get a single filing
      description: "Paid: $0.018 USDC via x402"
      tags: [SEC]
      parameters:
        - name: accession
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Filing data
        "402":
          description: Payment required
        "404":
          description: Filing not found

  /api/v1/sec/companies:
    get:
      summary: Search companies
      description: "Paid: $0.018 USDC via x402"
      tags: [SEC]
      parameters:
        - name: search
          in: query
          required: true
          schema: { type: string, minLength: 2 }
      responses:
        "200":
          description: Company search results
        "402":
          description: Payment required

  /api/v1/sec/sample:
    get:
      summary: Free sample SEC filings (50 recent 8-Ks)
      tags: [SEC]
      responses:
        "200":
          description: Sample filings

  /api/v1/sec/stats:
    get:
      summary: SEC dataset statistics
      tags: [SEC]
      responses:
        "200":
          description: Dataset stats

  /api/v1/sec/export:
    get:
      summary: Download full SEC dataset (Parquet)
      description: "Paid: $43.99 USDC via x402"
      tags: [SEC]
      responses:
        "200":
          description: Pre-signed download links
        "402":
          description: Payment required

  # ── Weather ─────────────────────────────────────────────────────────────

  /api/v1/weather:
    get:
      summary: Query weather observations
      description: "Paid: $0.001 USDC via x402"
      tags: [Weather]
      parameters:
        - name: station_id
          in: query
          schema: { type: string }
          description: GHCN station ID (e.g. USW00023174)
        - name: state
          in: query
          schema: { type: string }
          description: Two-letter state code
        - name: date_from
          in: query
          schema: { type: string, format: date }
        - name: date_to
          in: query
          schema: { type: string, format: date }
        - name: limit
          in: query
          schema: { type: integer, default: 100, maximum: 1000 }
      responses:
        "200":
          description: Weather observation results
        "402":
          description: Payment required

  /api/v1/weather/sample:
    get:
      summary: Free sample weather observations
      tags: [Weather]
      responses:
        "200":
          description: Sample data

  /api/v1/weather/stats:
    get:
      summary: Weather dataset statistics
      tags: [Weather]
      responses:
        "200":
          description: Dataset stats

  /api/v1/weather/export:
    get:
      summary: Download full weather dataset (Parquet)
      description: "Paid: $31.49 USDC via x402"
      tags: [Weather]
      responses:
        "200":
          description: Pre-signed download links
        "402":
          description: Payment required

  # ── PACER ───────────────────────────────────────────────────────────────

  /api/v1/pacer/cases:
    get:
      summary: Search federal court cases
      description: "Paid: $0.50 USDC via x402"
      tags: [PACER]
      parameters:
        - name: party
          in: query
          schema: { type: string }
          description: Party name search
        - name: court
          in: query
          schema: { type: string }
          description: Court code (e.g. cacd, nysd)
        - name: case_type
          in: query
          schema: { type: string }
          description: Case type (civil, criminal, bankruptcy)
        - name: date_from
          in: query
          schema: { type: string, format: date }
        - name: limit
          in: query
          schema: { type: integer, default: 25, maximum: 100 }
      responses:
        "200":
          description: Case results
        "402":
          description: Payment required

  /api/v1/pacer/cases/{caseId}:
    get:
      summary: Look up a single court case
      description: "Paid: $0.13 USDC via x402"
      tags: [PACER]
      parameters:
        - name: caseId
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Case details
        "402":
          description: Payment required
        "404":
          description: Case not found

  /api/v1/pacer/sample:
    get:
      summary: Free sample court case records
      tags: [PACER]
      responses:
        "200":
          description: Sample data

  /api/v1/pacer/stats:
    get:
      summary: PACER dataset statistics
      tags: [PACER]
      responses:
        "200":
          description: Dataset stats

  # ── OTC ─────────────────────────────────────────────────────────────────

  /api/v1/otc:
    get:
      summary: Query OTC companies
      description: "Paid: $0.018 USDC via x402. Search OTC-traded companies with shell risk scoring and financial analytics."
      tags: [OTC]
      parameters:
        - name: ticker
          in: query
          schema: { type: string }
          description: Ticker symbol (partial match)
        - name: company_name
          in: query
          schema: { type: string }
          description: Company name (partial match)
        - name: has_financials
          in: query
          schema: { type: boolean }
          description: Filter to companies with XBRL financial data
        - name: min_filing_recency
          in: query
          schema: { type: integer, minimum: 0, maximum: 100 }
          description: Minimum filing recency score (0-100)
        - name: max_shell_risk
          in: query
          schema: { type: integer, minimum: 0, maximum: 100 }
          description: Maximum shell risk score (0-100)
        - name: min_revenue
          in: query
          schema: { type: number }
          description: Minimum revenue in USD
        - name: limit
          in: query
          schema: { type: integer, default: 25, maximum: 100 }
        - name: offset
          in: query
          schema: { type: integer, default: 0 }
      responses:
        "200":
          description: OTC company results
        "402":
          description: Payment required

  /api/v1/otc/{ticker}:
    get:
      summary: Look up a single OTC company by ticker
      description: "Paid: $0.018 USDC via x402"
      tags: [OTC]
      parameters:
        - name: ticker
          in: path
          required: true
          schema: { type: string, pattern: "^[A-Z]{1,10}$" }
      responses:
        "200":
          description: Company data
        "402":
          description: Payment required
        "404":
          description: Ticker not found

  /api/v1/otc/sample:
    get:
      summary: Free sample OTC companies (25 records)
      tags: [OTC]
      responses:
        "200":
          description: Sample data

  /api/v1/otc/stats:
    get:
      summary: OTC dataset statistics
      tags: [OTC]
      responses:
        "200":
          description: Dataset stats

  /api/v1/otc/export:
    get:
      summary: Download full OTC dataset (Parquet)
      description: "Paid: $237.59 USDC via x402"
      tags: [OTC]
      responses:
        "200":
          description: Pre-signed download links
        "402":
          description: Payment required

  # ── Trademarks ──────────────────────────────────────────────────────────

  /api/v1/trademarks:
    get:
      summary: Search USPTO trademarks
      description: "Paid: $0.018 USDC via x402"
      tags: [Trademarks]
      parameters:
        - name: mark_text
          in: query
          schema: { type: string }
          description: Trademark text (partial match)
        - name: owner_name
          in: query
          schema: { type: string }
          description: Owner / applicant name
        - name: international_class
          in: query
          schema: { type: string }
          description: Nice Classification code (e.g. 009)
        - name: status
          in: query
          schema: { type: string, enum: [REGISTERED, PENDING, ABANDONED, CANCELLED] }
        - name: date_from
          in: query
          schema: { type: string, format: date }
        - name: date_to
          in: query
          schema: { type: string, format: date }
        - name: limit
          in: query
          schema: { type: integer, default: 25, maximum: 100 }
      responses:
        "200":
          description: Trademark results
        "402":
          description: Payment required

  /api/v1/trademarks/{serial}:
    get:
      summary: Look up a trademark by serial number
      description: "Paid: $0.018 USDC via x402"
      tags: [Trademarks]
      parameters:
        - name: serial
          in: path
          required: true
          schema: { type: string, pattern: "^\\d{7,8}$" }
      responses:
        "200":
          description: Trademark details
        "402":
          description: Payment required
        "404":
          description: Serial not found

  /api/v1/trademarks/sample:
    get:
      summary: Free sample trademarks (25 records)
      tags: [Trademarks]
      responses:
        "200":
          description: Sample data

  /api/v1/trademarks/stats:
    get:
      summary: Trademark dataset statistics
      tags: [Trademarks]
      responses:
        "200":
          description: Dataset stats

  /api/v1/trademarks/export:
    get:
      summary: Download full trademark dataset (Parquet)
      description: "Paid: $899.99 USDC via x402"
      tags: [Trademarks]
      responses:
        "200":
          description: Pre-signed download links
        "402":
          description: Payment required

  # ── Patents ─────────────────────────────────────────────────────────────

  /api/v1/patents:
    get:
      summary: Search USPTO patents
      description: "Paid: $0.018 USDC via x402"
      tags: [Patents]
      parameters:
        - name: patent_title
          in: query
          schema: { type: string }
          description: Patent title keyword search
        - name: assignee
          in: query
          schema: { type: string }
          description: Assignee organization name
        - name: inventor
          in: query
          schema: { type: string }
          description: Inventor name
        - name: cpc_section
          in: query
          schema: { type: string, enum: [A, B, C, D, E, F, G, H, Y] }
          description: CPC section letter (Y = cross-sectional technologies)
        - name: patent_type
          in: query
          schema: { type: string, enum: [utility, design, plant, reissue] }
        - name: date_from
          in: query
          schema: { type: string, format: date }
        - name: date_to
          in: query
          schema: { type: string, format: date }
        - name: limit
          in: query
          schema: { type: integer, default: 25, maximum: 100 }
      responses:
        "200":
          description: Patent results
        "402":
          description: Payment required

  /api/v1/patents/{patent_number}:
    get:
      summary: Look up a patent by number
      description: "Paid: $0.018 USDC via x402"
      tags: [Patents]
      parameters:
        - name: patent_number
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Patent details
        "402":
          description: Payment required
        "404":
          description: Patent not found

  /api/v1/patents/sample:
    get:
      summary: Free sample patents (25 records)
      tags: [Patents]
      responses:
        "200":
          description: Sample data

  /api/v1/patents/stats:
    get:
      summary: Patent dataset statistics
      tags: [Patents]
      responses:
        "200":
          description: Dataset stats

  /api/v1/patents/export:
    get:
      summary: Download full patent dataset (Parquet)
      description: "Paid: $44.99 USDC via x402"
      tags: [Patents]
      responses:
        "200":
          description: Pre-signed download links
        "402":
          description: Payment required

  # ── Company Intelligence ────────────────────────────────────────────────

  /api/v1/company/{identifier}:
    get:
      summary: Cross-dataset company profile
      description: "Paid: $0.035 USDC via x402. Unified profile from SEC, OTC, Patents, Trademarks, and PACER."
      tags: [Company]
      parameters:
        - name: identifier
          in: path
          required: true
          schema: { type: string }
          description: Ticker symbol, CIK number, or company name
      responses:
        "200":
          description: Unified company profile
        "402":
          description: Payment required
        "404":
          description: No data found

  /api/v1/companies/screen:
    get:
      summary: Company screener
      description: "Paid: $0.035 USDC via x402. Filter companies by financial, industry, IP, and litigation criteria."
      tags: [Company]
      parameters:
        - name: sic_code
          in: query
          schema: { type: string }
        - name: industry
          in: query
          schema: { type: string }
        - name: min_revenue
          in: query
          schema: { type: number }
        - name: max_revenue
          in: query
          schema: { type: number }
        - name: max_shell_risk
          in: query
          schema: { type: integer, minimum: 0, maximum: 100 }
        - name: has_patents
          in: query
          schema: { type: boolean }
        - name: has_trademarks
          in: query
          schema: { type: boolean }
        - name: has_litigation
          in: query
          schema: { type: boolean }
        - name: limit
          in: query
          schema: { type: integer, default: 25, maximum: 100 }
      responses:
        "200":
          description: Screener results
        "402":
          description: Payment required

  /api/v1/companies/signals:
    get:
      summary: Trader alpha signals
      description: "Paid: $0.035 USDC via x402. Recent signals across all datasets."
      tags: [Company]
      parameters:
        - name: days
          in: query
          schema: { type: integer, default: 7, minimum: 1, maximum: 90 }
          description: Lookback period in days
        - name: signal_types
          in: query
          schema: { type: string }
          description: Comma-separated signal types (new_8k, short_interest_spike, new_patent, new_trademark, new_litigation, delinquent_filer)
        - name: limit
          in: query
          schema: { type: integer, default: 100, maximum: 500 }
      responses:
        "200":
          description: Signal results
        "402":
          description: Payment required

  # ── Crypto Intelligence ──────────────────────────────────────────────────

  /api/v1/crypto/risk/protocols:
    get:
      summary: Protocol risk monitor
      description: "Paid: $0.025 USDC via x402. Liquidation pressure and stress scores per DeFi lending protocol."
      tags: [Crypto]
      parameters:
        - name: window
          in: query
          schema: { type: string, enum: [5m, 1h, 24h, 7d], default: "1h" }
          description: Aggregation time window
        - name: network
          in: query
          schema: { type: string, enum: [ethereum, arbitrum, polygon, base, bsc, avalanche] }
          description: Filter by blockchain network
        - name: protocol
          in: query
          schema: { type: string, enum: [aave_v3, compound_v3, venus, radiant, morpho_blue, llamalend, zerolend, makerdao] }
          description: Filter by lending protocol
        - name: limit
          in: query
          schema: { type: integer, default: 100, maximum: 1000 }
      responses:
        "200":
          description: Protocol risk data
        "402":
          description: Payment required

  /api/v1/crypto/risk/networks:
    get:
      summary: Market stress indices
      description: "Paid: $0.020 USDC via x402. Network-level market stress index combining liquidation intensity, gas costs, and execution failure rates."
      tags: [Crypto]
      parameters:
        - name: window
          in: query
          schema: { type: string, enum: [1h, 24h, 7d], default: "1h" }
          description: Aggregation time window
        - name: network
          in: query
          schema: { type: string, enum: [ethereum, arbitrum, polygon, base, bsc, avalanche] }
          description: Filter by blockchain network
      responses:
        "200":
          description: Network stress data
        "402":
          description: Payment required

  /api/v1/crypto/cohorts/critical:
    get:
      summary: Near-liquidation cohort signals
      description: "Paid: $0.025 USDC via x402. Health factor tier populations, entry/exit rates, and deterioration velocity."
      tags: [Crypto]
      parameters:
        - name: window
          in: query
          schema: { type: string, enum: [5m, 1h, 24h], default: "1h" }
          description: Aggregation time window
        - name: network
          in: query
          schema: { type: string, enum: [ethereum, arbitrum, polygon, base, bsc, avalanche] }
          description: Filter by blockchain network
        - name: protocol
          in: query
          schema: { type: string, enum: [aave_v3, compound_v3, venus, radiant, morpho_blue, llamalend, zerolend, makerdao] }
          description: Filter by lending protocol
      responses:
        "200":
          description: Cohort signals
        "402":
          description: Payment required

  /api/v1/crypto/stats:
    get:
      summary: Crypto intelligence dataset statistics
      tags: [Crypto]
      responses:
        "200":
          description: Dataset stats (total signals, networks, protocols, date range)

  /api/v1/crypto/sample:
    get:
      summary: Free sample liquidation signals (25 recent records)
      tags: [Crypto]
      responses:
        "200":
          description: Sample data

  # ── OFAC Sanctions ───────────────────────────────────────────────────────

  /api/v1/sanctions/screen:
    get:
      summary: Screen a name or wallet against OFAC sanctions
      description: "Paid: $0.005 USDC via x402"
      tags: [Sanctions]
      parameters:
        - name: address
          in: query
          schema: { type: string }
          description: Wallet address to screen
        - name: name
          in: query
          schema: { type: string }
          description: Name to screen
      responses:
        "200":
          description: Sanctions screen results
        "402":
          description: Payment required

  /api/v1/sanctions/search:
    get:
      summary: Full-text sanctions search
      description: "Paid: $0.009 USDC via x402"
      tags: [Sanctions]
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string, minLength: 2 }
      responses:
        "200":
          description: Sanctions search results
        "402":
          description: Payment required

  /api/v1/sanctions/stats:
    get:
      summary: OFAC sanctions dataset stats
      tags: [Sanctions]
      responses:
        "200":
          description: Stats

  /api/v1/sanctions/sample:
    get:
      summary: Free sanctions sample data
      tags: [Sanctions]
      responses:
        "200":
          description: Sample rows

  # ── Whale Wallet Tracking ────────────────────────────────────────────────

  /api/v1/whales:
    get:
      summary: Query whale wallets
      description: "Paid: $0.014 USDC via x402"
      tags: [Whales]
      parameters:
        - name: chain
          in: query
          schema: { type: string, enum: [ethereum, base, polygon, arbitrum] }
        - name: min_balance
          in: query
          schema: { type: number }
        - name: limit
          in: query
          schema: { type: integer, default: 100, maximum: 500 }
      responses:
        "200":
          description: Whale results
        "402":
          description: Payment required

  /api/v1/whales/{address}:
    get:
      summary: Whale wallet details + snapshots
      description: "Paid: $0.020 USDC via x402"
      tags: [Whales]
      parameters:
        - name: address
          in: path
          required: true
          schema: { type: string, pattern: "^0x[a-fA-F0-9]{40}$" }
      responses:
        "200":
          description: Wallet detail
        "402":
          description: Payment required

  /api/v1/whales/movements:
    get:
      summary: Significant whale balance changes
      description: "Paid: $0.040 USDC via x402"
      tags: [Whales]
      parameters:
        - name: period
          in: query
          schema: { type: string, enum: [1h, 24h, 7d], default: "24h" }
      responses:
        "200":
          description: Movement events
        "402":
          description: Payment required

  /api/v1/whales/stats:
    get:
      summary: Whale dataset statistics
      tags: [Whales]
      responses:
        "200":
          description: Stats

  /api/v1/whales/sample:
    get:
      summary: Free whale sample data
      tags: [Whales]
      responses:
        "200":
          description: Sample rows

  # ── Address Labels ───────────────────────────────────────────────────────

  /api/v1/labels/{address}:
    get:
      summary: Address label and risk lookup
      description: "Paid: $0.009 USDC via x402"
      tags: [Labels]
      parameters:
        - name: address
          in: path
          required: true
          schema: { type: string, pattern: "^0x[a-fA-F0-9]{40}$" }
      responses:
        "200":
          description: Label results
        "402":
          description: Payment required

  /api/v1/labels/batch:
    post:
      summary: Batch address label lookup (up to 100)
      description: "Paid: $0.45 USDC via x402"
      tags: [Labels]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [addresses]
              properties:
                addresses:
                  type: array
                  maxItems: 100
                  items:
                    type: string
      responses:
        "200":
          description: Batch label results
        "402":
          description: Payment required

  /api/v1/labels/stats:
    get:
      summary: Label dataset stats
      tags: [Labels]
      responses:
        "200":
          description: Stats

  /api/v1/labels/sample:
    get:
      summary: Free label sample data
      tags: [Labels]
      responses:
        "200":
          description: Sample rows

  # ── Token Holder Snapshots ───────────────────────────────────────────────

  /api/v1/holders/{token_address}:
    get:
      summary: Top token holders
      description: "Paid: $0.04 USDC via x402"
      tags: [Holders]
      parameters:
        - name: token_address
          in: path
          required: true
          schema: { type: string, pattern: "^0x[a-fA-F0-9]{40}$" }
        - name: chain
          in: query
          schema: { type: string, default: "ethereum" }
        - name: limit
          in: query
          schema: { type: integer, default: 100, maximum: 500 }
      responses:
        "200":
          description: Holder ranks
        "402":
          description: Payment required

  /api/v1/holders/{token_address}/concentration:
    get:
      summary: Holder concentration metrics
      description: "Paid: $0.02 USDC via x402"
      tags: [Holders]
      parameters:
        - name: token_address
          in: path
          required: true
          schema: { type: string, pattern: "^0x[a-fA-F0-9]{40}$" }
        - name: chain
          in: query
          schema: { type: string, default: "ethereum" }
      responses:
        "200":
          description: Gini + top holder concentration
        "402":
          description: Payment required

  /api/v1/holders/stats:
    get:
      summary: Holder dataset stats
      tags: [Holders]
      responses:
        "200":
          description: Stats

  /api/v1/holders/sample:
    get:
      summary: Free holder sample data
      tags: [Holders]
      responses:
        "200":
          description: Sample rows

  # ── DEX Trade History ────────────────────────────────────────────────────

  /api/v1/dex/trades:
    get:
      summary: Recent DEX trades by pair/chain
      description: "Paid: $0.003 USDC via x402"
      tags: [DEX]
      parameters:
        - name: pair
          in: query
          schema: { type: string }
        - name: chain
          in: query
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, default: 100, maximum: 500 }
      responses:
        "200":
          description: Trade results
        "402":
          description: Payment required

  /api/v1/dex/pairs:
    get:
      summary: Available indexed DEX pairs
      description: "Paid: $0.001 USDC via x402"
      tags: [DEX]
      parameters:
        - name: chain
          in: query
          schema: { type: string }
      responses:
        "200":
          description: Pair listing
        "402":
          description: Payment required

  /api/v1/dex/volume:
    get:
      summary: DEX pair volume stats
      description: "Paid: $0.005 USDC via x402"
      tags: [DEX]
      parameters:
        - name: pair
          in: query
          schema: { type: string }
        - name: period
          in: query
          schema: { type: string, enum: [1h, 24h, 7d, 30d], default: "24h" }
      responses:
        "200":
          description: Volume statistics
        "402":
          description: Payment required

  /api/v1/dex/stats:
    get:
      summary: DEX dataset stats
      tags: [DEX]
      responses:
        "200":
          description: Stats

  /api/v1/dex/sample:
    get:
      summary: Free DEX sample trades
      tags: [DEX]
      responses:
        "200":
          description: Sample rows

  # ── Government Contracts ────────────────────────────────────────────────

  /api/v1/contracts:
    get:
      summary: Search government contract awards
      description: "Paid: $0.018 USDC via x402"
      tags: [Contracts]
      parameters:
        - name: agency
          in: query
          schema: { type: string }
        - name: min_amount
          in: query
          schema: { type: number }
        - name: limit
          in: query
          schema: { type: integer, default: 100, maximum: 1000 }
      responses:
        "200":
          description: Contract search results
        "402":
          description: Payment required

  /api/v1/contracts/{award_id}:
    get:
      summary: Single contract award lookup
      description: "Paid: $0.018 USDC via x402"
      tags: [Contracts]
      parameters:
        - name: award_id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Contract award details
        "402":
          description: Payment required

  /api/v1/contracts/top-vendors:
    get:
      summary: Top vendors by total awarded spend
      description: "Paid: $0.03 USDC via x402"
      tags: [Contracts]
      parameters:
        - name: agency
          in: query
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
      responses:
        "200":
          description: Top-vendor aggregates
        "402":
          description: Payment required

  /api/v1/contracts/export:
    get:
      summary: Download full contracts dataset
      description: "Paid: $179.99 USDC via x402"
      tags: [Contracts]
      responses:
        "200":
          description: Parquet export links
        "402":
          description: Payment required

  /api/v1/contracts/stats:
    get:
      summary: Contracts dataset statistics
      tags: [Contracts]
      responses:
        "200":
          description: Stats

  /api/v1/contracts/sample:
    get:
      summary: Free contracts sample data
      tags: [Contracts]
      responses:
        "200":
          description: Sample rows
