DripMetrics AI Market summary API

openapi: 3.2.0
info:
  title: DripMetrics Market summary API
  version: 1.0.0
  description: DripMetricsAI provides on-demand crypto market microstructure, risk, prediction-market, Hyperliquid, and on-chain metrics. Paid endpoints use x402 (USDC on Base or USDG on Robinhood Chain) and return structured JSON without subscriptions or API keys. Also available over MCP (Streamable HTTP) at https://mcp.dripmetrics.ai/mcp with free discovery tools.
  x-mcp: https://mcp.dripmetrics.ai/mcp
  x-guidance: 'Use /openapi.json for discovery. Routes with x-payment-info are x402-paid resources: first call the endpoint without PAYMENT-SIGNATURE to receive a 402 challenge, then retry with a valid x402 v2 PAYMENT-SIGNATURE. Routes with security: [] are public discovery or health routes and should not be probed for payment.'
  contact:
    email: drip@dripmetrics.ai
    url: https://dripmetrics.ai/
servers:
- url: https://api.dripmetrics.ai
tags:
- name: Market summary
paths:
  /market/summary:
    get:
      operationId: getMarketSummary
      summary: AI-explained BTC market microstructure summary
      description: 'Synthesizes the BTC trade tape and Deribit options chain into deterministic microstructure signals and metrics, including raw, estimated-null, and excess VPIN, plus a concise AI-written explanation of current conditions. The categorical VPIN signal remains null until excess-VPIN thresholds are calibrated from archived BTC windows. All numbers come from the same calculators as the individual metric endpoints; the AI only interprets them. The prose may note hedged historical tendencies for the observed configuration; it never gives price targets or trade recommendations. Invalid requests and upstream failures fail before payment; if summary generation fails after payment, the deterministic payload is still returned with summary: null.'
      tags:
      - Market summary
      parameters:
      - name: pair
        in: query
        required: false
        description: BTC-only in this phase. Optional; defaults to BTC.
        schema:
          type: string
          enum:
          - BTC
          - BTCUSDT
          - BTC-USD
          example: BTC-USD
      - name: window
        in: query
        required: false
        description: Lookback window for the trade-tape signals.
        schema:
          type: string
          enum:
          - 30m
          - 1h
          - 2h
          - 3h
          default: 30m
      security:
      - x402: []
      x-payment-info:
        price:
          fixed:
            mode: fixed
            currency: USD
            amount: '0.25'
        protocols:
        - x402: {}
      x-dripmetrics-paid: true
      x-x402:
        priceUsd: '0.25'
        asset: USDC
        network: eip155:8453
        scheme: exact
        paymentOptions:
        - network: eip155:8453
          asset: USDC
          scheme: exact
        - network: eip155:4663
          asset: USDG
          scheme: exact
      responses:
        '200':
          description: Successful paid response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketSummaryResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '422':
          $ref: '#/components/responses/MetricNotComputable'
        '503':
          $ref: '#/components/responses/UpstreamUnavailable'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        metric:
          type: string
        components:
          type: object
          additionalProperties: true
      required:
      - error
      additionalProperties: true
    MarketSummaryResult:
      type: object
      properties:
        pair:
          type: string
          const: BTC
        window:
          type: string
          enum:
          - 30m
          - 1h
          - 2h
          - 3h
        asOf:
          type: string
          format: date-time
        lastPrice:
          type:
          - number
          - 'null'
        confidence:
          type: number
          minimum: 0
          maximum: 1
        signals:
          type: object
          description: Deterministic categorical reads of each metric family. Each value is null when the underlying metric could not be computed.
          additionalProperties:
            type:
            - string
            - 'null'
        metrics:
          type: object
          description: The numeric metric values behind the signals.
          additionalProperties:
            type:
            - number
            - 'null'
        summary:
          type:
          - string
          - 'null'
          description: AI-written explanation of the signals. Null only when generation failed after payment; the deterministic payload is still returned.
        summaryModel:
          type:
          - string
          - 'null'
        summaryError:
          type: string
        disclaimer:
          type: string
          description: Fixed informational-use disclaimer; never LLM-generated.
        sampleSize:
          type: object
          additionalProperties: true
        coverage:
          type: object
          additionalProperties: true
        source:
          type: object
          additionalProperties: true
      required:
      - pair
      - window
      - asOf
      - lastPrice
      - confidence
      - signals
      - metrics
      - summary
      - summaryModel
      - disclaimer
      - sampleSize
      - coverage
      - source
      additionalProperties: true
  responses:
    UpstreamUnavailable:
      description: Upstream data source unavailable or insufficient.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentRequired:
      description: x402 payment required. Programmatic clients should read payment requirements and retry with a valid PAYMENT-SIGNATURE header.
      headers:
        PAYMENT-REQUIRED:
          description: Base64-encoded x402 v2 payment requirements.
          schema:
            type: string
        PAYMENT-RESPONSE:
          description: Base64-encoded x402 payment response after verification or settlement.
          schema:
            type: string
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    MetricNotComputable:
      description: Metric could not be computed from available data.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    x402:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: x402 v2 payment signature header supplied after reading the 402 PAYMENT-REQUIRED response.