openapi: 3.0.3
info:
  title: Signer Metrics Accounts Info 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: Info
  description: Read-only endpoints to obtain network, Proof-of-Transfer, Stacking, STX token, and node information
paths:
  /extended:
    get:
      operationId: get_status
      summary: API status
      tags:
      - Info
      description: Retrieves the running status of the Stacks Blockchain API, including the server version and current chain tip information.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                title: Api Status Response
                type: object
                properties:
                  server_version:
                    description: the server version that is currently running
                    type: string
                  status:
                    description: the current server status
                    type: string
                  pox_v1_unlock_height:
                    anyOf:
                    - type: integer
                    - type: 'null'
                  pox_v2_unlock_height:
                    anyOf:
                    - type: integer
                    - type: 'null'
                  pox_v3_unlock_height:
                    anyOf:
                    - type: integer
                    - type: 'null'
                  chain_tip:
                    anyOf:
                    - type: object
                      properties:
                        block_height:
                          description: the current block height
                          type: integer
                        block_hash:
                          description: the current block hash
                          type: string
                        index_block_hash:
                          description: the current index block hash
                          type: string
                        microblock_hash:
                          description: the current microblock hash
                          type: string
                        microblock_sequence:
                          description: the current microblock sequence number
                          type: integer
                        burn_block_height:
                          description: the current burn chain block height
                          type: integer
                      required:
                      - block_height
                      - block_hash
                      - index_block_hash
                      - burn_block_height
                    - type: 'null'
                required:
                - server_version
                - status
        4XX:
          description: Default Response
          content:
            application/json:
              schema:
                title: Error Response
                additionalProperties: true
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
  /extended/v1/stx_supply/:
    get:
      operationId: get_stx_supply
      summary: Get total and unlocked STX supply
      tags:
      - Info
      description: Retrieves the total and unlocked STX supply. More information on Stacking can be found [here] (https://docs.stacks.co/block-production/stacking).
      parameters:
      - schema:
          minimum: 0
          title: Block height
          type: integer
        example: 777678
        in: query
        name: height
        required: false
        description: Supply details are queried from specified block height. If the block height is not specified, the latest block height is taken as default value. Note that the `block height` is referred to the stacks blockchain.
      - schema:
          default: false
          type: boolean
        example: true
        in: query
        name: unanchored
        required: false
        description: Include data from unanchored (i.e. unconfirmed) microblocks
      responses:
        '200':
          description: GET request that returns network target block times
          content:
            application/json:
              schema:
                title: GetStxSupplyResponse
                description: GET request that returns network target block times
                type: object
                properties:
                  unlocked_percent:
                    description: String quoted decimal number of the percentage of STX that have unlocked
                    type: string
                  total_stx:
                    description: String quoted decimal number of the total circulating number of STX (at the input block height if provided, otherwise the current block height)
                    type: string
                  total_stx_year_2050:
                    description: String quoted decimal number of total circulating STX supply in year 2050. STX supply grows approx 0.3% annually thereafter in perpetuity.
                    type: string
                  unlocked_stx:
                    description: String quoted decimal number of the STX that have been mined or unlocked
                    type: string
                  block_height:
                    description: The block height at which this information was queried
                    type: integer
                required:
                - unlocked_percent
                - total_stx
                - total_stx_year_2050
                - unlocked_stx
                - block_height
        4XX:
          description: Default Response
          content:
            application/json:
              schema:
                title: Error Response
                additionalProperties: true
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
  /extended/v1/stx_supply/total/plain:
    get:
      operationId: get_stx_supply_total_supply_plain
      summary: Get total STX supply in plain text format
      tags:
      - Info
      description: Retrieves the total circulating STX token supply as plain text.
      deprecated: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    text/plain:
                      type: string
        4XX:
          description: Default Response
          content:
            application/json:
              schema:
                title: Error Response
                additionalProperties: true
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
  /extended/v1/stx_supply/circulating/plain:
    get:
      operationId: get_stx_supply_circulating_plain
      summary: Get circulating STX supply in plain text format
      tags:
      - Info
      description: Retrieves the STX tokens currently in circulation that have been unlocked as plain text.
      deprecated: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    text/plain:
                      type: string
        4XX:
          description: Default Response
          content:
            application/json:
              schema:
                title: Error Response
                additionalProperties: true
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
  /extended/v1/stx_supply/legacy_format:
    get:
      operationId: get_total_stx_supply_legacy_format
      summary: Get total and unlocked STX supply (results formatted the same as the legacy 1.0 API)
      tags:
      - Info
      description: Retrieves total supply of STX tokens including those currently in circulation that have been unlocked.
      parameters:
      - schema:
          minimum: 0
          title: Block height
          type: integer
        example: 777678
        in: query
        name: height
        required: false
        description: Supply details are queried from specified block height. If the block height is not specified, the latest block height is taken as default value. Note that the `block height` is referred to the stacks blockchain.
      - schema:
          default: false
          type: boolean
        example: true
        in: query
        name: unanchored
        required: false
        description: Include data from unanchored (i.e. unconfirmed) microblocks
      deprecated: true
      responses:
        '200':
          description: GET request that returns network target block times
          content:
            application/json:
              schema:
                title: GetStxSupplyLegacyFormatResponse
                description: GET request that returns network target block times
                type: object
                properties:
                  unlockedPercent:
                    description: String quoted decimal number of the percentage of STX that have unlocked
                    type: string
                  totalStacks:
                    description: String quoted decimal number of the total circulating number of STX (at the input block height if provided, otherwise the current block height)
                    type: string
                  totalStacksFormatted:
                    description: Same as `totalStacks` but formatted with comma thousands separators
                    type: string
                  totalStacksYear2050:
                    description: String quoted decimal number of total circulating STX supply in year 2050. STX supply grows approx 0.3% annually thereafter in perpetuity.
                    type: string
                  totalStacksYear2050Formatted:
                    description: Same as `totalStacksYear2050` but formatted with comma thousands separators
                    type: string
                  unlockedSupply:
                    description: String quoted decimal number of the STX that have been mined or unlocked
                    type: string
                  unlockedSupplyFormatted:
                    description: Same as `unlockedSupply` but formatted with comma thousands separators
                    type: string
                  blockHeight:
                    description: The block height at which this information was queried
                    type: string
                required:
                - unlockedPercent
                - totalStacks
                - totalStacksFormatted
                - totalStacksYear2050
                - totalStacksYear2050Formatted
                - unlockedSupply
                - unlockedSupplyFormatted
                - blockHeight
        4XX:
          description: Default Response
          content:
            application/json:
              schema:
                title: Error Response
                additionalProperties: true
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
  /extended/v1/info/network_block_times:
    get:
      operationId: get_network_block_times
      summary: Get the network target block time
      tags:
      - Info
      description: Retrieves the target block times for mainnet and testnet. The block time is hardcoded and will change throughout the implementation phases of the testnet.
      responses:
        '200':
          description: GET request that returns network target block times
          content:
            application/json:
              schema:
                title: NetworkBlockTimesResponse
                description: GET request that returns network target block times
                type: object
                properties:
                  mainnet:
                    type: object
                    properties:
                      target_block_time:
                        type: integer
                    required:
                    - target_block_time
                  testnet:
                    type: object
                    properties:
                      target_block_time:
                        type: integer
                    required:
                    - target_block_time
                required:
                - mainnet
                - testnet
        4XX:
          description: Default Response
          content:
            application/json:
              schema:
                title: Error Response
                additionalProperties: true
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
  /extended/v1/info/network_block_time/{network}:
    get:
      operationId: get_network_block_time_by_network
      summary: Get a given network's target block time
      tags:
      - Info
      description: Retrieves the target block time for a given network. The network can be mainnet or testnet. The block time is hardcoded and will change throughout the implementation phases of the testnet.
      parameters:
      - schema:
          anyOf:
          - type: string
            enum:
            - testnet
          - type: string
            enum:
            - mainnet
        in: path
        name: network
        required: true
      responses:
        '200':
          description: GET request that target block time for a given network
          content:
            application/json:
              schema:
                title: NetworkBlockTimeResponse
                description: GET request that target block time for a given network
                type: object
                properties:
                  target_block_time:
                    type: integer
                required:
                - target_block_time
        4XX:
          description: Default Response
          content:
            application/json:
              schema:
                title: Error Response
                additionalProperties: true
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
  /v2/info:
    get:
      summary: Get Core API info
      description: Get Core API information
      tags:
      - Info
      security: []
      operationId: getNodeInfo
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeInfo'
              examples:
                node-info:
                  $ref: ./components/examples/node-info.example.json
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/pox:
    get:
      summary: Get PoX details
      description: Get Proof of Transfer (PoX) information. Can be used for Stacking.
      tags:
      - Info
      security: []
      operationId: getPoxInfo
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PoxInfo'
              examples:
                pox-info:
                  $ref: ./components/examples/pox-info.example.json
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
      - $ref: ./components/parameters/tip.yaml
  /v3/health:
    get:
      summary: Query the health of the node.
      description: 'Get node health information.

        A node is considered healthy if its Stacks tip height matches the maximum Stacks tip height observed among its connected peers.

        This endpoint returns:

        - `difference_from_max_peer`: The difference in Stacks height between this node and its most advanced peer.

        - `max_stacks_height_of_neighbors`: The maximum Stacks height observed among the node"s connected peers.

        - `node_stacks_tip_height`: The current Stacks tip height of this node.

        - `max_stacks_neighbor_address`: The address of the most advanced peer. Null if no peer data is available.

        '
      tags:
      - Info
      security: []
      operationId: getNodeHealth
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetHealth'
              examples:
                node-health:
                  $ref: ./components/examples/node-health.example.json
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/neighbors:
    get:
      summary: Get neighbor peers
      tags:
      - Info
      security: []
      operationId: getNetworkPeers
      description: 'Get information about the node"s neighbor peers in the network.

        '
      responses:
        '200':
          description: List of neighbor peers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkPeers'
              examples:
                network-peers:
                  $ref: ./components/examples/network-peers.example.json
components:
  schemas:
    PoxInfo:
      $ref: ./components/schemas/pox-info.schema.yaml
    GetHealth:
      $ref: ./components/schemas/get-health.schema.yaml
    NetworkPeers:
      $ref: ./components/schemas/network-peers.schema.yaml
    NodeInfo:
      $ref: ./components/schemas/node-info.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