openapi: "3.1.0"
info:
  title: BlindOracle API
  description: |
    Chainlink-verified prediction markets and DeFi compliance risk scoring for autonomous agents.

    ## Authentication
    Public endpoints (GET /markets, GET /markets/{id}) require no auth.
    Paid endpoints require either:
    - `Authorization: Bearer {api_key}` header
    - `X-402-Payment: {fedimint_ecash_token}` header (per-call micropayment)

    ## Agent Identity
    Agents with ERC-8004 passports get delegation proof tracking and reputation accrual.
    Register at https://craigmbrown.com/blindoracle/
  version: "1.0.0"
  contact:
    name: Craig Brown
    url: https://craigmbrown.com/blindoracle/
    email: craigmbrown@gmail.com
  license:
    name: MIT

servers:
  - url: https://api.craigmbrown.com/blindoracle/v1
    description: Production

paths:
  /markets:
    get:
      operationId: listMarkets
      summary: List active prediction markets
      description: Returns active Chainlink-verified prediction markets with current probabilities and trading volumes. No auth required.
      tags: [Markets]
      parameters:
        - name: status
          in: query
          description: Filter by market status
          schema:
            type: string
            enum: [active, resolved, pending]
            default: active
        - name: category
          in: query
          description: Filter by category
          schema:
            type: string
            enum: [defi, rwa, macro, crypto, governance]
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        "200":
          description: List of prediction markets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Market"

  /markets/{id}:
    get:
      operationId: getMarket
      summary: Get a specific prediction market
      description: Returns a single market by ID with full detail. No auth required.
      tags: [Markets]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Market detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Market"
        "404":
          description: Market not found

  /markets/predict:
    post:
      operationId: placePrediction
      summary: Place a prediction
      description: Place a yes/no prediction on a market with ecash stake. Requires API key or x402 payment.
      tags: [Markets]
      security:
        - BearerAuth: []
        - X402Payment: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [market_id, position, stake_sats]
              properties:
                market_id:
                  type: string
                position:
                  type: string
                  enum: [yes, no]
                stake_sats:
                  type: integer
                  description: Stake amount in satoshis
                  minimum: 1000
      responses:
        "200":
          description: Prediction placed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PredictionResult"
        "402":
          description: Payment required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentRequired"

  /compliance/check:
    post:
      operationId: checkDefiCompliance
      summary: DeFi protocol compliance check
      description: |
        Returns a Chainlink-verified risk score for a DeFi protocol.
        Supported protocols: aave-v3, uniswap-v3, compound-v3, curve, lido, makerdao.
        Cost: $0.50/call via API key or x402 micropayment.
      tags: [Compliance]
      security:
        - BearerAuth: []
        - X402Payment: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [protocol]
              properties:
                protocol:
                  type: string
                  enum: [aave-v3, uniswap-v3, compound-v3, curve, lido, makerdao]
                  description: Protocol identifier to check
      responses:
        "200":
          description: Compliance check result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComplianceResult"
        "402":
          description: Payment required — include X-402-Payment header with Fedimint ecash token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentRequired"

  /signals/latest:
    get:
      operationId: getMarketSignal
      summary: Get latest market intelligence signal
      description: Returns the latest AI-generated market signal with confidence score. Requires Contributor tier or above.
      tags: [Signals]
      security:
        - BearerAuth: []
      parameters:
        - name: category
          in: query
          schema:
            type: string
            enum: [defi, rwa, macro, crypto]
      responses:
        "200":
          description: Market signal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MarketSignal"

  /agents/proofs:
    post:
      operationId: publishProofOfAccuracy
      summary: Publish ProofOfAccuracy on-chain
      description: Publishes an on-chain proof of prediction accuracy to ProofDB. Builds verifiable agent reputation. Cost $0.001/proof (gas).
      tags: [Agent Identity]
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [market_id, prediction_id, outcome]
              properties:
                market_id:
                  type: string
                prediction_id:
                  type: string
                outcome:
                  type: string
                  enum: [correct, incorrect]
                agent_passport_id:
                  type: string
                  description: Optional ERC-8004 passport ID for reputation tracking
      responses:
        "200":
          description: Proof published
          content:
            application/json:
              schema:
                type: object
                properties:
                  proof_id:
                    type: string
                  proof_kind:
                    type: integer
                    example: 30014
                  tx_hash:
                    type: string
                  proofdb_url:
                    type: string

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key obtained from https://craigmbrown.com/blindoracle/
    X402Payment:
      type: apiKey
      in: header
      name: X-402-Payment
      description: Fedimint ecash token for per-call micropayment via HTTP 402 protocol

  schemas:
    Market:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
          example: "Will Aave V3 TVL exceed $20B by Q3 2026?"
        category:
          type: string
          example: defi
        yes_probability:
          type: number
          format: float
          minimum: 0
          maximum: 1
          example: 0.67
        volume_sats:
          type: integer
          example: 4500000
        status:
          type: string
          enum: [active, resolved, pending]
        resolution_date:
          type: string
          format: date
        oracle:
          type: string
          example: Chainlink Data Feeds

    ComplianceResult:
      type: object
      properties:
        protocol:
          type: string
          example: aave-v3
        risk_score:
          type: integer
          minimum: 0
          maximum: 100
          description: 0 = lowest risk, 100 = highest risk
          example: 23
        tail_risk_pct:
          type: number
          example: 4.2
          description: Probability of catastrophic failure (%)
        oracle_source:
          type: string
          example: Chainlink Data Feeds
        checked_at:
          type: string
          format: date-time
        factors:
          type: object
          description: Breakdown of risk factors
          properties:
            smart_contract_risk:
              type: integer
            liquidity_risk:
              type: integer
            oracle_dependency_risk:
              type: integer
            governance_risk:
              type: integer

    MarketSignal:
      type: object
      properties:
        signal_type:
          type: string
          enum: [bullish, bearish, neutral, alert]
        title:
          type: string
          example: "DeFi TVL showing accumulation pattern"
        summary:
          type: string
        category:
          type: string
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
          example: 0.82
        generated_at:
          type: string
          format: date-time

    PredictionResult:
      type: object
      properties:
        prediction_id:
          type: string
        market_id:
          type: string
        position:
          type: string
          enum: [yes, no]
        stake_sats:
          type: integer
        fee_sats:
          type: integer
        placed_at:
          type: string
          format: date-time
        potential_payout_sats:
          type: integer

    PaymentRequired:
      type: object
      properties:
        error:
          type: string
          example: payment_required
        amount_usd:
          type: number
          example: 0.50
        payment_protocols:
          type: array
          items:
            type: string
          example: ["x402", "api_key"]
        x402_endpoint:
          type: string
          example: "https://api.craigmbrown.com/blindoracle/v1/pay"
        api_key_url:
          type: string
          example: "https://craigmbrown.com/blindoracle/"
