openapi: 3.2.0
info:
  title: Gala DeFi Backend Explore API
  description: OpenAPI reference for DeFi backend endpoints.
  version: 0.0.1
  contact: {}
servers: []
tags:
- name: explore
  description: ''
paths:
  /explore/volume:
    get:
      description: Get volume details for the protocol.
      operationId: ExploreController_volumeDetails
      parameters: []
      responses:
        '200':
          description: ''
      summary: Get volume details
      tags:
      - explore
  /explore/pools:
    get:
      description: Get details of all liquidity pools.
      operationId: ExploreController_poolsDetails
      parameters:
      - name: sortBy
        required: false
        in: query
        description: Sort by field
        schema:
          example: tvl
          type: string
          enum:
          - tvl
          - volume30d
          - volume1d
      - name: sortOrder
        required: false
        in: query
        description: Sort order
        schema:
          example: desc
          type: string
          enum:
          - asc
          - desc
      - name: search
        required: false
        in: query
        description: Search term for filtering pools
        schema:
          maxLength: 64
          example: GALA
          type: string
      - name: page
        required: true
        in: query
        description: Page number for pagination (starts at 1)
        schema:
          minimum: 1
          example: 1
          type: number
      - name: limit
        required: true
        in: query
        description: Maximum number of pools to return per page
        schema:
          minimum: 1
          maximum: 1000
          example: 10
          type: number
      responses:
        '200':
          description: ''
      summary: Get pools details
      tags:
      - explore
  /explore/opportunities:
    get:
      description: 'Authoritative "best opportunities" feed: pools carrying a distinguishing bot-ready signal, ranked by composite opportunityScore (desc), plus any campaign-boosted pools. Top-N only — no pagination.'
      operationId: ExploreController_opportunities
      parameters:
      - name: limit
        required: false
        in: query
        description: Maximum ranked pools to return (1-100, default 20)
        schema:
          minimum: 1
          maximum: 100
          example: 20
          type: number
      responses:
        '200':
          description: ''
      summary: Get ranked opportunity pools
      tags:
      - explore
  /explore/pool:
    get:
      description: Get details of a specific pool by its hash.
      operationId: ExploreController_poolDetailByHash
      parameters:
      - name: poolHash
        required: true
        in: query
        description: The 64-character hexadecimal hash identifying the pool
        schema:
          minLength: 64
          maxLength: 64
          pattern: ^(0x|0h)?[0-9A-F]+$
          example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
          type: string
      responses:
        '200':
          description: ''
      summary: Get pool details by hash
      tags:
      - explore
  /explore/transactions:
    get:
      description: Get a list of transactions.
      operationId: ExploreController_transactionsDetails
      parameters:
      - name: limit
        required: true
        in: query
        description: Maximum number of transactions to return per page
        schema:
          minimum: 1
          example: 10
          type: number
      - name: page
        required: true
        in: query
        description: Page number for pagination (starts at 1)
        schema:
          minimum: 1
          example: 1
          type: number
      - name: poolHash
        required: false
        in: query
        description: The 64-character hexadecimal hash identifying the pool (optional)
        schema:
          minLength: 64
          maxLength: 64
          pattern: ^(0x|0h)?[0-9A-F]+$
          example: 632e14d63876b38674ec7944ebad71f31857412305abba8b2adb921c92f90b2a
          type: string
      responses:
        '200':
          description: ''
      summary: Get transactions details
      tags:
      - explore
  /explore/graph-data:
    get:
      description: Get graph data for a specific period.
      operationId: ExploreController_graphData
      parameters:
      - name: actualDate
        required: true
        in: query
        description: The reference date for the graph data (ISO 8601 format)
        schema:
          example: '2026-01-26T18:18:27.115Z'
          type: string
      - name: duration
        required: true
        in: query
        description: The time period for the graph data
        schema:
          enum:
          - 1d
          - 1w
          - 1M
          - 1y
          type: string
      - name: poolHash
        required: true
        in: query
        description: The 64-character hexadecimal hash identifying the pool
        schema:
          minLength: 64
          maxLength: 64
          pattern: ^(0x|0h)?[0-9A-F]+$
          example: 632e14d63876b38674ec7944ebad71f31857412305abba8b2adb921c92f90b2a
          type: string
      responses:
        '200':
          description: ''
      summary: Get graph data for a period
      tags:
      - explore
components:
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Required for admin endpoints protected by ApiKeyGuard.