openapi: 3.1.0
info:
  title: Gated Alpha API
  version: 1.0.0
  description: Agent-first crypto alpha marketplace with X402 pay-per-call access.
servers:
  - url: https://api.gatedalpha.market
paths:
  /groups:
    get:
      summary: List active alpha groups
      parameters:
        - in: query
          name: chain
          schema:
            type: string
        - in: query
          name: category
          schema:
            type: string
        - in: query
          name: sort
          schema:
            type: string
            enum: [group_score, price, volume]
            default: group_score
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Group listing
  /leaderboard:
    get:
      summary: Top groups ranked by group score
      parameters:
        - in: query
          name: period
          schema:
            type: string
            enum: [24h, 7d, 30d]
            default: 30d
        - in: query
          name: chain
          schema:
            type: string
      responses:
        '200':
          description: Leaderboard response
  /alpha/latest:
    get:
      summary: Latest alpha previews
      parameters:
        - in: query
          name: chain
          schema:
            type: string
        - in: query
          name: category
          schema:
            type: string
        - in: query
          name: min_group_score
          schema:
            type: integer
            minimum: 0
            maximum: 100
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Preview list
  /alpha/{id}:
    get:
      summary: Retrieve full alpha payload for a call
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Full paid alpha payload
        '402':
          description: X402 payment required
components:
  schemas:
    AlphaPreview:
      type: object
      required: [id, preview, available_at]
      properties:
        id:
          type: string
        available_at:
          type: string
          format: date-time
        preview:
          type: object
          required: [group_id, group_name, group_score, chain, category, price_usdc]
          properties:
            group_id:
              type: string
            group_name:
              type: string
            group_score:
              type: integer
              minimum: 0
              maximum: 100
            group_reputation:
              type: integer
              minimum: 0
              maximum: 100
            chain:
              type: string
            category:
              type: string
            mcap_range:
              type: string
            risk_level:
              type: string
            confidence:
              type: number
            price_usdc:
              type: number
