circle-info
Check out the upcoming Programming USDCx on Stacks Builder Challenge!
arrow-up-right
search
Platform

RPC API (old)

hashtag
Introduction

The Stacks Blockchain API allows you to query the Stacks blockchain and interact with smart contracts. It was built to maintain pageable materialized views of the Stacks Blockchain.

Note that the Stacks Node RPC APIarrow-up-right and the Hiro Stacks APIarrow-up-right are two different things. The Hiro API is a centralized service run by Hiro, a developer tooling company, that makes it easy to get onboarded and begin interacting with the Stacks blockchain in a RESTful way. You can also run your own API serverarrow-up-right.

The Hiro Stacks API is a proxy for the Stacks Node API that makes it a bit easier to work with by providing additional functionality.

The RPC API is generated by every Stacks node and allows developers to self-host their own node and API for a more decentralized architecture.

The RPC API can be used without any authorization. The basepath for the API is:

# for mainnet, replace `testnet` with `mainnet`
https://api.testnet.hiro.so/
circle-exclamation

If you run a local node, it exposes an HTTP server on port 20443. The info endpoint would be localhost:20443/v2/info.

hashtag
Stacks Node RPC API endpoints

The Stacks Blockchain RPC API is exposed by every running Stacks node. Below is an interactive list of common RPC endpoints.

hashtag
Broadcast raw transaction

post

Broadcast raw transactions on the network. You can use the @stacks/transactionsarrow-up-right project to generate a raw transaction payload.

The node performs static validation checks on transactions before accepting them into the mempool, including:

  • Transaction format validation

  • Signature verification

  • Nonce checking

  • Fee validation

  • Size limits

Body
string · binaryOptional
Responses
chevron-right
200

Transaction ID of successful post of a raw tx to the node's mempool.

application/json
ResponsestringExample: e161978626f216b2141b156ade10501207ae535fa365a13ef5d7a7c9310a09f2Pattern: ^[0-9a-f]{64}$
post
/v2/transactions

hashtag
Get specific data-map inside a contract

post

Attempt to fetch data from a contract data map. The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The map is identified with [Map Name].

The key to lookup in the map is supplied via the POST body. This should be supplied as the hex string serialization of the key (which should be a Clarity value). Note, this is a JSON string.

The response is a JSON object with the following properties:

  • data: The hex serialization of the map response. Note that map responses are Clarity option types, for non-existent values, this is a serialized none, and for all other responses, it is a serialized (some ...) object.

  • proof: The hex serialization of the Merkle proof for the data.

Path parameters
contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
map_namestring · min: 1 · max: 128RequiredPattern: ^([a-zA-Z0-9_]|[-!?+<>=/*]){1,128}$
Body
stringOptional
Responses
chevron-right
200

Success

application/json
post
/v2/map_entry/{contract_address}/{contract_name}/{map_name}

hashtag
Get contract interface

get

Get contract interface using a contract_address and contract name

Path parameters
contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
Responses
chevron-right
200

Contract interface

application/json
get
/v2/contracts/interface/{contract_address}/{contract_name}

hashtag
Get contract source

get

Returns the Clarity source code of a given contract, along with the block height it was published in, and the MARF proof for the data.

Path parameters
contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
Responses
chevron-right
200

Success

application/json
get
/v2/contracts/source/{contract_address}/{contract_name}

hashtag
Call read-only function

post

Call a read-only public function on a given contract.

The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The function is identified with [Function Name].

The arguments to the function are supplied via the POST body. This should be a JSON object with two main properties:

  • sender which should be a standard Stacks address

  • arguments which should be an array of hex-encoded Clarity values.

Path parameters
contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
function_namestring · min: 1 · max: 128RequiredPattern: ^([a-zA-Z0-9_]|[-!?+<>=/*]){1,128}$
Body

Describes representation of a Type-0 Stacks 2.0 transaction. https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#type-0-transferring-an-asset

senderstringRequired

The simulated tx-sender

sponsorstringOptional

The simulated sponsor address

argumentsstring[]Required

An array of hex serialized Clarity values

Responses
chevron-right
200

Function executed successfully

application/json
Responseone of

The result of a read-only function call.

or
post
/v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}

hashtag
Call read-only function in fast mode (no cost and memory tracking)

post

Call a read-only public function on a given smart contract without cost tracking.

The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The function is identified with [Function Name].

The arguments to the function are supplied via the POST body. This should be a JSON object with two main properties:

  • sender which should be a standard Stacks address

  • arguments which should be an array of hex-encoded Clarity values.

This API endpoint requires a basic Authorization header.

Authorizations
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.

Path parameters
contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
function_namestring · min: 1 · max: 128RequiredPattern: ^([a-zA-Z0-9_]|[-!?+<>=/*]){1,128}$
Body

Describes representation of a Type-0 Stacks 2.0 transaction. https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#type-0-transferring-an-asset

senderstringRequired

The simulated tx-sender

sponsorstringOptional

The simulated sponsor address

argumentsstring[]Required

An array of hex serialized Clarity values

Responses
chevron-right
200

Function executed successfully

application/json
Responseone of

The result of a read-only function call.

or
post
/v3/contracts/fast-call-read/{contract_address}/{contract_name}/{function_name}

hashtag
Get account info

get

Get the account data for the provided principal

Where balance is the hex encoding of a unsigned 128-bit integer (big-endian), nonce is a unsigned 64-bit integer, and the proofs are provided as hex strings.

For non-existent accounts, this does not 404, rather it returns an object with balance and nonce of 0.

Responses
chevron-right
200

Success

application/json
get
/v2/accounts/{principal}

hashtag
Get approximate fees for the given transaction

post

Get an estimated fee for the supplied transaction. This estimates the execution cost of the transaction, the current fee rate of the network, and returns estimates for fee amounts.

  • transaction_payload is a hex-encoded serialization of the TransactionPayload for the transaction.

  • estimated_len is an optional argument that provides the endpoint with an estimation of the final length (in bytes) of the transaction, including any post-conditions and signatures

If the node cannot provide an estimate for the transaction (e.g., if the node has never seen a contract-call for the given contract and function) or if estimation is not configured on this node, a 400 response is returned. The 400 response will be a JSON error containing a reason field which can be one of the following:

  • DatabaseError - this Stacks node has had an internal database error while trying to estimate the costs of the supplied transaction.

  • NoEstimateAvailable - this Stacks node has not seen this kind of contract-call before, and it cannot provide an estimate yet.

  • CostEstimationDisabled - this Stacks node does not perform fee or cost estimation, and it cannot respond on this endpoint.

The 200 response contains the following data:

  • estimated_cost - the estimated multi-dimensional cost of executing the Clarity VM on the provided transaction.

  • estimated_cost_scalar - a unitless integer that the Stacks node uses to compare how much of the block limit is consumed by different transactions. This value incorporates the estimated length of the transaction and the estimated execution cost of the transaction. The range of this integer may vary between different Stacks nodes. In order to compute an estimate of total fee amount for the transaction, this value is multiplied by the same Stacks node"s estimated fee rate.

  • cost_scalar_change_by_byte - a float value that indicates how much the estimated_cost_scalar value would increase for every additional byte in the final transaction.

  • estimations - an array of estimated fee rates and total fees to pay in microSTX for the transaction. This array provides a range of estimates (default: 3) that may be used. Each element of the array contains the following fields:

    • fee_rate - the estimated value for the current fee rates in the network

    • fee - the estimated value for the total fee in microSTX that the given transaction should pay. These values are the result of computing: fee_rate x estimated_cost_scalar. If the estimated fees are less than the minimum relay fee (1 ustx x estimated_len), then that minimum relay fee will be returned here instead.

Note: If the final transaction"s byte size is larger than supplied to estimated_len, then applications should increase this fee amount by:

fee_rate x cost_scalar_change_by_byte x (final_size - estimated_size)

Body

POST request for estimated fee

transaction_payloadstringRequired
estimated_lenintegerOptional
Responses
chevron-right
200

Estimated fees for the transaction

application/json
post
/v2/fees/transaction

hashtag
Get estimated fee

get

Get an estimated fee rate for STX transfer transactions. This is a fee rate per byte, returned as a JSON integer (microSTX per byte).

Responses
chevron-right
200

Fee rate in microSTX per byte

application/json
Responseinteger · min: 1

Fee rate in microSTX per byte

get
/v2/fees/transfer

hashtag
Get Core API info

get

Get Core API information

Responses
chevron-right
200

Success

application/json
get
/v2/info

hashtag
Get PoX details

get

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

Responses
chevron-right
200

Success

application/json
get
/v2/pox
200

Success

hashtag
Get trait implementation details

get

Determine whether or not a specified trait is implemented (either explicitly or implicitly) within a given contract.

Path parameters
contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
trait_contract_addressstring · min: 28 · max: 41Required

Stacks address of the trait-defining contract.

Example: SP2Z1K16238380NBP4T38A4G10A90Q03JJ2C2003Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$
trait_contract_namestring · min: 1 · max: 128Required

Contract name of the trait-defining contract.

Example: some-traitPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
trait_namestring · min: 1 · max: 128RequiredExample: some-traitPattern: ^([a-zA-Z0-9_]|[-!?+<>=/*]){1,128}$
Responses
chevron-right
200

Success

application/json
get
/v2/traits/{contract_address}/{contract_name}/{trait_contract_address}/{trait_contract_name}/{trait_name}

hashtag
Get the MARF value for a given key

get

Attempt to fetch the value of a MARF key. The key is a 64-character hex string representing the MARF node hash.

Path parameters
marf_key_hashstring · min: 64 · max: 64Required

The 64-character hex-encoded hash of the MARF key.

Pattern: ^[0-9a-f]{64}$
Responses
chevron-right
200

Success

application/json
get
/v2/clarity/marf/{marf_key_hash}

hashtag
Get the contract metadata for the metadata key

get

Attempt to fetch the metadata of a contract. The contract is identified with [Contract Address] and [Contract Name] in the URL path. The metadata key is identified with [Clarity Metadata Key].

In the response, data is formatted as JSON.

Path parameters
contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
clarity_metadata_keystringRequired

Metadata key

Responses
chevron-right
200

Success

application/json
get
/v2/clarity/metadata/{contract_address}/{contract_name}/{clarity_metadata_key}

hashtag
Get the value of a constant inside a contract

get

Attempt to fetch the value of a constant inside a contract. The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The constant is identified with [Constant Name].

In the response, data is the hex serialization of the constant value.

Path parameters
contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
constant_namestring · min: 1 · max: 128RequiredPattern: ^([a-zA-Z0-9_]|[-!?+<>=/*]){1,128}$
Responses
chevron-right
200

Success

application/json
get
/v2/constant_val/{contract_address}/{contract_name}/{constant_name}

hashtag
Validate a proposed Stacks block

post

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

Authorizations
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
blockstringRequired

Hex-encoded block data

chain_idintegerRequired

Chain ID for the block

Responses
post
/v3/block_proposal

hashtag
Fetch the stacker and signer set information for a given cycle.

get

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.

Path parameters
cycle_numberintegerRequired

reward cycle number

Responses
chevron-right
200

Information for the given reward cycle

application/json
get
/v3/stacker_set/{cycle_number}

hashtag
Get Nakamoto block by ID

get

Get a specific Nakamoto block (Stacks 3.x+) by its index block hash. This endpoint streams the block data from the Nakamoto staging blocks database where Nakamoto blocks are stored with additional metadata including tenure information.

Compatibility: Works with Nakamoto blocks only. For Stacks 2.x blocks, use /v2/blocks/{block_id}.

Path parameters
block_idstringRequired

The block"s ID hash

Responses
chevron-right
200

The raw SIP-003-encoded block will be returned.

application/octet-stream
Responsestring · binary
get
/v3/blocks/{block_id}

hashtag
Fetch a Nakamoto block by its height and optional tip

get

Fetch a Nakamoto block by its height and optional tip.

Path parameters
block_heightintegerRequired

The block's height

Responses
chevron-right
200

The raw SIP-003-encoded block will be returned.

application/octet-stream
Responsestring · binary
get
/v3/blocks/height/{block_height}

hashtag
Fetch metadata about the ongoing Nakamoto tenure

get

Fetch metadata about the ongoing Nakamoto tenure. This information is sufficient to obtain and authenticate the highest complete tenure, as well as obtain new tenure blocks.

Responses
chevron-right
200

Metadata about the ongoing tenure

application/json
get
/v3/tenures/info
200

Metadata about the ongoing tenure

hashtag
Fetch a sequence of Nakamoto blocks in a tenure

get

Fetch a sequence of Nakamoto blocks in a tenure. The blocks will be served in order from highest to lowest. The blocks will be encoded in their SIP-003 wire format, and concatenated together.

Path parameters
block_idstringRequired

The tenure-start block ID of the tenure to query

Query parameters
stopstringOptional

The block ID hash of the highest block in this tenure that is already known to the caller. Neither the corresponding block nor any of its ancestors will be served. This is used to fetch tenure blocks that the caller does not have.

Responses
chevron-right
200

SIP-003-encoded Nakamoto blocks, concatenated together

application/octet-stream
Responsestring · binary
get
/v3/tenures/{block_id}
200

SIP-003-encoded Nakamoto blocks, concatenated together

hashtag
Get the list of Stacks blocks in a tenure

get

Get the list of blocks in a tenure. The blocks will be shown in order from highest to lowest.

Path parameters
consensus_hashstringRequired

The hex-encoded consensus hash of the tenure to query (40 hexadecimal characters, without 0x prefix)

Pattern: ^[0-9a-f]{40}$
Responses
chevron-right
200

List of Stacks blocks in the tenure

application/json
get
/v3/tenures/blocks/{consensus_hash}

hashtag
Get the list of Nakamoto Stacks blocks in a tenure given Bitcoin block hash

get

Get the list of Nakamoto blocks in a tenure given the Bitcoin block hash. The blocks will be shown in order from highest to lowest. This is only for Nakamoto blocks, Epoch2 ones will not be shown.

Path parameters
burnchain_block_hashstringRequired

The hex-encoded Bitcoin block hash of the tenure to query (64 hexadecimal characters, without 0x prefix)

Pattern: ^[0-9a-f]{64}$
Responses
chevron-right
200

List of Stacks blocks in the tenure

application/json
get
/v3/tenures/blocks/hash/{burnchain_block_hash}

hashtag
Get the list of Nakamoto Stacks blocks in a tenure given Bitcoin block height

get

Get the list of Nakamoto blocks in a tenure given the Bitcoin block height. The blocks will be shown in order from highest to lowest. This is only for Nakamoto blocks, Epoch2 ones will not be shown.

Path parameters
burnchain_block_heightintegerRequired

The Bitcoin block height of the tenure to query

Responses
chevron-right
200

List of Stacks blocks in the tenure

application/json
get
/v3/tenures/blocks/height/{burnchain_block_height}

hashtag
Get latest sortition information

get

Get sortition information about the latest burnchain block processed by this node. Returns a single-element array with the latest sortition.

Responses
chevron-right
200

Latest sortition information

application/json
get
/v3/sortitions

hashtag
Get latest and last winning sortitions

get

Get sortition information about the latest burn block with a winning miner AND the previous such burn block. Returns an array with two sortition objects.

Responses
chevron-right
200

Latest and last sortition information

application/json
get
/v3/sortitions/latest_and_last

hashtag
Get sortition by consensus hash

get

Get sortition information for a specific consensus hash. Returns a single-element array with the matching sortition.

Path parameters
consensus_hashstringRequired

Hex-encoded consensus hash (40 characters)

Pattern: ^(0x)?[0-9a-f]{40}$
Responses
chevron-right
200

Sortition information for the consensus hash

application/json
get
/v3/sortitions/consensus/{consensus_hash}

hashtag
Get sortition by burn header hash

get

Get sortition information for a specific burn header hash. Returns a single-element array with the matching sortition.

Path parameters
burn_header_hashstringRequired

Hex-encoded burn header hash (64 characters)

Pattern: ^(0x)?[0-9a-f]{64}$
Responses
chevron-right
200

Sortition information for the burn header hash

application/json
get
/v3/sortitions/burn/{burn_header_hash}

hashtag
Get sortition by burn block height

get

Get sortition information for a specific burn block height. Returns a single-element array with the matching sortition.

Path parameters
heightintegerRequired

Burn block height (integer)

Responses
chevron-right
200

Sortition information for the burn block height

application/json
get
/v3/sortitions/burn_height/{height}

hashtag
Get number of blocks signed by signer during a given reward cycle

get

Get number of blocks signed by signer during a given reward cycle

Path parameters
signer_pubkeystringRequired

Hex-encoded compressed Secp256k1 public key of signer

Pattern: ^0[23][0-9a-f]{64}$
cycle_numberintegerRequired

Reward cycle number

Responses
chevron-right
200

Number of blocks signed

application/json
get
/v3/signer/{signer_pubkey}/{cycle_number}
200

Number of blocks signed

hashtag
Retrieve transaction details by TXID

get

Get a JSON with the transaction details including the index_block_hash, the hex-encoded transaction body, and the result.

Path parameters
txidstringRequired

Transaction ID (64 hexadecimal characters)

Pattern: ^[0-9a-f]{64}$
Responses
chevron-right
200

Transaction JSON with index_block_hash, transaction body and result

application/json
get
/v3/transaction/{txid}

hashtag
Query the health of the node.

get

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
chevron-right
200

Success

application/json
get
/v3/health

hashtag
Get attachment by hash

get

Get an attachment by its hash. Attachments are content stored in the Atlas network.

The attachment hash is a 40-character hex string (SHA-1 hash).

Path parameters
hashstringRequired

Hex-encoded SHA-1 hash of the attachment (40 characters)

Pattern: ^[0-9a-f]{40}$
Responses
chevron-right
200

The attachment content

application/json
get
/v2/attachments/{hash}

hashtag
Get attachment inventory

get

Get inventory of attachments for a given index block hash and page range. This returns a bitfield indicating which attachments are available.

Query parameters
index_block_hashstringRequired

Hex-encoded index block hash (64 characters)

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

max 8 pages per request

Example: 1,2,3Pattern: ^[0-9]+(,[0-9]+){0,7}$
Responses
chevron-right
200

Attachment inventory bitfield

application/json
get
/v2/attachments/inv

hashtag
Get stream of confirmed microblocks (Epoch 2.x)

get

Get microblocks that were confirmed by the given anchored block. The microblocks are returned as a binary stream of concatenated microblock data.

Path parameters
block_idstringRequired

Hex-encoded Stacks block ID (64 characters)

Pattern: ^[0-9a-f]{64}$
Responses
chevron-right
200

Stream of confirmed microblocks

application/octet-stream
Responsestring · binary
get
/v2/microblocks/confirmed/{block_id}

hashtag
Get a stream of microblocks beginning with the given microblock (Epoch 2.x).

get
Path parameters
microblock_idstringRequired

Hex-encoded microblock hash (64 characters)

Pattern: ^[0-9a-f]{64}$
Responses
chevron-right
200

The microblock data

application/octet-stream
Responsestring · binary
get
/v2/microblocks/{microblock_id}

hashtag
Get stream of unconfirmed microblocks (Epoch 2.x)

get

Get unconfirmed microblocks starting from a specific sequence number. The microblocks are returned as a binary stream.

Path parameters
block_idstringRequired

Hex-encoded parent block ID (64 characters)

Pattern: ^[0-9a-f]{64}$
seqinteger · max: 65535Required

Starting sequence number (0-65535)

Responses
chevron-right
200

Stream of unconfirmed microblocks

application/octet-stream
Responsestring · binary
get
/v2/microblocks/unconfirmed/{block_id}/{seq}

hashtag
Submit a microblock (Epoch 2.x)

post

Submit a microblock to the node for validation and relay. The body must be the SIP-003 binary serialization of a Microblock and sent with Content-Type: application/octet-stream.

Body
string · binaryOptional
Responses
chevron-right
200

Index-block hash of the accepted microblock

application/json
Responsestring

32-byte block-header hash (hex)

Pattern: ^[0-9a-f]{64}$
post
/v2/microblocks

hashtag
Get StackerDB chunk (latest version)

get

Get the latest version of a chunk of data from a StackerDB instance.

Path parameters
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
slot_idintegerRequired

Slot ID

Responses
chevron-right
200

StackerDB chunk data

application/octet-stream
Responsestring · binary
get
/v2/stackerdb/{principal}/{contract_name}/{slot_id}

hashtag
Get StackerDB chunk (specific version)

get

Get a specific version of a chunk of data from a StackerDB instance.

Path parameters
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
slot_idintegerRequired

Slot ID

slot_versionintegerRequired

Specific slot version

Responses
chevron-right
200

StackerDB chunk data

application/octet-stream
Responsestring · binary
get
/v2/stackerdb/{principal}/{contract_name}/{slot_id}/{slot_version}

hashtag
Get StackerDB metadata

get

Get metadata about a StackerDB instance, including slot information.

Path parameters
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
Responses
chevron-right
200

StackerDB metadata

application/json
get
/v2/stackerdb/{principal}/{contract_name}

hashtag
Write StackerDB chunk

post

Write a chunk of data to a StackerDB instance.

The request body should contain a JSON object with the chunk data including slot_id, slot_version, signature, and hex-encoded data.

The response indicates whether the chunk was accepted, and if not, provides detailed error information. Note that failed writes return HTTP 200 with accepted: false, not HTTP error codes.

Path parameters
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
Body
slot_idintegerRequired

Slot identifier

slot_versionintegerRequired

Slot version (lamport clock)

sigstringRequired

Hex-encoded signature from the stacker

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

Hex-encoded chunk data

Pattern: ^[0-9a-f]*$
Responses
chevron-right
200

Chunk submission result (both success and failure cases)

application/json
post
/v2/stackerdb/{principal}/{contract_name}/chunks

hashtag
List StackerDB replicas

get

Get a list of replicas for a StackerDB instance.

Path parameters
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
Responses
chevron-right
200

List of StackerDB replicas

application/json
get
/v2/stackerdb/{principal}/{contract_name}/replicas

hashtag
Get contract data variable

get

Fetch a data variable from a smart contract. Returns the raw hex-encoded value of the variable.

Path parameters
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
var_namestringRequired

Variable name

Responses
chevron-right
200

The data variable value

application/json
get
/v2/data_var/{principal}/{contract_name}/{var_name}

hashtag
Get recent 2.x block headers

get

Deprecated: This endpoint is deprecated since Nakamoto.** Stream (as a JSON array) up to quantity most recent anchored Stacks block headers. The result is ordered from the current tip backwards.

Path parameters
quantityinteger · min: 1 · max: 256Required

Number of headers to return (max 256)

Responses
chevron-right
200

Array of block headers

application/json
get
/v2/headers/{quantity}

hashtag
Get Stacks 2.x block by ID

get

Get a specific Stacks 2.x era block by its block ID. This endpoint streams the block data from the filesystem storage where traditional Stacks blocks are stored as individual files.

Compatibility: Works with all Stacks 2.x blocks. For Nakamoto blocks (Stacks 3.x+), use /v3/blocks/{block_id}.

Path parameters
block_idstringRequired

Hex-encoded block ID (64 characters)

Pattern: ^[0-9a-f]{64}$
Responses
chevron-right
200

The block data

application/octet-stream
Responsestring · binary
get
/v2/blocks/{block_id}

hashtag
Get neighbor peers

get

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

Responses
chevron-right
200

List of neighbor peers

application/json
get
/v2/neighbors
200

List of neighbor peers

hashtag
Get tenure fork information

get

Get information about tenure forking between two consensus hashes. This is used to identify conflicting tenures in the Nakamoto consensus.

Path parameters
startstringRequired

Starting consensus hash (40 hexadecimal characters, without 0x prefix)

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

Stopping consensus hash (40 hexadecimal characters, without 0x prefix)

Pattern: ^[0-9a-f]{40}$
Responses
chevron-right
200

Ordered list of tenure fork events from stop back to (and including) start

application/json
get
/v3/tenures/fork_info/{start}/{stop}

hashtag
Get tenure tip

get

Get the tip block of a tenure identified by consensus hash.

Path parameters
consensus_hashstringRequired

Consensus hash (40 characters)

Pattern: ^[0-9a-f]{40}$
Responses
chevron-right
200

Tenure tip block information

application/json
Responseone of

JSON encoding of StacksBlockHeaderTypes returned by /v3/tenures/tip. Exactly one variant property will be present: either Epoch2 or Nakamoto.

or
get
/v3/tenures/tip/{consensus_hash}

hashtag
Get unconfirmed transaction

get

Get an unconfirmed transaction by its transaction ID. This looks in both the mempool and unconfirmed microblock stream.

Path parameters
txidstringRequired

Transaction ID (64 hexadecimal characters)

Pattern: ^[0-9a-f]{64}$
Responses
chevron-right
200

Unconfirmed transaction details

application/json
get
/v2/transactions/unconfirmed/{txid}

hashtag
Upload a Stacks block

post

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
string · binaryOptional

Binary-encoded Stacks block

Responses
chevron-right
200

Block upload result

application/json
post
/v2/blocks/upload/{consensus_hash}

hashtag
Query mempool for missing transactions

post

Query the mempool for transactions that might be missing from the requesting node. This endpoint supports pagination and streaming of transaction data.

Query parameters
page_idstringOptional

Transaction ID to start pagination from

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

Binary SIP-003 encoding of MemPoolSyncData (BloomFilter or TxTags variants).

transactionsstring[]Optional

Transaction IDs

Responses
chevron-right
200

Stream of missing transactions

application/octet-stream
Responsestring · binary

Binary stream of transactions and pagination data. The stream contains serialized transactions followed by a page ID for continuation.

post
/v2/mempool/query

hashtag
Upload a Nakamoto block

post

Upload a Nakamoto block to the node for processing.

  • Body - must be the binary (SIP-003) serialization of a NakamotoBlock.

  • Authentication - only required when the query parameter broadcast=1 is supplied. In that case the caller must include an Authorization header.

Authorizations
authorizationstringOptional

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.

Query parameters
broadcaststring · enumOptional

If set to "1" the node will broadcast the uploaded block to peers. When present the request must include a valid Authorization header.

Possible values:
Body
string · binaryOptional

Binary SIP-003 encoding of a NakamotoBlock

Responses
chevron-right
200

Block upload result.

application/json
post
/v3/blocks/upload

hashtag
Replay mining of a block and returns its content

get

Replay the mining of a block (no data is written in the MARF) and returns its content.

Authorizations
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.

Path parameters
block_idstringRequired

The block ID hash

Pattern: ^[0-9a-f]{64}$
Responses
chevron-right
200

Content of the replayed block

application/json
get
/v3/blocks/replay/{block_id}

For details about request/response schemas, consult the Stacks node OpenAPI spec: https://raw.githubusercontent.com/stacks-network/stacks-core/master/docs/rpc/openapi.yaml

Last updated

Was this helpful?