openapi: 3.1.0
info:
  title: LiveTradr API
  description: |
    LiveTradr's public API for AI swarm intelligence market analysis.
    Deploys 120 AI agents to simulate how hedge funds, quants, and retail
    investors react to any market scenario. Returns definitive BEARISH/BULLISH/NEUTRAL
    verdicts with conviction levels.
  version: "2.0"
  contact:
    email: institutional@livetradr.com
  x-logo:
    url: https://livetradr.com/favicon-lt.png

servers:
  - url: https://livetradr.com
    description: Production

paths:
  /api/swarm-simulate:
    post:
      operationId: swarmSimulate
      summary: Run a 15-agent MiroShark market intelligence simulation
      description: |
        Deploys 15 specialist AI agents (3 per archetype) across 4 time horizons
        (0h, 2h, 6h, 24h) to produce a structured market intelligence report for
        any ticker or scenario. Returns dominant narrative, contrarian signal,
        sentiment timeline, archetype breakdown, trading implication, and confidence score.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [source]
              properties:
                source:
                  type: string
                  description: "Ticker + scenario text, e.g. 'Ticker: NVDA\n\nScenario: NVDA misses EPS by 8%'"
                n_agents_per_type:
                  type: integer
                  default: 5
                  description: Number of agents per archetype (5 archetypes = 5x agents total)
            example:
              source: "Ticker: NVDA\n\nScenario: NVDA misses EPS by 8% but guides AI infrastructure flat. How does the crowd react over 24 hours?"
              n_agents_per_type: 3
      responses:
        "200":
          description: Swarm simulation report
          content:
            application/json:
              schema:
                type: object
                properties:
                  report:
                    type: object
                    properties:
                      dominant_narrative:
                        type: string
                      contrarian_signal:
                        type: string
                      sentiment_timeline:
                        type: object
                        properties:
                          "0h": { type: string }
                          "2h": { type: string }
                          "6h": { type: string }
                          "24h": { type: string }
                      archetype_breakdown:
                        type: object
                        additionalProperties:
                          type: object
                          properties:
                            positioning: { type: string }
                            sentiment: { type: string, enum: [bullish, bearish, neutral] }
                            key_concern: { type: string }
                      trading_implication:
                        type: string
                      confidence_score:
                        type: integer
                        minimum: 0
                        maximum: 100
                      confidence_reasoning:
                        type: string
                      watch_for:
                        type: string

  /api/simulation/consensus:
    post:
      operationId: getConsensus
      summary: Synthesise OASIS swarm agent output into a consensus verdict
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ticker, prompt, posts]
              properties:
                ticker:
                  type: string
                  example: NVDA
                prompt:
                  type: string
                  example: "If NVDA misses EPS by 8%, how does the crowd react over 30 days?"
                posts:
                  type: array
                  items:
                    type: object
      responses:
        "200":
          description: Consensus verdict
          content:
            application/json:
              schema:
                type: object
                properties:
                  verdict:
                    type: string
                    enum: [BEARISH, BULLISH, NEUTRAL]
                  conviction:
                    type: string
                    enum: [HIGH, MEDIUM, LOW]
                  rationale:
                    type: string
                  keyBear:
                    type: string
                  keyBull:
                    type: string
                  agentBreakdown:
                    type: string

  /api/graph-extract/from-ticker:
    post:
      operationId: buildKnowledgeGraph
      summary: Build a real-time knowledge graph for any stock ticker
      description: Returns supply chain, customers, competitors, institutional holders, macro linkages, and media coverage for any publicly traded company.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ticker]
              properties:
                ticker:
                  type: string
                  example: NVDA
      responses:
        "200":
          description: Knowledge graph data
          content:
            application/json:
              schema:
                type: object
                properties:
                  nodes:
                    type: array
                  links:
                    type: array
                  summary:
                    type: string