openapi: 3.0.3
info:
  title: Signer Metrics Accounts Signers API
  description: Welcome to the API reference overview for the Signer Metrics API.
  version: 1.0.3
servers:
- url: https://api.hiro.so/
  description: mainnet
- url: https://api.testnet.hiro.so/
  description: testnet
tags:
- name: Signers
paths:
  /signer-metrics/v1/cycles/{cycle_number}/signers:
    get:
      operationId: getPoxCycleSigners
      summary: PoX Cycle Signers
      tags:
      - Signers
      description: List of signers for a given PoX cycle
      parameters:
      - schema:
          type: string
        in: query
        name: from
        required: false
        description: Start of time range (e.g., now-2h or ISO timestamp)
      - schema:
          type: string
        in: query
        name: to
        required: false
        description: End of time range (e.g., now or ISO timestamp)
      - schema:
          type: integer
          default: 100
        in: query
        name: limit
        required: true
        description: 'Number of results to return (default: 100)'
      - schema:
          type: integer
          default: 0
        in: query
        name: offset
        required: true
        description: 'Number of results to skip (default: 0)'
      - schema:
          type: integer
        in: path
        name: cycle_number
        required: true
        description: PoX cycle number
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - total
                - limit
                - offset
                - results
                properties:
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
                  results:
                    type: array
                    items:
                      type: object
                      required:
                      - signer_key
                      - slot_index
                      - weight
                      - weight_percentage
                      - stacked_amount
                      - stacked_amount_percent
                      - stacked_amount_rank
                      - proposals_accepted_count
                      - proposals_rejected_count
                      - proposals_missed_count
                      - average_response_time_ms
                      - last_seen
                      - version
                      properties:
                        signer_key:
                          type: string
                        slot_index:
                          description: Index of the signer in the stacker set
                          type: integer
                        weight:
                          description: Voting weight of this signer (based on slots allocated which is proportional to stacked amount)
                          type: integer
                        weight_percentage:
                          description: Voting weight percent (weight / total_weight)
                          type: number
                        stacked_amount:
                          description: Total STX stacked associated with this signer (string quoted integer)
                          type: string
                        stacked_amount_percent:
                          description: Stacked amount percent (stacked_amount / total_stacked_amount)
                          type: number
                        stacked_amount_rank:
                          description: This signer's rank in the list of all signers (for this cycle) ordered by stacked amount
                          type: integer
                        proposals_accepted_count:
                          description: Number of block proposals accepted by this signer
                          type: integer
                        proposals_rejected_count:
                          description: Number of block proposals rejected by this signer
                          type: integer
                        proposals_missed_count:
                          description: Number of block proposals missed by this signer
                          type: integer
                        average_response_time_ms:
                          description: Time duration (in milliseconds) taken to submit responses to block proposals (tracked best effort)
                          type: number
                        last_seen:
                          description: ISO timestamp of the last time a message from this signer was seen
                          anyOf:
                          - type: string
                          - type: 'null'
                        version:
                          description: The last seen signer binary version reported by this signer
                          anyOf:
                          - type: string
                          - type: 'null'
  /signer-metrics/v1/cycles/{cycle_number}/signers/{signer_id}:
    get:
      operationId: getPoxCycleSigner
      summary: PoX Cycle Signer
      tags:
      - Signers
      description: Get stats for a specific signer in a given PoX cycle
      parameters:
      - schema:
          type: integer
        in: path
        name: cycle_number
        required: true
        description: PoX cycle number
      - schema:
          type: string
        in: path
        name: signer_id
        required: true
        description: Signer public key (hex encoded)
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - signer_key
                - slot_index
                - weight
                - weight_percentage
                - stacked_amount
                - stacked_amount_percent
                - stacked_amount_rank
                - proposals_accepted_count
                - proposals_rejected_count
                - proposals_missed_count
                - average_response_time_ms
                - last_seen
                - version
                properties:
                  signer_key:
                    type: string
                  slot_index:
                    description: Index of the signer in the stacker set
                    type: integer
                  weight:
                    description: Voting weight of this signer (based on slots allocated which is proportional to stacked amount)
                    type: integer
                  weight_percentage:
                    description: Voting weight percent (weight / total_weight)
                    type: number
                  stacked_amount:
                    description: Total STX stacked associated with this signer (string quoted integer)
                    type: string
                  stacked_amount_percent:
                    description: Stacked amount percent (stacked_amount / total_stacked_amount)
                    type: number
                  stacked_amount_rank:
                    description: This signer's rank in the list of all signers (for this cycle) ordered by stacked amount
                    type: integer
                  proposals_accepted_count:
                    description: Number of block proposals accepted by this signer
                    type: integer
                  proposals_rejected_count:
                    description: Number of block proposals rejected by this signer
                    type: integer
                  proposals_missed_count:
                    description: Number of block proposals missed by this signer
                    type: integer
                  average_response_time_ms:
                    description: Time duration (in milliseconds) taken to submit responses to block proposals (tracked best effort)
                    type: number
                  last_seen:
                    description: ISO timestamp of the last time a message from this signer was seen
                    anyOf:
                    - type: string
                    - type: 'null'
                  version:
                    description: The last seen signer binary version reported by this signer
                    anyOf:
                    - type: string
                    - type: 'null'
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
                    description: Error message when signer is not found
  /v3/stacker_set/{cycle_number}:
    get:
      summary: Fetch the stacker and signer set information for a given cycle.
      tags:
      - Signers
      security: []
      operationId: getStackerSet
      description: 'Used to get stacker and signer set information for a given cycle.


        This will only return information for cycles started in Epoch-2.5

        where PoX-4 was active and subsequent cycles.

        '
      parameters:
      - name: cycle_number
        in: path
        required: true
        description: reward cycle number
        schema:
          type: integer
      - $ref: ./components/parameters/tip.yaml
      responses:
        '200':
          description: Information for the given reward cycle
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStackerSet'
              examples:
                stacker-set:
                  $ref: ./components/examples/get-stacker-set.example.json
        '400':
          description: Could not fetch the given reward set
          content:
            application/json:
              schema:
                type: object
                required:
                - response
                - err_msg
                properties:
                  response:
                    type: string
                    enum:
                    - error
                    description: Response status
                  err_type:
                    type: string
                    description: Error type classification
                  err_msg:
                    type: string
                    description: Detailed error message
              examples:
                stacker-set-error:
                  $ref: ./components/examples/get-stacker-set-400.example.json
        '404':
          description: Reward cycle not found or does not exist
          content:
            text/plain:
              schema:
                type: string
              example: No such file or directory
  /v3/signer/{signer_pubkey}/{cycle_number}:
    get:
      summary: Get number of blocks signed by signer during a given reward cycle
      tags:
      - Signers
      security: []
      operationId: getSignerBlocksSigned
      description: Get number of blocks signed by signer during a given reward cycle
      parameters:
      - name: signer_pubkey
        in: path
        required: true
        description: Hex-encoded compressed Secp256k1 public key of signer
        schema:
          type: string
          pattern: ^0[23][0-9a-f]{64}$
      - name: cycle_number
        in: path
        required: true
        description: Reward cycle number
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: Number of blocks signed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignerBlocksSigned'
              example:
                blocks_signed: 7
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    GetStackerSet:
      $ref: ./components/schemas/get-stacker-set.schema.yaml
    SignerBlocksSigned:
      $ref: ./components/schemas/signer-blocks-signed.schema.yaml
  responses:
    NotFound:
      description: Not found
      content:
        text/plain:
          schema:
            type: string
          example: Not found
    InternalServerError:
      description: Internal Server Error
      content:
        text/plain:
          schema:
            type: string
          example: Internal Server Error
    BadRequest:
      description: Bad request
      content:
        text/plain:
          schema:
            type: string
          example: Bad request
externalDocs:
  url: https://github.com/hirosystems/signer-metrics-api
  description: Source Repository