{
  "openapi": "3.0.3",
  "info": {
    "title": "HyperWasp Reports & Skills API",
    "version": "1.1.0",
    "description": "Order AI-generated stock analysis reports from 8 independent analysts, plus market literacy skills and agent certifications. Payment via x402 protocol (USDC on Base network). All content is Ed25519 signed and response-hardened.",
    "contact": {
      "name": "HyperWasp",
      "url": "https://hyperwasp.com"
    }
  },
  "servers": [
    {
      "url": "https://api.hyperwasp.com/api/v2",
      "description": "Production API"
    }
  ],
  "paths": {
    "/reports/order/{ticker}": {
      "get": {
        "operationId": "orderReport",
        "summary": "Order a stock analysis report",
        "description": "Request a report for a US equity ticker. Returns HTTP 402 with x402 payment requirements (USDC on Base). After USDC payment is verified on-chain, the signed JSON report is delivered in the response body.",
        "x-payment-info": {
          "protocols": ["x402"],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "1.00",
            "max": "35.01"
          },
          "network": "eip155:8453",
          "asset": "USDC",
          "description": "Price varies by report type: momentum ($1), standard ($25), rush ($35.01)"
        },
        "x-bazaar": {
          "discoverable": true,
          "category": "finance",
          "tags": ["stock-analysis", "trading-signals", "insider-flow", "institutional-positioning", "risk-assessment", "ai-agents"]
        },
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{1,5}$",
              "example": "UNH"
            },
            "description": "US equity ticker symbol (1-5 uppercase letters). Examples: AAPL, TSLA, UNH, CHRD"
          },
          {
            "name": "speed",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["standard", "rush"],
              "default": "standard"
            },
            "description": "Delivery speed. standard = 12 hours ($25 USDC). rush = 1 hour ($35.01 USDC, auto-refund if SLA missed)."
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["full", "momentum"],
              "default": "full"
            },
            "description": "Report type. full = 8-analyst comprehensive ($25 standard, $35.01 rush). momentum = real-time signal ($1)."
          }
        ],
        "responses": {
          "402": {
            "description": "Payment required. The PAYMENT-REQUIRED header contains base64-encoded x402 payment requirements including payTo address, amount in USDC base units, and network (base-mainnet).",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded JSON with x402 payment requirements",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "200": {
            "description": "Report delivered after payment verification. Content is signed with Ed25519. Verify by checking meta.content_hash against SHA-256 of the report body, then verify meta.signature against the public key at /.well-known/keys.json.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FullReport"
                }
              }
            }
          },
          "400": {
            "description": "Invalid ticker symbol or parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/x402/skills/first-blood": {
      "get": {
        "operationId": "buyFirstBlood",
        "summary": "Purchase First Blood market literacy skill",
        "description": "Buy the First Blood skill — market literacy fundamentals for AI agents. Returns HTTP 402 with x402 payment requirements ($5 USDC on Base). After payment, delivers Ed25519-signed, response-hardened skill content including SKILL.md (265 lines) and loss anatomy case study.",
        "x-payment-info": {
          "protocols": ["x402"],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "5.00"
          },
          "network": "eip155:8453",
          "asset": "USDC",
          "description": "First Blood market literacy skill for AI agents"
        },
        "x-bazaar": {
          "discoverable": true,
          "category": "education",
          "tags": ["agent-skills", "market-literacy", "trading-fundamentals", "ai-education", "agent-certification"]
        },
        "responses": {
          "402": {
            "description": "Payment required. $5 USDC on Base via x402 protocol."
          },
          "200": {
            "description": "Skill delivered after payment. Content is Ed25519 signed, response-hardened, with integrity seal and content boundary markers.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "skill": {
                      "type": "string",
                      "description": "Skill content (markdown)"
                    },
                    "examples": {
                      "type": "object",
                      "description": "Supporting examples and case studies"
                    },
                    "signature": {
                      "type": "string",
                      "description": "Ed25519 signature"
                    },
                    "content_hash": {
                      "type": "string",
                      "description": "SHA-256 content hash"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/reports/verify": {
      "post": {
        "operationId": "verifyReport",
        "summary": "Verify report authenticity and integrity",
        "description": "Submit a report to verify its Ed25519 signature and SHA-256 content hash. Confirms the report was generated by HyperWasp and has not been tampered with.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FullReport"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verified": {
                      "type": "boolean",
                      "description": "true if signature and content hash are valid"
                    },
                    "signer": {
                      "type": "string",
                      "description": "Key ID that signed this report"
                    },
                    "integrity": {
                      "type": "string",
                      "enum": ["valid", "tampered", "unknown_signer"],
                      "description": "Content integrity status"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FullReport": {
        "type": "object",
        "required": ["meta", "analysts", "conviction"],
        "properties": {
          "meta": {
            "type": "object",
            "required": ["ticker", "generated_at", "report_id", "report_type"],
            "properties": {
              "ticker": {
                "type": "string",
                "description": "Equity ticker symbol"
              },
              "generated_at": {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp of report generation"
              },
              "report_id": {
                "type": "string",
                "format": "uuid",
                "description": "Unique report identifier"
              },
              "report_type": {
                "type": "string",
                "enum": ["full", "summary", "momentum"]
              },
              "content_hash": {
                "type": "string",
                "description": "SHA-256 hash of the serialized report body (analysts + conviction sections). Hex-encoded."
              },
              "signature": {
                "type": "string",
                "description": "Ed25519 signature of content_hash. Base64-encoded."
              },
              "signed_by": {
                "type": "string",
                "description": "Key ID from /.well-known/keys.json used to sign this report"
              },
              "schema_version": {
                "type": "string",
                "description": "Report schema version for forward compatibility"
              }
            }
          },
          "analysts": {
            "type": "array",
            "description": "Individual analyst assessments. 8 sections for full reports.",
            "items": {
              "$ref": "#/components/schemas/AnalystSection"
            }
          },
          "conviction": {
            "type": "object",
            "description": "Aggregate conviction scoring across all analysts",
            "properties": {
              "score": {
                "type": "number",
                "minimum": 0,
                "maximum": 100,
                "description": "Weighted conviction score (0-100)"
              },
              "consensus": {
                "type": "string",
                "enum": ["STRONG_BUY", "BUY", "NEUTRAL", "SELL", "STRONG_SELL"],
                "description": "Aggregate consensus assessment"
              },
              "agreement_ratio": {
                "type": "number",
                "minimum": 0,
                "maximum": 1,
                "description": "Fraction of analysts in agreement with consensus (0.0-1.0)"
              },
              "dissent": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Names of dissenting analysts with brief reasoning"
              }
            }
          }
        }
      },
      "AnalystSection": {
        "type": "object",
        "required": ["analyst", "role", "assessment"],
        "properties": {
          "analyst": {
            "type": "string",
            "description": "Analyst name (e.g. Cipher, Wren, Theorem)"
          },
          "role": {
            "type": "string",
            "description": "Analyst specialization (e.g. Technical Analysis, Risk Assessment)"
          },
          "assessment": {
            "type": "string",
            "enum": ["BULLISH", "NEUTRAL", "BEARISH"],
            "description": "Directional assessment"
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Confidence in assessment (0.0-1.0)"
          },
          "key_findings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Top findings from this analyst's domain"
          },
          "risk_factors": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Identified risk factors"
          },
          "data_points": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DataPoint"
            },
            "description": "Quantitative data supporting the assessment"
          }
        }
      },
      "DataPoint": {
        "type": "object",
        "required": ["metric", "value"],
        "properties": {
          "metric": {
            "type": "string",
            "description": "Name of the metric (e.g. dark_pool_ratio, insider_buy_count)"
          },
          "value": {
            "description": "Metric value (string, number, or boolean)"
          },
          "period": {
            "type": "string",
            "description": "Time period for the metric (e.g. 5d, 30d, 1y)"
          },
          "context": {
            "type": "string",
            "description": "Brief context for the data point"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error type"
          },
          "message": {
            "type": "string",
            "description": "Human-readable error description"
          }
        }
      }
    }
  }
}