API

Introduction

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

Note that the Stacks Node RPC API and the Hiro Stacks API 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 server

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.

This documentation only covers endpoints that are exposed on a Stacks node, referred to as the RPC API. For full documentation on the RESTful API, check out the Hiro's API reference.

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/

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

Stacks Node RPC API endpoints

The Stacks 2.0 Blockchain API (Hiro's API) is centrally hosted. However, every running Stacks node exposes an RPC API, which allows you to interact with the underlying blockchain. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node.

Broadcast raw transaction

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

POSThttp://localhost:20443/v2/transactions

Body

application/octet-stream

string (binary)

Response

200400

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

Body

text/plain

string

Example: "\"e161978626f216b2141b156ade10501207ae535fa365a13ef5d7a7c9310a09f2\""

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:20443/v2/transactions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/octet-stream"
    },
    body: JSON.stringify("binary format of 00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000"),
});
const data = await response.json();

Response

200

"e161978626f216b2141b156ade10501207ae535fa365a13ef5d7a7c9310a09f2"

Get contract interface

Get contract interface using a contract_address and contract name

GEThttp://localhost:20443/v2/contracts/interface/{contract_address}/{contract_name}

Path parameters

contract_address*string

Stacks address

contract_name*string

Contract name

Query parameters

Response

200

Contract interface

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:20443/v2/contracts/interface/{contract_address}/{contract_name}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get specific data-map inside a contract

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

In the response, data is 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.

POSThttp://localhost:20443/v2/map_entry/{contract_address}/{contract_name}/{map_name}

Path parameters

contract_address*string

Stacks address

contract_name*string

Contract name

map_name*string

Map name

Query parameters

Body

application/json

Hex string serialization of the lookup key (which should be a Clarity value)

string

Response

200400

Success

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:20443/v2/map_entry/{contract_address}/{contract_name}/{map_name}', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify("text"),
});
const data = await response.json();

Get contract source

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

GEThttp://localhost:20443/v2/contracts/source/{contract_address}/{contract_name}

Path parameters

contract_address*string

Stacks address

contract_name*string

Contract name

Query parameters

Response

200

Success

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:20443/v2/contracts/source/{contract_address}/{contract_name}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Call read-only function

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

The smart contract and function are specified using the URL path. The arguments and the simulated tx-sender are supplied via the POST body in the following JSON format:

POSThttp://localhost:20443/v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}

Path parameters

contract_address*string

Stacks address

contract_name*string

Contract name

function_name*string

Function name

Query parameters

Body

application/json

map of arguments and the simulated tx-sender where sender is either a Contract identifier or a normal Stacks address, and arguments is an array of hex serialized Clarity values.

any

Response

200

Success

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:20443/v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
});
const data = await response.json();

Get account info

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.

GEThttp://localhost:20443/v2/accounts/{principal}

Path parameters

principal*string

Stacks address or a Contract identifier (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info)

Query parameters

Response

200

Success

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:20443/v2/accounts/{principal}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get approximate fees for the given transaction

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)

POSThttp://localhost:20443/v2/fees/transaction

Body

application/json

any

Response

200

Estimated fees for the transaction

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:20443/v2/fees/transaction', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
});
const data = await response.json();

Get estimated fee

Get an estimated fee rate for STX transfer transactions. This a a fee rate / byte, and is returned as a JSON integer

GEThttp://localhost:20443/v2/fees/transfer

Response

200

Success

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:20443/v2/fees/transfer', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get Core API info

Get Core API information

GEThttp://localhost:20443/v2/info

Response

200

Success

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:20443/v2/info', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get PoX details

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

GEThttp://localhost:20443/v2/pox

Query parameters

Response

200

Success

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:20443/v2/pox', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get trait implementation details

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

GEThttp://localhost:20443/v2/traits/{contract_address}/{contract_name}/{trait_contract_address}/{trait_contract_name}/{trait_name}

Path parameters

contract_address*string

Stacks address

contract_name*string

Contract name

trait_contract_address*string

Trait Stacks address

trait_contract_name*string

Trait contract name

trait_name*string

Trait name

Query parameters

Response

200

Success

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:20443/v2/traits/{contract_address}/{contract_name}/{trait_contract_address}/{trait_contract_name}/{trait_name}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get the value of a constant inside a contract

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.

POSThttp://localhost:20443/v2/constant_val/{contract_address}/{contract_name}/{constant_name}

Path parameters

contract_address*string

Stacks address

contract_name*string

Contract name

constant_name*string

Constant name

Query parameters

Response

200400

Success

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:20443/v2/constant_val/{contract_address}/{contract_name}/{constant_name}', {
    method: 'POST',
    headers: {},
});
const data = await response.json();