openapi: 3.1.0
info:
  title: Federal Procurement MCP
  version: 0.1.0
  description: |
    Three pay-per-call x402 endpoints for U.S. federal procurement data:
    `opportunities/search` ($0.05, SAM.gov), `awards/search` ($0.03, USASpending.gov),
    `agencies/list` ($0.01, USASpending.gov). Pay USDC on Base — no signup, no API key.
  contact:
    email: hello@
servers:
  - url: https://procure-mcp.mtree.workers.dev
x-pricing:
  - path: /v1/opportunities/search
    method: POST
    price: $0.05
    amount: "0.05"
    asset: USDC
    network: base
  - path: /v1/awards/search
    method: POST
    price: $0.03
    amount: "0.03"
    asset: USDC
    network: base
  - path: /v1/agencies/list
    method: POST
    price: $0.01
    amount: "0.01"
    asset: USDC
    network: base
paths:
  /v1/opportunities/search:
    post:
      summary: Search SAM.gov contract opportunities
      description: |
        Search live U.S. federal contract opportunities (RFPs, RFIs, sources sought) on SAM.gov by keyword,
        NAICS, place-of-performance state, and posting recency. Returns notice IDs, deadlines, agencies,
        NAICS codes, and direct UI links. $0.05 per call via x402 USDC on Base. Requires the deployment to
        have `SAM_API_KEY` configured (free at sam.gov); without it, this endpoint returns 503.
      operationId: opportunitiesSearch
      x-x402-price-usd: 0.05
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                keyword: { type: string, example: cybersecurity }
                naics: { type: string, example: "541512" }
                state: { type: string, example: CA }
                postedFromDays: { type: integer, example: 30, minimum: 1, maximum: 365 }
                limit: { type: integer, example: 25, minimum: 1, maximum: 100 }
      responses:
        '402': { description: Payment required (x402 envelope) }
        '200': { description: Search results }
        '503': { description: SAM_API_KEY not configured on this deployment }
  /v1/awards/search:
    post:
      summary: Search USASpending.gov federal contract awards
      description: |
        Search U.S. federal contract awards on USASpending.gov by keyword, awarding agency, NAICS,
        and time window. Returns recipient, amount, agency, NAICS/PSC, and direct USASpending links.
        $0.03 per call via x402 USDC on Base. No upstream auth required (USASpending.gov is fully open).
      operationId: awardsSearch
      x-x402-price-usd: 0.03
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                keyword: { type: string, example: satellite }
                agency: { type: string, example: Department of Defense }
                naics: { type: string, example: "517410" }
                fromDays: { type: integer, example: 90, minimum: 1, maximum: 3650 }
                limit: { type: integer, example: 25, minimum: 1, maximum: 100 }
      responses:
        '402': { description: Payment required (x402 envelope) }
        '200': { description: Search results }
  /v1/agencies/list:
    post:
      summary: Directory of U.S. federal toptier agencies
      description: |
        Directory of U.S. federal toptier agencies with budget authority + outlay totals.
        Useful for resolving agency names, abbreviations, and codes before querying awards/opportunities.
        $0.01 per call via x402 USDC on Base.
      operationId: agenciesList
      x-x402-price-usd: 0.01
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                search: { type: string, example: Defense }
                limit: { type: integer, example: 50, minimum: 1, maximum: 500 }
      responses:
        '402': { description: Payment required (x402 envelope) }
        '200': { description: Agency directory }
  /healthz:
    get:
      summary: Liveness probe (unpaid)
      operationId: healthz
      responses:
        '200': { description: Service is live }
  /mcp:
    post:
      summary: MCP Streamable HTTP transport (JSON-RPC 2.0; unpaid catalog discovery)
      operationId: mcpRpc
      responses:
        '200': { description: JSON-RPC response }

x-money-tree-buyer-readiness:
  quote_before_signing: "Read the unpaid 402 quote before signing or before paying; compare payTo, amount, network, asset, and resource."
  rail_readiness:
    network: "eip155:8453"
    asset: "USDC on Base"
  payment_proof_policy:
    require_payment_response: true
    receipt_fields: [transaction, network, asset, amount, payer, payTo]
  funding_handoff: "If the buyer lacks Base USDC or the settlement asset, stop before signing and hand off to funding; retry only with the same request after funding."
  revenue_metric_policy: "External paid calls are settled revenue; self-funded/internal-credit calls are protocol proof only."
  decision_json_shape:
    required_keys: [verdict, recommendation, warnings, confidence, metadata, evidence, action, stop_conditions, fallbacks, attribution]
