Info

General informational endpoints about the node.

Get Core API info

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/info

Get Core API information

Responses

200

Success

application/json

GET request for core node information

peer_versionintegerRequired

Identifies the version number for the networking communication. This should not change while a node is running, and will only change if there's an upgrade.

pox_consensusstringRequired

A hash used to identify the burnchain view for a node. It incorporates bitcoin chain information and PoX information. Nodes that disagree on this value will appear to each other as forks. This value changes after every block.

burn_block_heightintegerRequired

Latest bitcoin chain height.

stable_pox_consensusstringRequired

Same as pox_consensus, but evaluated at stable_burn_block_height.

stable_burn_block_heightintegerRequired

The bitcoin block height at which the last PoX anchor block was seen. Leftover from stacks 1.0, basically always burn_block_height - 1.

server_versionstringRequired

A version descriptor for the node.

network_idintegerRequired

Identifies the network (e.g., mainnet, testnet).

parent_network_idintegerRequired

same as network_id, but for bitcoin

stacks_tip_heightintegerRequired

The latest Stacks chain height.

stacks_tipstringRequired

The best known block hash for the Stacks chain.

stacks_tip_consensus_hashstringRequired

The bitcoin consensus hash at the time that stacks_tip was mined.

genesis_chainstate_hashstringRequired

The SHA256 hash of the genesis chainstate.

unanchored_tipstring · nullableOptional

The latest microblock hash if any microblocks were processed. If no microblock has been processed for the current block, a 000.., hex array is returned.

unanchored_seqinteger · nullableOptional

The sequence number of the latest microblock if any microblocks were processed.

tenure_heightintegerRequired

The latest Stacks tenure height.

exit_at_block_heightinteger · nullableOptional

The block height at which a testnet network will be reset. Not applicable to mainnet.

is_fully_syncedbooleanRequired

Indicates whether the node has fully synchronized with the network.

node_public_keystring · nullableOptional

The node's public key.

node_public_key_hashstring · nullableOptional

The HASH160 of the node's public key.

stackerdbsstring[] · nullableOptional

500

Internal Server Error

text/plain

get

/v2/info

HTTPcURLJavaScriptPython

GET /v2/info HTTP/1.1
Host: localhost:20443
Accept: */*

{
  "peer_version": 385875968,
  "pox_consensus": "17f76e597bab45646956f38dd39573085d72cbc0",
  "burn_block_height": 16,
  "stable_pox_consensus": "8e0561978fc5506b68a589c402dad97e862edb59",
  "stable_burn_block_height": 15,
  "server_version": "stacks-node 3.1.0.0.12 (release/3.1.0.0.12:ae969ca+, release build, linux [x86_64])",
  "network_id": 1,
  "parent_network_id": 3652501241,
  "stacks_tip_height": 1832097,
  "stacks_tip": "b1807a2d3f7f8c7922f7c1d60d7c34145ade05d789640dc7dc9ec1021e07bb54",
  "stacks_tip_consensus_hash": "17f76e597bab45646956f38dd39573085d72cbc0",
  "genesis_chainstate_hash": "74237aa39aa50a83de11a4f3e9a0b9c89a0b1a2f2a6a11b8a7e1e9a0b1c2d3e4f",
  "unanchored_tip": "0000000000000000000000000000000000000000000000000000000000000000",
  "tenure_height": 523,
  "exit_at_block_height": null,
  "is_fully_synced": false,
  "node_public_key": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01",
  "node_public_key_hash": "1328af7c4f96eee8fdbb1e023e48ba11e255d1c8",
  "last_pox_anchor": {
    "anchor_block_hash": "47c20352492e1647127d6f6275fa5abfe90157f6a64e6a175ff45ed0c1fb3f4e",
    "anchor_block_txid": "5b5d678c658525122fa73a8699b5810325ce9412bf0dc3762fb7518699be3d4d"
  },
  "stackerdbs": []
}

Get PoX details

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/pox

Get Proof of Transfer (PoX) information. Can be used for Stacking.

Query parameters

tipstring · max: 64Optional

Stacks chain tip to query from. Options:

• (empty/omitted): Use latest anchored tip (canonical confirmed state)
• latest: Use latest known tip including unconfirmed microblocks
• {block_id}: Use specific block ID (64 hex characters)

Example: latestPattern: ^(latest|[0-9a-f]{64})?$

Responses

200

Success

application/json

Get Proof of Transfer (PoX) information

contract_idstringRequired

The contract identifier for the PoX contract

first_burnchain_block_heightintegerRequired

The first burn block evaluated in this Stacks chain

current_burnchain_block_heightintegerRequired

The latest Bitcoin chain block height

current_epochstringRequired

The ID of the Stacks Epoch that the node is currently in.

Pattern: ^Epoch[0-9]+(_[0-9]+)?$

pox_activation_threshold_ustxintegerRequired

The threshold of stacking participation that must be reached for PoX to activate in any cycle

rejection_fractioninteger · nullableOptional

The fraction of liquid STX that must vote to reject PoX in order to prevent the next reward cycle from activating.

reward_phase_block_lengthintegerRequired

The length in burn blocks of the reward phase

prepare_phase_block_lengthintegerRequired

The length in burn blocks of the prepare phase

reward_slotsintegerRequired

The number of reward slots in a reward cycle

total_liquid_supply_ustxintegerRequired

The current total amount of liquid microstacks.

reward_cycle_lengthintegerRequired

The length in burn blocks of a whole PoX cycle (reward phase and prepare phase)

reward_cycle_idintegerOptionalDeprecated

The active reward cycle number

min_amount_ustxintegerOptionalDeprecated

prepare_cycle_lengthintegerOptionalDeprecated

rejection_votes_left_requiredinteger · nullableOptionalDeprecated

next_reward_cycle_inintegerOptionalDeprecated

The number of blocks until the next reward cycle.

400

Bad request

text/plain

404

Not found

text/plain

500

Internal Server Error

text/plain

get

/v2/pox

HTTPcURLJavaScriptPython

GET /v2/pox HTTP/1.1
Host: localhost:20443
Accept: */*

{
  "contract_id": "SP000000000000000000002Q6VF78.pox",
  "current_epoch": "Epoch30",
  "pox_activation_threshold_ustx": 52329761604388,
  "first_burnchain_block_height": 666050,
  "current_burnchain_block_height": 812345,
  "prepare_phase_block_length": 100,
  "reward_phase_block_length": 2000,
  "reward_slots": 4000,
  "rejection_fraction": 25,
  "total_liquid_supply_ustx": 1046595232087772,
  "current_cycle": {
    "id": 2,
    "min_threshold_ustx": 70000000000,
    "stacked_ustx": 202157971547640,
    "is_pox_active": true
  },
  "next_cycle": {
    "id": 3,
    "min_threshold_ustx": 70000000000,
    "min_increment_ustx": 52329761604,
    "stacked_ustx": 162057034977640,
    "prepare_phase_start_block_height": 672250,
    "blocks_until_prepare_phase": 407,
    "reward_phase_start_block_height": 672350,
    "blocks_until_reward_phase": 507,
    "ustx_until_pox_rejection": 261648808021925
  },
  "min_amount_ustx": 70000000000,
  "prepare_cycle_length": 100,
  "reward_cycle_id": 2,
  "reward_cycle_length": 2100,
  "rejection_votes_left_required": 261648808021925,
  "next_reward_cycle_in": 507,
  "contract_versions": [
    {
      "contract_id": "SP000000000000000000002Q6VF78.pox",
      "activation_burnchain_block_height": 666050,
      "first_reward_cycle_id": 0
    },
    {
      "contract_id": "SP000000000000000000002Q6VF78.pox-2",
      "activation_burnchain_block_height": 712345,
      "first_reward_cycle_id": 123
    }
  ],
  "epochs": [
    {
      "epoch_id": "Epoch0",
      "start_height": 0,
      "end_height": 200000,
      "block_limit": {
        "read_count": 15000,
        "read_length": 100000000,
        "write_count": 15000,
        "write_length": 15000000,
        "runtime": 5000000000
      },
      "network_epoch": 0
    },
    {
      "epoch_id": "Epoch1",
      "start_height": 200000,
      "end_height": 300000,
      "block_limit": {
        "read_count": 15000,
        "read_length": 100000000,
        "write_count": 15000,
        "write_length": 15000000,
        "runtime": 5000000000
      },
      "network_epoch": 1
    }
  ]
}

Query the health of the node.

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v3/health

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.

Responses

200

Success

application/json

Health information about the node's synchronization status

difference_from_max_peerintegerRequired

The difference in Stacks height between this node and its most advanced peer

max_stacks_height_of_neighborsintegerRequired

The maximum Stacks height observed among the node's connected peers

node_stacks_tip_heightintegerRequired

The current Stacks tip height of this node

max_stacks_neighbor_addressstring · nullableOptional

The address of the most advanced peer

400

Bad request

text/plain

500

Internal Server Error

text/plain

get

/v3/health

HTTPcURLJavaScriptPython

GET /v3/health HTTP/1.1
Host: localhost:20443
Accept: */*

{
  "difference_from_max_peer": 0,
  "node_stacks_tip_height": 12345,
  "max_stacks_height_of_neighbors": 12345,
  "max_stacks_neighbor_address": "127.0.0.1:8080"
}

Get neighbor peers

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/neighbors

Get information about the node"s neighbor peers in the network.

Responses

200

List of neighbor peers

application/json

Information about the node's neighbor peers in the network.

get

/v2/neighbors

HTTPcURLJavaScriptPython

GET /v2/neighbors HTTP/1.1
Host: localhost:20443
Accept: */*

200

List of neighbor peers

{
  "bootstrap": [
    {
      "network_id": 1,
      "peer_version": 24000000,
      "ip": "172.20.0.3",
      "port": 20444,
      "public_key_hash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
      "authenticated": true,
      "stackerdbs": [
        "SP000000000000000000002Q6VF78.my-stacker-db-1"
      ],
      "age": null
    }
  ],
  "sample": [
    {
      "network_id": 1,
      "peer_version": 24000000,
      "ip": "88.99.100.123",
      "port": 20444,
      "public_key_hash": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3",
      "authenticated": true,
      "stackerdbs": [],
      "age": null
    }
  ],
  "inbound": [
    {
      "network_id": 1,
      "peer_version": 24000000,
      "ip": "192.168.1.10",
      "port": 54321,
      "public_key_hash": "c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "authenticated": true,
      "stackerdbs": [],
      "age": 3600
    }
  ],
  "outbound": [
    {
      "network_id": 1,
      "peer_version": 24000000,
      "ip": "10.0.0.5",
      "port": 20444,
      "public_key_hash": "d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5",
      "authenticated": true,
      "stackerdbs": [
        "SP000000000000000000002Q6VF78.my-stacker-db-2"
      ],
      "age": 120
    }
  ]
}