openapi: 3.1.0
info:
  title: Mezcal Protocol Extensions API
  version: 1.0.0
  description: Protocol-specific Mezcal extension contract for bridge analytics surfaces that sit outside the core explorer API.
servers:
  - url: /api
    description: Hosted external Mezcal API base for this docs deployment. Requests execute against /api/v1/* on the same host.
security:
  - MezcalApiKey: []
paths:
  /v1/{chain}/analytics/wrappers:
    get:
      summary: BTC wrapper analytics aggregates
      security:
        - MezcalApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: window
          in: query
          description: Lookback window in hours (clamped to 1..720).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 720
        - name: status
          in: query
          description: Metrics tier (`provisional` or `finalized`).
          schema:
            $ref: "#/components/schemas/AnalyticsMetricsStatus"
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Aggregated wrapper metrics for the selected window
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WrapperAnalyticsView"
        "400":
          description: Invalid analytics query parameter
          content:
            text/plain:
              schema:
                type: string
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
      x-mezcal-audience: protocol-extension
      x-mezcal-stability: stable
      x-mezcal-surface-tier: official-public-api
      x-mezcal-key-tier: read
      tags:
        - Bridge analytics
  /v1/{chain}/analytics/wrappers/txs:
    get:
      summary: Wrapper transactions page
      security:
        - MezcalApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: token
          in: query
          required: true
          description: Wrapper token symbol or contract address.
          schema:
            type: string
        - name: window
          in: query
          description: Lookback window in hours (clamped to 1..720).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 720
        - name: status
          in: query
          description: Metrics tier (`provisional` or `finalized`).
          schema:
            $ref: "#/components/schemas/AnalyticsMetricsStatus"
        - name: cursor
          in: query
          description: Cursor encoded as `block:tx:log:transfer`.
          schema:
            type: string
        - name: limit
          in: query
          description: Page size (clamped to 1..100).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Paginated wrapper transfer transactions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WrapperTxPageView"
        "400":
          description: Invalid analytics query parameter
          content:
            text/plain:
              schema:
                type: string
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Wrapper token not found
          content:
            text/plain:
              schema:
                type: string
      x-mezcal-audience: protocol-extension
      x-mezcal-stability: stable
      x-mezcal-surface-tier: official-public-api
      x-mezcal-key-tier: read
      tags:
        - Bridge analytics
  /v1/{chain}/analytics/netflows:
    get:
      summary: Starknet bridge netflow timeseries
      security:
        - MezcalApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: window
          in: query
          description: Lookback window in hours (clamped to 1..720).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 720
        - name: granularity
          in: query
          description: Timeseries bucket granularity.
          schema:
            type: string
            enum:
              - 1h
              - 1d
        - name: status
          in: query
          description: Metrics tier (`provisional` or `finalized`).
          schema:
            $ref: "#/components/schemas/AnalyticsMetricsStatus"
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Netflow totals and timeseries buckets
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NetflowSeriesView"
        "400":
          description: Invalid analytics query parameter
          content:
            text/plain:
              schema:
                type: string
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
      x-mezcal-audience: protocol-extension
      x-mezcal-stability: stable
      x-mezcal-surface-tier: official-public-api
      x-mezcal-key-tier: read
      tags:
        - Bridge analytics
  /v1/{chain}/analytics/netflows/assets:
    get:
      summary: Starknet bridge netflow per-asset breakdown
      security:
        - MezcalApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: window
          in: query
          description: Lookback window in hours (clamped to 1..720).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 720
        - name: status
          in: query
          description: Metrics tier (`provisional` or `finalized`).
          schema:
            $ref: "#/components/schemas/AnalyticsMetricsStatus"
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Netflow totals and top asset breakdown
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NetflowAssetsView"
        "400":
          description: Invalid analytics query parameter
          content:
            text/plain:
              schema:
                type: string
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
      x-mezcal-audience: protocol-extension
      x-mezcal-stability: stable
      x-mezcal-surface-tier: official-public-api
      x-mezcal-key-tier: read
      tags:
        - Bridge analytics
components:
  securitySchemes:
    MezcalApiKey:
      type: apiKey
      in: header
      name: X-Mezcal-Api-Key
      description: Mezcal API key for protocol-extension reads.
  parameters:
    ChainParam:
      name: chain
      in: path
      required: true
      schema:
        type: string
    RequestIdHeader:
      name: X-Request-Id
      in: header
      required: false
      description: Optional caller-supplied correlation ID echoed back in the response.
      schema:
        type: string
  responses:
    UnauthorizedText:
      description: Missing or invalid Mezcal credential.
      headers:
        X-Request-Id:
          description: Canonical request correlation header for support and tracing.
          schema:
            type: string
        WWW-Authenticate:
          description: Auth error details when the request is rejected.
          schema:
            type: string
      content:
        text/plain:
          schema:
            type: string
            example: Unauthorized
    ForbiddenText:
      description: Valid Mezcal credential lacks the required scope.
      headers:
        X-Request-Id:
          description: Canonical request correlation header for support and tracing.
          schema:
            type: string
        WWW-Authenticate:
          description: Scope hint when the caller lacks required access.
          schema:
            type: string
      content:
        text/plain:
          schema:
            type: string
            example: Forbidden
  schemas:
    AnalyticsMetricsStatus:
      type: string
      enum:
        - provisional
        - finalized
    AnalyticsFreshnessView:
      type: object
      additionalProperties: false
      required:
        - metricsStatus
        - refreshedAtIso
        - refreshedFromIso
        - refreshedToIso
      properties:
        metricsStatus:
          $ref: "#/components/schemas/AnalyticsMetricsStatus"
        refreshedAtIso:
          type: string
        refreshedFromIso:
          type: string
        refreshedToIso:
          type: string
    WrapperAnalyticsItemView:
      type: object
      additionalProperties: false
      required:
        - tokenAddress
        - symbol
        - name
        - txCount
        - transferCount
        - amountBtc
        - volumeUsd
        - priceUnavailableTransfers
      properties:
        tokenAddress:
          type: string
        symbol:
          type: string
        name:
          type: string
        txCount:
          type: integer
          format: int64
        transferCount:
          type: integer
          format: int64
        amountBtc:
          type:
            - string
            - "null"
        volumeUsd:
          type:
            - string
            - "null"
        priceUnavailableTransfers:
          type: integer
          format: int64
    WrapperAnalyticsView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - windowHours
        - freshness
        - items
      properties:
        chainId:
          type: string
        windowHours:
          type: integer
          format: int64
        freshness:
          $ref: "#/components/schemas/AnalyticsFreshnessView"
        items:
          type: array
          items:
            $ref: "#/components/schemas/WrapperAnalyticsItemView"
    WrapperTxItemView:
      type: object
      additionalProperties: false
      required:
        - txHash
        - blockNumber
        - txIndex
        - logIndex
        - transferIndex
        - timestampIso
        - tokenAddress
        - symbol
        - name
        - fromAddress
        - toAddress
        - amountRaw
        - amountDecimal
        - amountUsd
      properties:
        txHash:
          type: string
        blockNumber:
          type: integer
          format: int64
        txIndex:
          type: integer
          format: int32
        logIndex:
          type: integer
          format: int32
        transferIndex:
          type: integer
          format: int32
        timestampIso:
          type: string
        tokenAddress:
          type: string
        symbol:
          type: string
        name:
          type: string
        fromAddress:
          type:
            - string
            - "null"
        toAddress:
          type:
            - string
            - "null"
        amountRaw:
          type:
            - string
            - "null"
        amountDecimal:
          type:
            - string
            - "null"
        amountUsd:
          type:
            - string
            - "null"
    WrapperTxPageView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - tokenAddress
        - symbol
        - windowHours
        - freshness
        - items
        - nextCursor
      properties:
        chainId:
          type: string
        tokenAddress:
          type: string
        symbol:
          type: string
        windowHours:
          type: integer
          format: int64
        freshness:
          $ref: "#/components/schemas/AnalyticsFreshnessView"
        items:
          type: array
          items:
            $ref: "#/components/schemas/WrapperTxItemView"
        nextCursor:
          type:
            - string
            - "null"
    NetflowPointView:
      type: object
      additionalProperties: false
      required:
        - bucketStartIso
        - grossInUsd
        - grossOutUsd
        - netUsd
        - grossInCount
        - grossOutCount
      properties:
        bucketStartIso:
          type: string
        grossInUsd:
          type: string
        grossOutUsd:
          type: string
        netUsd:
          type: string
        grossInCount:
          type: integer
          format: int64
        grossOutCount:
          type: integer
          format: int64
    NetflowAssetView:
      type: object
      additionalProperties: false
      required:
        - tokenAddress
        - symbol
        - grossInUsd
        - grossOutUsd
        - netUsd
        - grossInCount
        - grossOutCount
      properties:
        tokenAddress:
          type: string
        symbol:
          type: string
        grossInUsd:
          type: string
        grossOutUsd:
          type: string
        netUsd:
          type: string
        grossInCount:
          type: integer
          format: int64
        grossOutCount:
          type: integer
          format: int64
    NetflowSeriesView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - windowHours
        - granularity
        - freshness
        - totals
        - items
      properties:
        chainId:
          type: string
        windowHours:
          type: integer
          format: int64
        granularity:
          type: string
        freshness:
          $ref: "#/components/schemas/AnalyticsFreshnessView"
        totals:
          $ref: "#/components/schemas/NetflowPointView"
        items:
          type: array
          items:
            $ref: "#/components/schemas/NetflowPointView"
    NetflowAssetsView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - windowHours
        - freshness
        - totals
        - assets
      properties:
        chainId:
          type: string
        windowHours:
          type: integer
          format: int64
        freshness:
          $ref: "#/components/schemas/AnalyticsFreshnessView"
        totals:
          $ref: "#/components/schemas/NetflowPointView"
        assets:
          type: array
          items:
            $ref: "#/components/schemas/NetflowAssetView"
x-mezcal-audience: protocol-extension
tags:
  - name: Bridge analytics