openapi: 3.0.0
info:
  title: Fortune Synthesis Agent API
  description: |
    AI agent identity analysis API. Combines Saju (Four Pillars), Tarot,
    Vedic Astrology, and Zi Wei Dou Shu to generate structured identity data.
    Payment via x402 protocol (Base chain USDC). No API key required.
  version: "1.0.0"
  contact:
    email: flowlabassit@gmail.com
    url: https://www.multifortune.xyz

servers:
  - url: https://www.multifortune.xyz
    description: Production

paths:
  /api/agent:
    get:
      operationId: getAgentApiInfo
      summary: API documentation and discovery
      description: Returns JSON describing all available agent endpoints, pricing, and usage.
      responses:
        "200":
          description: API documentation
          content:
            application/json:
              schema:
                type: object

  /api/agent/analyze:
    post:
      operationId: runFullAnalysis
      summary: Full multi-engine analysis
      description: |
        Runs all four divination engines (Saju, Tarot, Astrology, Zi Wei Dou Shu)
        and returns a synthesized identity analysis. Requires x402 payment of $1.99 USDC.
        Include the payment in the `X-PAYMENT` header.
      parameters:
        - name: X-PAYMENT
          in: header
          required: true
          description: x402 payment header (Base chain USDC)
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnalyzeRequest"
      responses:
        "200":
          description: Analysis completed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalysisResponse"
        "402":
          description: Payment required — includes payment requirements
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentRequired"
        "400":
          description: Invalid input
        "429":
          description: Rate limited (max 5 requests/minute per payer)

  /api/agent/analyze/{engine}:
    post:
      operationId: runSingleEngineAnalysis
      summary: Single-engine analysis
      description: |
        Runs a single divination engine. Requires x402 payment of $0.49 USDC.
        Zi Wei Dou Shu requires birth_time.
      parameters:
        - name: engine
          in: path
          required: true
          schema:
            type: string
            enum: [saju, tarot, astrology, ziwei]
          description: The divination engine to use
        - name: X-PAYMENT
          in: header
          required: true
          description: x402 payment header (Base chain USDC)
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnalyzeRequest"
      responses:
        "200":
          description: Analysis completed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalysisResponse"
        "402":
          description: Payment required
        "400":
          description: Invalid input or engine

  /api/agent/result/{analysisId}:
    get:
      operationId: getAnalysisResult
      summary: Retrieve a completed analysis
      description: |
        Fetch a previously completed agent analysis by ID.
        Also supports lookup by transaction hash via `?tx=` query parameter.
      parameters:
        - name: analysisId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: tx
          in: query
          required: false
          description: x402 transaction hash (alternative lookup)
          schema:
            type: string
      responses:
        "200":
          description: Completed analysis
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResultResponse"
        "202":
          description: Analysis still processing
        "404":
          description: Analysis not found

components:
  schemas:
    AnalyzeRequest:
      type: object
      required:
        - birth_date
        - gender
      properties:
        birth_date:
          type: string
          format: date
          description: Birth date in YYYY-MM-DD format
          example: "1990-05-15"
        birth_time:
          type: string
          description: Birth time in HH:MM format (24h). Required for Zi Wei Dou Shu.
          example: "14:30"
        gender:
          type: string
          enum: [M, F]
          description: Gender (M or F) — affects Saju and Zi Wei calculations
        language:
          type: string
          enum: [en, ko]
          default: en
          description: Response language
        birth_lat:
          type: number
          description: Birth location latitude (improves accuracy via True Solar Time)
          example: 37.5665
        birth_lng:
          type: number
          description: Birth location longitude
          example: 126.978

    AnalysisResponse:
      type: object
      properties:
        analysis_id:
          type: string
          format: uuid
        birth_data:
          type: object
          properties:
            birth_date:
              type: string
            birth_time:
              type: string
            gender:
              type: string
        engines_used:
          type: array
          items:
            type: string
        identity:
          type: object
          description: Structured identity analysis synthesized across all engines
        synthesis:
          type: string
          description: Natural language synthesis of all engine results
        raw_results:
          type: object
          description: Per-engine detailed results

    ResultResponse:
      type: object
      properties:
        analysis_id:
          type: string
          format: uuid
        status:
          type: string
          enum: [completed, processing]
        identity:
          type: object
        raw_results:
          type: object

    PaymentRequired:
      type: object
      properties:
        x402Version:
          type: integer
          example: 1
        error:
          type: string
          example: "payment required"
        resource:
          type: object
          properties:
            url:
              type: string
            description:
              type: string
            mimeType:
              type: string
        accepts:
          type: array
          description: Payment requirements (asset, amount, payTo address, network)