Hiro Signer Metrics API
REST API to monitor and analyze signer behavior and performance on the Stacks Nakamoto network.
OpenAPI Specification
openapi: 3.0.3
info:
title: Signer Metrics API
description: Welcome to the API reference overview for the Signer Metrics API.
version: 1.0.3
components:
schemas: {}
paths:
/signer-metrics/:
get:
operationId: getApiStatus
summary: API Status
tags:
- Status
description: Displays the status of the API and its current workload
responses:
"200":
description: Default Response
content:
application/json:
schema:
title: Api Status Response
type: object
required:
- server_version
- status
- chain_tip
properties:
server_version:
type: string
example: signer-metrics-api v0.0.1 (master:a1b2c3)
status:
type: string
example: ready
chain_tip:
type: object
required:
- block_height
- index_block_hash
properties:
block_height:
type: integer
example: 163541
index_block_hash:
type: string
example: "0x1234567890abcdef"
/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
/signer-metrics/v1/blocks:
get:
operationId: getBlocks
summary: Aggregated signer information for most recent blocks
tags:
- Blocks
description: Aggregated signer information for most recent blocks
parameters:
- schema:
type: integer
default: 100
in: query
name: limit
required: true
description: Number of results to return
- schema:
type: integer
default: 0
in: query
name: offset
required: true
description: Number of results to skip
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:
- block_height
- block_hash
- block_time
- index_block_hash
- burn_block_height
- tenure_height
- signer_data
properties:
block_height:
type: integer
block_hash:
type: string
block_time:
description: Unix timestamp in seconds of when the block was mined
type: integer
index_block_hash:
type: string
burn_block_height:
type: integer
tenure_height:
type: integer
signer_data:
description: Signer data can by null if it was not detected by the metrics
service
anyOf:
- type: object
required:
- cycle_number
- total_signer_count
- accepted_count
- rejected_count
- missing_count
- accepted_excluded_count
- average_response_time_ms
- block_proposal_time_ms
- accepted_stacked_amount
- rejected_stacked_amount
- missing_stacked_amount
- accepted_weight
- rejected_weight
- missing_weight
properties:
cycle_number:
type: integer
total_signer_count:
description: Total number of signers expected for this block
type: integer
accepted_count:
description: Number of signers that submitted an approval for this block
type: integer
rejected_count:
description: Number of signers that submitted a rejection for this block
type: integer
missing_count:
description: Number of signers that failed to submit any response/vote for this
block
type: integer
accepted_excluded_count:
description: Number of signers that submitted an approval but where not included
in time by the miner (this is a subset of
the accepted_count)
type: integer
average_response_time_ms:
description: Average time duration (in milliseconds) taken by signers to submit
a response for this block (tracked best
effort)
type: number
block_proposal_time_ms:
description: Unix timestamp in milliseconds of when the block was first proposed
(tracked best effort)
type: number
accepted_stacked_amount:
description: Sum of total STX stacked of signers who approved the block
type: string
rejected_stacked_amount:
description: Sum of total STX stacked of signers who rejected the block
type: string
missing_stacked_amount:
description: Sum of total STX stacked of missing signers
type: string
accepted_weight:
description: Sum of voting weight of signers who approved the block (based on
slots allocated to each signer proportional
to stacked amount)
type: integer
rejected_weight:
description: Sum of voting weight of signers who rejected the block
type: integer
missing_weight:
description: Sum of voting weight of missing signers
type: integer
- type: "null"
/signer-metrics/v1/blocks/{height_or_hash}:
get:
operationId: getBlock
summary: Aggregated signer information for a block
tags:
- Blocks
description: Aggregated signer information for a block
parameters:
- schema:
anyOf:
- type: string
enum:
- latest
- pattern: ^(0x)?[a-fA-F0-9]{64}$
title: Block hash
description: Block hash
examples:
- "0xdaf79950c5e8bb0c620751333967cdd62297137cdaf79950c5e8bb0c\
62075133"
type: string
- title: Block height
description: Block height
examples:
- 777678
type: integer
in: path
name: height_or_hash
required: true
responses:
"200":
description: Default Response
content:
application/json:
schema:
type: object
required:
- block_height
- block_hash
- block_time
- index_block_hash
- burn_block_height
- tenure_height
- signer_data
properties:
block_height:
type: integer
block_hash:
type: string
block_time:
description: Unix timestamp in seconds of when the block was mined
type: integer
index_block_hash:
type: string
burn_block_height:
type: integer
tenure_height:
type: integer
signer_data:
description: Signer data can by null if it was not detected by the metrics
service
anyOf:
- type: object
required:
- cycle_number
- total_signer_count
- accepted_count
- rejected_count
- missing_count
- accepted_excluded_count
- average_response_time_ms
- block_proposal_time_ms
- accepted_stacked_amount
- rejected_stacked_amount
- missing_stacked_amount
- accepted_weight
- rejected_weight
- missing_weight
properties:
cycle_number:
type: integer
total_signer_count:
description: Total number of signers expected for this block
type: integer
accepted_count:
description: Number of signers that submitted an approval for this block
type: integer
rejected_count:
description: Number of signers that submitted a rejection for this block
type: integer
missing_count:
description: Number of signers that failed to submit any response/vote for this
block
type: integer
accepted_excluded_count:
description: Number of signers that submitted an approval but where not included
in time by the miner (this is a subset of the
accepted_count)
type: integer
average_response_time_ms:
description: Average time duration (in milliseconds) taken by signers to submit
a response for this block (tracked best effort)
type: number
block_proposal_time_ms:
description: Unix timestamp in milliseconds of when the block was first proposed
(tracked best effort)
type: number
accepted_stacked_amount:
description: Sum of total STX stacked of signers who approved the block
type: string
rejected_stacked_amount:
description: Sum of total STX stacked of signers who rejected the block
type: string
missing_stacked_amount:
description: Sum of total STX stacked of missing signers
type: string
accepted_weight:
description: Sum of voting weight of signers who approved the block (based on
slots allocated to each signer proportional to
stacked amount)
type: integer
rejected_weight:
description: Sum of voting weight of signers who rejected the block
type: integer
missing_weight:
description: Sum of voting weight of missing signers
type: integer
- type: "null"
/signer-metrics/v1/block_proposals:
get:
operationId: getBlockProposals
summary: Signer information for most recent block proposals
tags:
- Blocks Proposals
description: Signer information for most recent block proposals
parameters:
- schema:
type: integer
default: 25
minimum: 1
maximum: 50
in: query
name: limit
required: true
description: Number of results to return
- schema:
type: integer
default: 0
in: query
name: offset
required: true
description: Number of results to skip
responses:
"200":
description: Default Response
content:
application/json:
schema:
type: object
required:
- limit
- offset
- results
properties:
limit:
type: integer
offset:
type: integer
results:
type: array
items:
type: object
required:
- received_at
- block_height
- block_hash
- index_block_hash
- burn_block_height
- block_time
- cycle_number
- status
- push_time_ms
- total_signer_count
- total_signer_weight
- total_signer_stacked_amount
- accepted_count
- rejected_count
- missing_count
- accepted_weight
- rejected_weight
- missing_weight
- signer_data
properties:
received_at:
description: ISO timestamp of when this block proposal was received
type: string
block_height:
type: integer
block_hash:
type: string
index_block_hash:
type: string
burn_block_height:
type: integer
block_time:
description: Unix timestamp in seconds of when the block was mined
type: integer
cycle_number:
type: integer
status:
description: Status of the block proposal
anyOf:
- type: string
enum:
- pending
- type: string
enum:
- accepted
- type: string
enum:
- rejected
push_time_ms:
description: Time duration (in milliseconds) taken between when the block was
proposed and when it was pushed
anyOf:
- type: "null"
- type: integer
total_signer_count:
description: Total number of signers expected for this proposal
type: integer
total_signer_weight:
description: Total voting weight of signers expected for this proposal
type: integer
total_signer_stacked_amount:
description: Total STX stacked of signers expected for this proposal
type: string
accepted_count:
description: Number of signers that submitted an approval for this proposal
type: integer
rejected_count:
description: Number of signers that submitted a rejection for this proposal
type: integer
missing_count:
description: Number of signers that failed to submit any response/vote for this
proposal
type: integer
accepted_weight:
description: Sum of voting weight of signers who approved the proposal
type: integer
rejected_weight:
description: Sum of voting weight of signers who rejected the proposal
type: integer
missing_weight:
description: Sum of voting weight of missing signers
type: integer
signer_data:
type: array
items:
type: object
required:
- signer_key
- slot_index
- response
- weight
- weight_percentage
- stacked_amount
- version
- received_at
- response_time_ms
- reason_string
- reason_code
- reject_code
properties:
signer_key:
type: string
slot_index:
description: Index of the signer in the stacker set
type: integer
response:
anyOf:
- type: string
enum:
- accepted
- type: string
enum:
- rejected
- type: string
enum:
- missing
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
version:
description: The signer binary version reported by this signer for this proposal
response (null if response missing)
anyOf:
- type: string
- type: "null"
received_at:
description: ISO timestamp of when this response was received (null if response
missing
anyOf:
- type: string
- type: "null"
response_time_ms:
description: Time duration (in milliseconds) taken to submit this response
(tracked best effort, null if response
missing)
anyOf:
- type: integer
- type: "null"
reason_string:
description: (For rejection responses) reason string for rejection
anyOf:
- type: string
- type: "null"
reason_code:
description: (For rejection responses) reason code for rejection
anyOf:
- type: string
- type: "null"
reject_code:
description: (For rejection responses) reject code for rejection
anyOf:
- type: string
- type: "null"
/signer-metrics/v1/block_proposals/{block_hash}:
get:
operationId: getBlockProposals
summary: Signer information for most recent block proposals
tags:
- Blocks Proposals
description: Signer information for most recent block proposals
parameters:
- schema:
type: integer
default: 25
minimum: 1
maximum: 50
in: query
name: limit
required: true
description: Number of results to return
- schema:
type: integer
default: 0
in: query
name: offset
required: true
description: Number of resul
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hiro/refs/heads/main/openapi/hiro-signer-metrics-api-openapi.yaml