openapi: 3.0.3
info:
  title: Kryptex Pool API
  version: "1"
servers:
  - url: https://pool.kryptex.com
tags:
  - name: Pool
  - name: Miner
  - name: Coin
  - name: Network

paths:
  /{coin}/api/v1/pool/info:
    get:
      tags: [Pool]
      summary: Pool info
      parameters:
        - $ref: "#/components/parameters/Coin"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PoolStats"

  /{coin}/api/v1/pool/hashrate:
    get:
      tags: [Pool]
      summary: Pool hashrate history
      parameters:
        - $ref: "#/components/parameters/Coin"
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/HashratePoint"

  /{coin}/api/v1/pool/topminers:
    get:
      tags: [Pool]
      summary: Top miners leaderboard
      parameters:
        - $ref: "#/components/parameters/Coin"
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TopMiner"

  /{coin}/api/v1/pool/topsoftware:
    get:
      tags: [Pool]
      summary: Top mining software
      parameters:
        - $ref: "#/components/parameters/Coin"
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TopSoftware"

  /{coin}/api/v1/miner/chart/{address}:
    get:
      tags: [Miner]
      summary: Miner hashrate chart
      parameters:
        - $ref: "#/components/parameters/Coin"
        - $ref: "#/components/parameters/Address"
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/HashratePoint"

  /{coin}/api/v1/miner/chart/{address}/{worker}:
    get:
      tags: [Miner]
      summary: Worker hashrate chart
      parameters:
        - $ref: "#/components/parameters/Coin"
        - $ref: "#/components/parameters/Address"
        - $ref: "#/components/parameters/Worker"
        - $ref: "#/components/parameters/Days"
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WorkerChartPoint"

  /{coin}/api/v1/miner/chart/{address}/{worker}/{scheme}:
    get:
      tags: [Miner]
      summary: Worker chart by scheme
      parameters:
        - $ref: "#/components/parameters/Coin"
        - $ref: "#/components/parameters/Address"
        - $ref: "#/components/parameters/Worker"
        - $ref: "#/components/parameters/Scheme"
        - $ref: "#/components/parameters/Days"
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WorkerChartPoint"

  /{coin}/api/v1/miner/balance/{address}:
    get:
      tags: [Miner]
      summary: Miner balance
      parameters:
        - $ref: "#/components/parameters/Coin"
        - $ref: "#/components/parameters/Address"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Balance"

  /{coin}/api/v1/miner/payouts/{address}:
    get:
      tags: [Miner]
      summary: Payout history
      parameters:
        - $ref: "#/components/parameters/Coin"
        - $ref: "#/components/parameters/Address"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedPayouts"

  /{coin}/api/v1/miner/payouts/{address}/stats:
    get:
      tags: [Miner]
      summary: Payout stats
      parameters:
        - $ref: "#/components/parameters/Coin"
        - $ref: "#/components/parameters/Address"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayoutStats"

  /{coin}/api/v1/miner/payouts/{address}/csv:
    get:
      tags: [Miner]
      summary: Payout history as CSV
      parameters:
        - $ref: "#/components/parameters/Coin"
        - $ref: "#/components/parameters/Address"
      responses:
        "200":
          content:
            text/csv:
              schema:
                type: string

  /{coin}/api/v1/miner/blocks/{address}:
    get:
      tags: [Miner]
      summary: Miner blocks
      parameters:
        - $ref: "#/components/parameters/Coin"
        - $ref: "#/components/parameters/Address"
        - name: scheme
          in: query
          required: false
          schema:
            type: string
            example: solo
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedMinerBlocks"

  /{coin}/api/v1/miner/settings/{address}:
    get:
      tags: [Miner]
      summary: Get miner settings
      parameters:
        - $ref: "#/components/parameters/Coin"
        - $ref: "#/components/parameters/Address"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MinerSettings"
    post:
      tags: [Miner]
      summary: Update miner settings
      parameters:
        - $ref: "#/components/parameters/Coin"
        - $ref: "#/components/parameters/Address"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MinerSettingsUpdate"
      responses:
        "200": {}
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items: { type: string }
                example:
                  errors:
                    threshold:
                      - "Enter a number."
                    ip_address:
                      - "Enter a valid IPv4 address."
        "403": {}

  /{coin}/api/v1/miner/reward-chart/{address}:
    get:
      tags: [Miner]
      summary: 31-day reward chart
      parameters:
        - $ref: "#/components/parameters/Coin"
        - $ref: "#/components/parameters/Address"
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RewardPoint"

  /{coin}/api/v3/miner/workers/{address}:
    get:
      tags: [Miner]
      summary: Active workers (v3)
      parameters:
        - $ref: "#/components/parameters/Coin"
        - $ref: "#/components/parameters/Address"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedWorkers"

  /api/v1/coin/{coin}/info:
    get:
      tags: [Coin]
      summary: Coin metadata
      parameters:
        - $ref: "#/components/parameters/Coin"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CoinInfo"

  /api/v1/coin/{coin}/price/chart:
    get:
      tags: [Coin]
      summary: Coin price chart
      parameters:
        - $ref: "#/components/parameters/Coin"
        - name: time_range
          in: query
          required: true
          schema:
            type: string
            enum: [day, week, month, year]
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PricePoint"

  /api/v1/net/stats/{coin}:
    get:
      tags: [Network]
      summary: Network hashrate and difficulty
      parameters:
        - $ref: "#/components/parameters/Coin"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NetStats"

components:
  parameters:
    Coin:
      name: coin
      in: path
      required: true
      schema:
        type: string
        example: btc
    Address:
      name: address
      in: path
      required: true
      schema: { type: string }
    Worker:
      name: worker
      in: path
      required: true
      schema: { type: string }
    Scheme:
      name: scheme
      in: path
      required: true
      schema:
        type: string
        enum: [solo, pps, prop]
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        example: 1
    Days:
      name: days
      in: query
      required: false
      schema: { type: integer }

  schemas:
    Server:
      type: object
      properties:
        host: { type: string }
        port: { type: integer }
        region: { type: string }

    PoolStats:
      type: object
      properties:
        ticker: { type: string }
        name: { type: string }
        hashrate: { type: number }
        miners: { type: integer }
        workers: { type: integer }
        fee_type:
          type: string
          enum: [pps+, prop, solo]
        fee: { type: number }
        minpay: { type: number }
        defpay: { type: number }
        maxpay: { type: number }
        commission: { type: number }
        modes:
          type: array
          items: { type: string }
        nh_force_solo: { type: boolean }
        blocks_for_maturation: { type: integer }
        block_time: { type: number }
        height: { type: integer }
        directMining: { type: boolean }
        servers:
          type: array
          items:
            $ref: "#/components/schemas/Server"

    Block:
      type: object
      properties:
        date: { type: integer }
        height: { type: integer }
        hash: { type: string }
        reward: { type: number }
        status: { type: string }

    MinerBlock:
      allOf:
        - $ref: "#/components/schemas/Block"
        - type: object
          properties:
            worker: { type: string }
            scheme: { type: string }
            miner_effort: { type: number }

    PaginatedBlocks:
      type: object
      properties:
        count: { type: integer }
        results:
          type: array
          items: { $ref: "#/components/schemas/Block" }

    PaginatedMinerBlocks:
      type: object
      properties:
        count: { type: integer }
        results:
          type: array
          items: { $ref: "#/components/schemas/MinerBlock" }

    HashratePoint:
      type: object
      properties:
        timestamp: { type: integer }
        hashrate: { type: number }

    WorkerChartPoint:
      type: object
      properties:
        timestamp: { type: integer }
        hashrate: { type: number }
        shares: { type: number }

    TopMiner:
      type: object
      properties:
        name: { type: string }
        hashrate: { type: number }
        workers: { type: integer }
        is_kryptex: { type: boolean }

    TopSoftware:
      type: object
      properties:
        name: { type: string }
        share: { type: number }

    Balance:
      type: object
      properties:
        total: { type: number }
        threshold: { type: number }
        reached_pct: { type: number }
        unconfirmed: { type: number }
        confirmed: { type: number }

    Payout:
      type: object
      properties:
        date: { type: integer }
        received: { type: number }
        txid: { type: string }
        status: { type: string }

    PaginatedPayouts:
      type: object
      properties:
        count: { type: integer }
        results:
          type: array
          items: { $ref: "#/components/schemas/Payout" }

    PayoutStats:
      type: object
      properties:
        paid: { type: number }
        unpaid: { type: number }
        reward:
          type: object
          properties:
            week: { type: number }
            month: { type: number }

    MinerSettings:
      type: object
      properties:
        threshold: { type: string }

    MinerSettingsUpdate:
      type: object
      required: [threshold, ip_address]
      properties:
        threshold: { type: string }
        ip_address: { type: string }

    RewardPoint:
      type: object
      properties:
        date: { type: integer }
        reward: { type: number }

    Worker:
      type: object
      properties:
        worker: { type: string }
        scheme: { type: string }
        hashrate: { type: number }
        shares: { type: number }
        last_share: { type: integer }

    PaginatedWorkers:
      type: object
      properties:
        count: { type: integer }
        results:
          type: array
          items: { $ref: "#/components/schemas/Worker" }

    CoinInfo:
      type: object
      properties:
        algo: { type: string, example: sha256 }
        launch_year: { type: integer }

    PricePoint:
      type: object
      properties:
        timestamp: { type: integer }
        price: { type: number }

    NetStatsBucket:
      type: array
      items:
        type: object
        properties:
          timestamp: { type: integer }
          net_hashrate: { type: number }
          difficulty: { type: number }

    NetStats:
      type: object
      properties:
        day:   { $ref: "#/components/schemas/NetStatsBucket" }
        week:  { $ref: "#/components/schemas/NetStatsBucket" }
        month: { $ref: "#/components/schemas/NetStatsBucket" }
        year:  { $ref: "#/components/schemas/NetStatsBucket" }