openapi: 3.0.0
info:
  title: AgentQuant Dual-Venue API
  version: 1.0.0
  description: |
    API for Avantis and Synthetic Equity trading signals and market intelligence.
    
    **Pricing is managed in your gateway.**
    
    This API provides:
    - Synthetic Equity alpha signals with cross-venue premium data
    - Bot-discoverable endpoints for automated integration
    
    All paid endpoints require payment via your gateway using X402 protocol.
servers:
  - url: https://agentquant-1.onrender.com
    description: Main production server

tags:
  - name: Avantis
    description: Avantis trading signals and market data
  - name: Synthetic Equity
    description: Synthetic equity alpha signals and cross-venue premium data
  - name: Discovery
    description: Bot-discoverable API information

paths:
  # Discovery endpoints (FREE)
  /api/discovery:
    get:
      tags:
        - Discovery
      summary: Bot-discoverable API information
      description: Returns structured JSON with all available endpoints, parameters, and schemas for bot auto-discovery
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  service_name:
                    type: string
                  description:
                    type: string
                  version:
                    type: string
                  base_url:
                    type: string
                  payment_protocol:
                    type: string
                  currency:
                    type: string
                  network:
                    type: string
                  venues:
                    type: object
                  mcp_tools:
                    type: object
                  free_endpoints:
                    type: object
                  bot_optimization:
                    type: object
                  integration_examples:
                    type: object

  /api/openapi.yaml:
    get:
      tags:
        - Discovery
      summary: OpenAPI 3.0 specification
      description: Returns the OpenAPI 3.0 specification for this API
      responses:
        '200':
          description: OpenAPI specification
          content:
            application/yaml:
              schema:
                type: string
        '404':
          description: OpenAPI specification not found

  /api/docs:
    get:
      tags:
        - Discovery
      summary: API docs (Swagger UI)
      description: Returns Swagger UI for interactive API documentation
      responses:
        '200':
          description: Swagger UI interface

  /health:
    get:
      tags:
        - Discovery
      summary: API health check endpoint
      description: Simple health check endpoint for load balancers and monitoring
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  service:
                    type: string
                    example: sigmagrid-api
                  time:
                    type: string
                    format: date-time
                    example: "2024-01-12T14:03:22.123456Z"

  /v1/validate:
    get:
      tags:
        - Discovery
      summary: Service validation and discovery endpoint
      description: Returns deterministic service metadata including supported assets and pricing model
      responses:
        '200':
          description: Service validation information
          content:
            application/json:
              schema:
                type: object
                properties:
                  service:
                    type: string
                    example: sigmagrid
                  status:
                    type: string
                    example: ok
                  timestamp:
                    type: string
                    format: date-time
                    example: "2024-01-12T14:03:22.123456Z"
                  supported_assets:
                    type: array
                    items:
                      type: string
                    example: ["TSLA", "AAPL", "NVDA", "META", "MSFT", "AMZN", "GOOGL"]
                  pricing_model:
                    type: string
                    example: x402-per-request

  # Synthetic Equity Alpha Signals endpoints
  /v1/signals/{ticker}:
    get:
      tags:
        - Synthetic Equity
      summary: Get unified signal for a ticker
      description: |
        Full consolidated signal combining upstream AlphaSnapshot fundamentals with venue-specific premium and funding data.
        
        **Purpose**: Provides a complete view of fair value, volatility forecasts, drift signals, regime classification, cross-venue premiums, and event sensitivity in a single response.
        
        **Target Audience**: Trading bots, systematic funds, market makers, risk managers, quantitative researchers.
        
        **Why they care**: Single endpoint for all signal data needed to make trading decisions. Combines institutional fair value with real-time perp market premiums across venues, enabling quick comparison and arbitrage detection.
      parameters:
        - name: ticker
          in: path
          required: true
          schema:
            type: string
          description: Ticker symbol (e.g., SPY, QQQ, TSLA)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignalResponse'
        '404':
          description: No signal data available
        '402':
          description: Payment required - use Nexus proxy

  /v1/premium/{ticker}:
    get:
      tags:
        - Synthetic Equity
      summary: Get cross-venue mispricing signals
      description: |
        Detect cross-venue mispricing and reversion opportunities.
        
        **Purpose**: Shows when Hyperliquid, Avantis, Aevo, etc. drift away from fair value or from each other — the core of perp arbitrage.
        
        **Target Audience**: Arbitrage bots, market makers, cross-venue LPs, stat-arb funds.
        
        **Why they care**: Identifies when premiums diverge across venues, creating arbitrage opportunities. Also shows funding-adjusted premiums for carry strategies. Intensity levels help prioritize opportunities.
      parameters:
        - name: ticker
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PremiumResponse'
        '404':
          description: No premium data available
        '402':
          description: Payment required - use Nexus proxy

  /v1/drift/{ticker}:
    get:
      tags:
        - Synthetic Equity
      summary: Get directional compass
      description: |
        Directional drift forecasts for short-term and overnight periods.
        
        **Purpose**: Provides directional bias signals for 1-hour and overnight horizons, helping traders understand expected price movement.
        
        **Target Audience**: Trend-following bots, directional traders, swing traders, position sizing algorithms.
        
        **Why they care**: Drift forecasts help determine entry timing, position sizing, and directional bias. Combined with regime information, enables better risk-adjusted position sizing.
      parameters:
        - name: ticker
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftResponse'
        '404':
          description: No drift data available
        '402':
          description: Payment required - use Nexus proxy

  /v1/regime/{ticker}:
    get:
      tags:
        - Synthetic Equity
      summary: Get risk regime identification
      description: |
        Market state and volatility regime classification.
        
        **Purpose**: Identifies current market regime (risk_on, risk_off, transitioning) with confidence.
        
        **Target Audience**: Risk managers, volatility traders, regime-switching strategies, position sizing algorithms.
        
        **Why they care**: Regime classification helps adjust position sizing, stop-loss levels, and strategy selection. Different regimes require different risk management approaches.
        
        **Full regime with VIX**: For the complete response including VIX level, vix_change_24h_points (in points), and funding_direction, use GET /v1/interim/regime or GET /v1/interim/regime/{ticker}.
        
        **VIX level categories (for interpretation)**: &lt;15 low vol, 15–25 moderate, &gt;25 elevated, &gt;35 high fear.
      parameters:
        - name: ticker
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegimeResponse'
        '404':
          description: No regime data available
        '402':
          description: Payment required - use Nexus proxy

  /v1/events/{ticker}:
    get:
      tags:
        - Synthetic Equity
      summary: Get event sensitivity
      description: |
        Upcoming macro events and their expected market impact.
        
        **Purpose**: Identifies scheduled events (CPI, FOMC, Earnings, etc.) and their expected impact level and directional bias.
        
        **Target Audience**: Event-driven traders, risk managers, volatility traders, position sizing algorithms.
        
        **Why they care**: Helps protect positions around high-impact events. Can be used to reduce position sizes, adjust stop-losses, or take event-driven trades based on expected bias.
      parameters:
        - name: ticker
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
        '404':
          description: No event data available
        '402':
          description: Payment required - use Nexus proxy

  /v1/historical/{ticker}:
    get:
      tags:
        - Synthetic Equity
      summary: Get historical time-series data
      description: |
        Time-series historical data for backtesting, research, and Sharpe uplift studies.
        
        **Purpose**: Provides historical signal data including fair value, drift, regime, premiums, and divergence metrics over time.
        
        **Target Audience**: Quantitative researchers, backtesting systems, Sharpe uplift studies, strategy developers.
        
        **Why they care**: Enables backtesting of strategies, analysis of drift hit-rates, premium behavior patterns, and regime transitions. Essential for validating signal quality and strategy performance.
      parameters:
        - name: ticker
          in: path
          required: true
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: string
            format: date-time
          description: Start time (ISO-8601)
        - name: end
          in: query
          schema:
            type: string
            format: date-time
          description: End time (ISO-8601)
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
          description: Maximum number of records to return
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalResponse'
        '404':
          description: No historical data available
        '402':
          description: Payment required - use Nexus proxy

  /v1/snapshot:
    get:
      tags:
        - Synthetic Equity
      summary: Get multi-ticker dashboard snapshot
      description: Returns compact signal data for multiple tickers
      parameters:
        - name: tickers
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated list of tickers (e.g., SPY,QQQ,TSLA)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotResponse'
        '400':
          description: Invalid tickers parameter
        '402':
          description: Payment required - use Nexus proxy

  /v1/arbitrage/{ticker}:
    get:
      tags:
        - Synthetic Equity
      summary: Get arbitrage and funding signals
      description: |
        Funding-adjusted arbitrage opportunities and carry signals.
        
        **Purpose**: Shows funding rates and funding-adjusted premiums across venues, enabling identification of carry opportunities and funding-adjusted arbitrage.
        
        **Target Audience**: Arbitrage bots, carry traders, funding rate traders, market makers.
        
        **Why they care**: Funding-adjusted premiums show true arbitrage opportunities after accounting for funding costs. Essential for carry strategies and identifying when funding makes arbitrage profitable.
      parameters:
        - name: ticker
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArbitrageResponse'
        '404':
          description: No arbitrage data available
        '402':
          description: Payment required - use Nexus proxy

  /v1/alpha-snapshot/{ticker}:
    get:
      tags:
        - Synthetic Equity
      summary: Get full AlphaSnapshot for one ticker
      description: Returns the latest full AlphaSnapshot (synthetic_signals row) for the given ticker.
      parameters:
        - name: ticker
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Full snapshot (fair_value, vol, regime, drift, events, per-venue mid/premium/funding)
        '404':
          description: No alpha snapshot available for ticker

  /v1/alpha-snapshot/batch:
    get:
      tags:
        - Synthetic Equity
      summary: Get full AlphaSnapshot for multiple tickers
      description: Returns full AlphaSnapshot for each requested ticker. Query parameter tickers=TSLA,AAPL,NVDA.
      parameters:
        - name: tickers
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated tickers (e.g., TSLA,AAPL,NVDA)
      responses:
        '200':
          description: Object keyed by ticker with full snapshot per ticker
        '400':
          description: Missing or invalid tickers parameter

  /healthz:
    get:
      tags:
        - Discovery
      summary: Health check (canonical)
      description: Lightweight health for ops/monitoring. Returns status, signals_ok, last_compute_ts.
      responses:
        '200':
          description: Service healthy

components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        details:
          type: object

    PaymentRequired:
      type: object
      properties:
        error:
          type: string
          example: Payment required. Use Nexus proxy.
        code:
          type: string
          example: PAYMENT_REQUIRED
        details:
          type: object
          properties:
            message:
              type: string
            nexus_url:
              type: string

    SignalResponse:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        ticker:
          type: string
        signals:
          type: object
          properties:
            fair_value:
              type: number
            vol_forecast_1h:
              type: number
            vol_forecast_4h:
              type: number
            regime:
              type: string
            drift_1h:
              type: number
            drift_4h:
              type: number
            drift_overnight:
              type: number
            premiums:
              type: array
              items:
                type: object
                properties:
                  venue:
                    type: string
                  mid_price:
                    type: number
                  premium:
                    type: number
                  funding_rate:
                    type: number
            divergence_zscore:
              type: number
            event_sensitivity:
              type: object
              properties:
                next_event:
                  type: string
                impact:
                  type: string
                bias:
                  type: string
        metadata:
          type: object
          properties:
            version:
              type: string
            expiry_sec:
              type: integer

    PremiumResponse:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        ticker:
          type: string
        fair_value:
          type: number
        venues:
          type: array
          items:
            type: object
            properties:
              venue:
                type: string
              mid_price:
                type: number
              premium:
                type: number
              funding_rate:
                type: number
        divergence_zscore:
          type: number
        divergence_flag:
          type: string
          enum: [normal, elevated, extreme]

    DriftResponse:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        ticker:
          type: string
        drift_1h:
          type: number
        drift_overnight:
          type: number
        regime:
          type: string

    RegimeResponse:
      type: object
      required:
        - regime
        - confidence
        - timestamp
      properties:
        regime:
          type: string
          enum: [risk_on, risk_off, transitioning]
          description: Market risk regime from VIX and funding context.
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Regime classification confidence (0-1).
        vix:
          type: number
          format: float
          description: CBOE VIX index level (typically 8-80). Example 20.82.
        vix_change_24h_points:
          type: number
          format: float
          nullable: true
          description: |
            Change in VIX index level over the last 24 hours, in points (standard market convention).
            Positive = increase in volatility. Example +2.0 means VIX moved from 18.82 to 20.82.
            vix_change_24h reflects absolute point change in CBOE VIX, standard market convention.
        funding_direction:
          type: string
          nullable: true
          description: Funding direction context (e.g. neutral, risk_off, risk_on).
        timestamp:
          type: string
          format: date-time
          description: Time of the regime snapshot; reflects data freshness.
        stale:
          type: boolean
          description: True if underlying data is stale.
        ticker:
          type: string
          description: Ticker symbol when request is per-ticker.

    EventsResponse:
      type: object
      properties:
        ticker:
          type: string
        next_event:
          type: string
        impact:
          type: string
        bias:
          type: string

    HistoricalResponse:
      type: object
      properties:
        ticker:
          type: string
        count:
          type: integer
        data:
          type: array
          items:
            type: object
            properties:
              timestamp:
                type: string
                format: date-time
              fair_value:
                type: number
              regime:
                type: string
              drift_1h:
                type: number
              drift_overnight:
                type: number
              hl_premium:
                type: number
              avantis_premium:
                type: number
              divergence_zscore:
                type: number

    SnapshotResponse:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        tickers:
          type: array
          items:
            type: object
            properties:
              ticker:
                type: string
              timestamp:
                type: string
                format: date-time
              fair_value:
                type: number
              regime:
                type: string
              hl_premium:
                type: number
              avantis_premium:
                type: number

    ArbitrageResponse:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        ticker:
          type: string
        fair_value:
          type: number
        venues:
          type: array
          items:
            type: object
            properties:
              venue:
                type: string
              mid_price:
                type: number
              premium:
                type: number
              funding_rate:
                type: number
              funding_adjusted_premium:
                type: number

  securitySchemes:
    NexusProxy:
      type: http
      scheme: bearer
      description: |
        Requests must come through Nexus proxy for payment enforcement.
        Pricing is configured in Nexus dashboard.

