openapi: 3.0.3
info:
  title: Hyperflow API
  description: "The Hyperflow API provides endpoints to retrieve leaderboard data, 
    transaction volumes, points, and partner bonuses for users."
  version: 1.0.0
  contact:
    name: Hyperflow API Support
    url: https://hyperflow.fun

servers:
  - url: https://api.hyperflow.fun
    description: Production server

paths:
  /v1/point/leaderboard:
    get:
      summary: Retrieve the points leaderboard
      description: "Returns leaderboard statistics, including transaction volume, 
        number of transactions, and earned points across swap, bridge, 
        and referral activities.  
        Partner bonuses are also included where applicable."
      operationId: getLeaderboard
      responses:
        "200":
          description: Successfully retrieved leaderboard data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LeaderboardResponse"
        "400":
          description: Bad request – Invalid query parameters
        "500":
          description: Internal server error

  /v1/point/estimate:
    get:
      summary: Estimate transaction points
      description: "Returns an estimate of the points a user would earn for a given transaction,  
        including both the system-awarded base points and any applicable partner bonuses."
      operationId: estimatePoints
      parameters:
        - name: user
          in: query
          description: Wallet address of the user.
          required: true
          schema:
            type: string
            example: "0xBc1E58631301a25ce1E4BF0677eF034882945597"
        - name: src_chain
          in: query
          description: Source chain identifier.
          required: true
          schema:
            type: string
            example: "hyperevm"
        - name: src_token
          in: query
          description: Address of the source token.
          required: true
          schema:
            type: string
            example: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
        - name: src_usd
          in: query
          description: USD equivalent of the source amount.
          required: true
          schema:
            type: number
            format: double
            example: 56.17255091488022
        - name: dst_chain
          in: query
          description: Destination chain identifier.
          required: true
          schema:
            type: string
            example: "hyperevm"
        - name: dst_token
          in: query
          description: Address of the destination token.
          required: true
          schema:
            type: string
            example: "0x5d3a1Ff2b6BAb83b63cd9AD0787074081a52ef34"
        - name: dst_usd
          in: query
          description: USD equivalent of the destination amount.
          required: true
          schema:
            type: number
            format: double
            example: 56.100707979020115
        - name: from
          in: query
          description: >
            Fixed timestamp used for point estimation.  
            Always corresponds to **10 July 2025 (Unix: 1752105600)**.  
            This value should be passed exactly as specified.
          required: true
          schema:
            type: integer
            example: 1752105600
        - name: source
          in: query
          description: "Partner code used to attribute the transaction to a specific partner.  
            This code must match one of the partner identifiers defined by the system."
          required: false
          schema:
            type: string
            example: "blabsteam"
      responses:
        "200":
          description: Successfully estimated points
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PointEstimateResponse"
        "400":
          description: Bad request – Invalid query parameters
        "500":
          description: Internal server error

  /ai/messages:
    post:
      summary: Send conversation messages to the AI and receive a response
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                messages:
                  type: array
                  maxItems: 7
                  description: The latest 6 messages in the conversation (user ↔ assistant) and a new question of user.
                  items:
                    $ref: '#/components/schemas/Message'
              example:
                messages:
                  - type: user
                    content: "I have 1000 usd, I like eth and it's bluechip tokens, I like medium strategy. Please make investment advice?"
                  - type: assistant
                    content: "{\"type\":\"suggest\",\"message\":\"For your investment...\",\"data\":{\"suggestData\":{\"pool_ids\":[\"6\",\"4\",\"15\"],\"allocations\":[400,400,200]}}}"
                  - type: user
                    content: "how are you?"
      responses:
        '200':
          description: AI response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiResponse'
              example:
                type: chat
                message: "I'm just a computer program, but I'm here to help you with your DeFi investments! How can I assist you further?"
                data:
                  suggestData:
                    pool_ids: null
                    allocations: [ ]
                    farms: [ ]
                    tokens: { }
                raw: "{\"type\":\"chat\",\"message\":\"I'm just a computer program...\",\"data\":{\"suggestData\":{\"pool_ids\":[],\"allocations\":[]}}}"

components:
  schemas:
    LeaderboardResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total number of leaderboard entries returned.
          example: 1687
        items:
          type: array
          description: List of leaderboard items.
          items:
            $ref: "#/components/schemas/LeaderboardItem"
        total:
          $ref: "#/components/schemas/StatsTotal"

    LeaderboardItem:
      type: object
      properties:
        user:
          type: string
          description: Wallet address of the user.
          example: "0x279f7364049B22Bb8A456532250c473e7b491619"
        swap:
          $ref: "#/components/schemas/StatsSwap"
        bridge:
          $ref: "#/components/schemas/StatsBridge"
        referral:
          $ref: "#/components/schemas/StatsReferral"
        total:
          $ref: "#/components/schemas/StatsTotal"
        offsetPoint:
          type: integer
          description: "One-time bonus points granted when the user interacts with a specific 
            system function for the first time. This reward is only applied once 
            per function and contributes to the user’s total points."
          example: 100

    StatsSwap:
      type: object
      description: Swap-related statistics.
      properties:
        volumeUsd:
          type: number
          format: double
          example: 1810828.249344356
        txs:
          type: integer
          example: 40
        point:
          type: integer
          description: "The number of points a user receives from swap action.
            This value does **not** include partner bonuses.  
            Any additional rewards from partners are listed separately 
            in `pointPartnerBonuses`."
          example: 22538530
        pointPartnerBonuses:
          $ref: "#/components/schemas/PointPartnerBonuses"

    StatsBridge:
      type: object
      description: Bridge-related statistics.
      properties:
        volumeUsd:
          type: number
          format: double
          example: 2196.023438551416
        txs:
          type: integer
          example: 2
        point:
          type: integer
          description: "The number of points a user receives from bridge action."
          example: 79737

    StatsReferral:
      type: object
      description: Referral-related statistics.
      properties:
        point:
          type: integer
          description: "The number of points a user receives from referral action."
          example: 12870

    StatsTotal:
      type: object
      description: Aggregated statistics across all categories.
      properties:
        volumeUsd:
          type: number
          format: double
          example: 1813024.2727829074
        txs:
          type: integer
          example: 42
        point:
          type: integer
          description: "The total of points a user receives from actions (swap, bridge, referral, etc.).
            This value does **not** include partner bonuses.  
            Any additional rewards from partners are listed separately 
            in `pointPartnerBonuses`."
          example: 22631237
        pointPartnerBonuses:
          $ref: "#/components/schemas/PointPartnerBonuses"

    PointPartnerBonuses:
      type: object
      description: >
        Mapping of **partner codes** to the bonus points they awarded.  
        Each field name is a partner code, and the value is the number of bonus points.  
        Example:  
        ```json
        {
          "blabsteam": 100,
          "partnerX": 250
        }
        ```
      additionalProperties:
        type: integer
      example:
        blabsteam: 100

    PointEstimateResponse:
      type: object
      properties:
        partnerBonus:
          type: integer
          description: "Additional bonus points awarded via the specified partner (if applicable)."
          example: 140
        point:
          type: integer
          description: "Base points the user would receive for this transaction, excluding partner bonuses."
          example: 280

    Message:
      type: object
      properties:
        type:
          type: string
          enum: [ user, assistant ]
          description: |
            - `user`: User's message  
            - `assistant`: Raw response from the AI (from previous request)
        content:
          type: string
          description: Message content or raw AI response

    AiResponse:
      type: object
      properties:
        type:
          type: string
          enum: [ chat, suggest ]
          description: Response type
        message:
          type: string
          description: Human-readable message returned by the AI
        data:
          type: object
          properties:
            suggestData:
              $ref: '#/components/schemas/SuggestData'
        raw:
          type: string
          description: Raw response string from AI

      SuggestData:
        type: object
        properties:
          allocations:
            type: array
            items:
              type: number
          farms:
            type: array
            items:
              type: object
          tokens:
            type: object
