Mining

Endpoints related to Stacks block production and mining.

Validate a proposed Stacks block

post

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

/v3/block_proposal

Used by stackers to validate a proposed Stacks block from a miner. This API endpoint requires a basic Authorization header.

Authorizations

rpcAuth

authorizationstringRequired

Plain-text secret value that must exactly equal the node's configured password, which is set as connection_options.auth_token in the node's configuration file.

Body

application/json

blockstring · min: 400Required

Hex-encoded block data (must be valid SIP-003 serialized block, typically 200+ bytes)

Pattern: ^([0-9a-fA-F]{2})+$

chain_idintegerRequired

Chain ID for the block

Responses

202

Block proposal has been accepted for processing. The result will be returned via the event observer.

application/json

400

Bad Request

application/jsontext/plain

401

Unauthorized. Invalid or missing authentication token.

text/plain

429

There is an ongoing proposal validation being processed, the new request cannot be accepted until the prior request has been processed.

application/json

500

Internal Server Error

text/plain

post

/v3/block_proposal

HTTPcURLJavaScriptPython

POST /v3/block_proposal HTTP/1.1
Host: localhost:20443
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 928

{
  "block": "00000000000000001f00000000000927c08fb5ae5bf80e39e4168f6a3fddb0407a069d21ee68465e6856393254d2a66194f44bb01070666d5effcfb2436e209a75878fe80a04b4258a8cd34ab97c38a8dde331a2a509dd7e4b90590726866172cc138c18e80567737667f55d3f9817ce4714c91d1adfd36101141829dc0b5ea0c4944668c0005ddb6f9e2718f60014f21932a42a36ffaf58e88e77b217b2af366c15dd59e6b136ca773729832dcfc5875ec0830d04012dd5a4fa77a196646ea2b356289116fd02558c034b62d63f8a65bdd20d7ffc3fec6c266cd974be776a9e92759b90f288dcc2525b6b6bd5622c5f02e0922440e9ad1095c19b4467fd94566caa9755669d8e0000000180800000000400f64081ae6209dce9245753a4f764d6f168aae1af00000000000000000000000000000064000041dbcc7391991c1a18371eb49b879240247a3ec7f281328f53976c1218ffd65421dbb101e59370e2c972b29f48dc674b2de5e1b65acbd41d5d2689124d42c16c01010000000000051a346048df62be3a52bb6236e11394e8600229e27b000000000000271000000000000000000000000000000000000000000000000000000000000000000000",
  "chain_id": 2147483648
}

{
  "message": "Block proposal is processing, result will be returned via the event observer",
  "result": "Accepted"
}

Upload a Stacks block

post

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

/v2/blocks/upload/{consensus_hash}

Upload a Stacks block to the node for processing. The block must be in binary format and associated with the given consensus hash.

Path parameters

consensus_hashstringRequired

Consensus hash (40 hex characters)

Pattern: ^[0-9a-f]{40}$

Body

application/octet-stream

string · binary · min: 1Optional

Binary-encoded Stacks block

Responses

200

Block upload result

application/json

stacks_block_idstringOptional

The ID of the uploaded block

acceptedbooleanOptional

Whether the block was accepted

400

Bad request

text/plain

404

Not found

text/plain

500

Internal Server Error

text/plain

post

/v2/blocks/upload/{consensus_hash}

HTTPcURLJavaScriptPython

POST /v2/blocks/upload/{consensus_hash} HTTP/1.1
Host: localhost:20443
Content-Type: application/octet-stream
Accept: */*
Content-Length: 8

"binary"

{
  "stacks_block_id": "abc123...",
  "accepted": true
}