🛠️
Stacks Documentation
  • Start Here
  • 🧠Concepts
    • Stacks 101
      • What Is Stacks?
      • Bitcoin Connection
      • Proof of Transfer
      • Stacks Among Other Layers
      • Financial Incentive and Security Budget
    • Network Fundamentals
      • Network Basics
      • Mainnet and Testnets
      • Accounts
      • Authentication
      • Bitcoin Name System
      • SIPs
      • Technical Specifications
    • Block Production
      • Mining
      • Signing
      • Bitcoin Finality
      • Bitcoin Reorgs
      • Stacking
    • Transactions
      • How Transactions Work
      • Post Conditions
    • Clarity
      • Overview
      • Decidability
    • sBTC
      • Core Features
      • sBTC Operations
        • Deposit
        • Withdrawal
        • Deposit vs Withdrawal Times
      • Emily API
      • Peg Wallet UTXO
      • Clarity Contracts
        • sBTC Registry
        • sBTC Token
        • sBTC Deposit
        • sBTC Withdrawal
      • Auxiliary Features
        • Transaction Fee Sponsorship
        • Signer Wallet Rotation
      • Walkthroughs
        • Signer Process Walkthrough
        • sBTC Transaction Walkthrough
      • sBTC FAQ
    • Gaia
      • Configuration
      • Deploy Gaia Hub
      • Amazon EC2
      • Linux
      • Mac OS
  • 🛠️Guides & Tutorials
    • Developer Quickstart
    • Clarity Crash Course
    • Build a Borrowing & Lending Protocol
    • Bitcoin Integration
      • Sending Bitcoin with Leather Wallet
      • Verifying a Bitcoin Transaction
      • Parsing a Bitcoin Transaction
    • Create Tokens
      • Creating a NFT
      • Creating a Fungible Token
    • Build a Frontend
      • Post Conditions with Stacks.js
      • Authentication with Stacks.js
      • Sending Transactions with Stacks.js
    • Testing Smart Contracts
      • Fuzz Testing
    • Run a Node
      • Run a Node with Docker
      • Run a Node with Digital Ocean
      • Run a Node with a Hosted Provider
      • Run a Node with Quicknode
      • Run a Bitcoin Node
      • Run a Pruned Bitcoin Node
    • Run a Miner
      • Miner Prerequisites
      • Miner Costs and Fees
      • Mine Testnet Stacks Tokens
      • Mine Mainnet Stacks Tokens
      • Verify Miner
    • Run a Signer
      • Signer Quickstart
      • How to Read Signer Logs
      • How to Monitor a Signer
      • Best practices for running a Signer
      • OpSec Best Practices
    • sBTC
      • How to Run an sBTC Signer
      • Best practices for running an sBTC Signer
      • How to Use the sBTC Bridge
      • Earn sBTC Rewards
    • Stack STX
      • Solo Stack
      • Operate a Pool
      • Stack with a Pool
      • Increase Stacked Position
      • Stop Stacking
    • Oracles
    • Community Tutorials
  • 📚Reference
    • API
    • Clarity Types
    • Clarity Functions
    • Clarity Keywords
    • Stacks Node Configuration
    • Signer Configuration
    • Stacks Tooling
  • 🏗️Example Contracts
    • Audited Starter Contracts
    • Stacking
    • BNS
    • Multi Send
  • 🧡Press & Top Links
    • 🔶2024
      • 🔸January 2024
      • 🔸February 2024
      • 🔸March 2024
      • 🔸April 2024
      • 🔸May 2024
      • 🔸June 2024
      • 🔸July 2024
      • 🔸August 2024
      • 🔸September 2024
      • 🔸October 2024
      • 🔸November 2024
      • 🔸December 2024
    • 🔶2025
      • 🔸January 2025
      • 🔸February 2025
      • 🔸March 2025
  • 🧡Bitcoin Theses and Reports
    • 🟠Bitcoin Theses
    • 📙Bitcoin Reports
  • Contribute
Powered by GitBook
On this page

Was this helpful?

  1. Reference

API

PreviousCommunity TutorialsNextClarity Types

Last updated 3 months ago

Was this helpful?

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 and the 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 .

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/

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.

📚
Stacks Node RPC API
Hiro Stacks API
run your own API server

Get contract interface

get

Get contract interface using a contract_address and contract name

Path parameters
contract_addressstringRequired

Stacks address

contract_namestringRequired

Contract name

Query parameters
tipstringOptional

The Stacks chain tip to query from. If tip == latest, the query will be run from the latest known tip (includes unconfirmed state).

Responses
200
Contract interface
application/json
get
GET /v2/contracts/interface/{contract_address}/{contract_name} HTTP/1.1
Host: localhost:20443
Accept: */*
200

Contract interface

{
  "functions": [
    {
      "name": "get-value",
      "access": "public",
      "args": [
        {
          "name": "key",
          "type": {
            "buffer": {
              "length": 32
            }
          }
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": {
              "buffer": {
                "length": 32
              }
            },
            "error": "int128"
          }
        }
      }
    },
    {
      "name": "set-value",
      "access": "public",
      "args": [
        {
          "name": "key",
          "type": {
            "buffer": {
              "length": 32
            }
          }
        },
        {
          "name": "value",
          "type": {
            "buffer": {
              "length": 32
            }
          }
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "uint128",
            "error": "none"
          }
        }
      }
    },
    {
      "name": "test-emit-event",
      "access": "public",
      "args": [],
      "outputs": {
        "type": {
          "response": {
            "ok": "uint128",
            "error": "none"
          }
        }
      }
    },
    {
      "name": "test-event-types",
      "access": "public",
      "args": [],
      "outputs": {
        "type": {
          "response": {
            "ok": "uint128",
            "error": "none"
          }
        }
      }
    }
  ],
  "variables": [
    {
      "name": "recipient",
      "type": "principal",
      "access": "constant"
    },
    {
      "name": "sender",
      "type": "principal",
      "access": "constant"
    }
  ],
  "maps": [
    {
      "name": "store",
      "key": [
        {
          "name": "key",
          "type": {
            "buffer": {
              "length": 32
            }
          }
        }
      ],
      "value": [
        {
          "name": "value",
          "type": {
            "buffer": {
              "length": 32
            }
          }
        }
      ]
    }
  ],
  "fungible_tokens": [
    {
      "name": "novel-token-19"
    }
  ],
  "non_fungible_tokens": [
    {
      "name": "hello-nft",
      "type": "uint128"
    }
  ]
}

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_addressstringRequired

Stacks address

contract_namestringRequired

Contract name

Query parameters
proofintegerOptional

Returns object without the proof field if set to 0

tipstringOptional

The Stacks chain tip to query from. If tip == latest, the query will be run from the latest known tip (includes unconfirmed state).

Responses
200
Success
application/json
get
GET /v2/contracts/source/{contract_address}/{contract_name} HTTP/1.1
Host: localhost:20443
Accept: */*
200

Success

{
  "source": "(define-constant sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)\n(define-constant recipient 'SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G)\n\n(define-fungible-token novel-token-19)\n(begin (ft-mint? novel-token-19 u12 sender))\n(begin (ft-transfer? novel-token-19 u2 sender recipient))\n\n(define-non-fungible-token hello-nft uint)\n(begin (nft-mint? hello-nft u1 sender))\n(begin (nft-mint? hello-nft u2 sender))\n(begin (nft-transfer? hello-nft u1 sender recipient))\n\n(define-public (test-emit-event)\n    (begin\n        (print \"Event! Hello world\")\n        (ok u1)))\n(begin (test-emit-event))\n\n(define-public (test-event-types)\n    (begin\n        (unwrap-panic (ft-mint? novel-token-19 u3 recipient))\n        (unwrap-panic (nft-mint? hello-nft u2 recipient))\n        (unwrap-panic (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR))\n        (unwrap-panic (stx-burn? u20 tx-sender))\n        (ok u1)))\n\n(define-map store ((key (buff 32))) ((value (buff 32))))\n(define-public (get-value (key (buff 32)))\n    (begin\n        (match (map-get? store ((key key)))\n            entry (ok (get value entry))\n            (err 0))))\n(define-public (set-value (key (buff 32)) (value (buff 32)))\n    (begin\n        (map-set store ((key key)) ((value value)))\n        (ok u1)))",
  "publish_height": 3196,
  "proof": "0000001104060000001ec4e..."
}

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.

Path parameters
principalstringRequired

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

Query parameters
proofintegerOptional

Returns object without the proof field if set to 0

tipstringOptional

The Stacks chain tip to query from. If tip == latest, the query will be run from the latest known tip (includes unconfirmed state).

Responses
200
Success
application/json
get
GET /v2/accounts/{principal} HTTP/1.1
Host: localhost:20443
Accept: */*
200

Success

{
  "balance": "0x0000000000000000000000000007a120",
  "locked": "0x0000000000000000000000000007a120",
  "unlock_height": 126,
  "nonce": 2867,
  "balance_proof": "0xabce",
  "nonce_proof": "0xabcd"
}

Get estimated fee

get

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

Responses
200
Success
application/json
Responseany
get
GET /v2/fees/transfer HTTP/1.1
Host: localhost:20443
Accept: */*
200

Success

{
  "$ref": "./api/core-node/get-fee-transfer.example.json"
}

Get Core API info

get

Get Core API information

Responses
200
Success
application/json
get
GET /v2/info HTTP/1.1
Host: localhost:20443
Accept: */*
200

Success

{
  "peer_version": 385875968,
  "pox_consensus": "17f76e597bab45646956f38dd39573085d72cbc0",
  "burn_block_height": 16,
  "stable_pox_consensus": "8e0561978fc5506b68a589c402dad97e862edb59",
  "stable_burn_block_height": 15,
  "server_version": "blockstack-core 0.0.1 => 23.0.0.0 (, release build, linux [x86_64])",
  "network_id": 2147483648,
  "parent_network_id": 3669344250,
  "stacks_tip_height": 15,
  "stacks_tip": "b1807a2d3f7f8c7922f7c1d60d7c34145ade05d789640dc7dc9ec1021e07bb54",
  "stacks_tip_consensus_hash": "17f76e597bab45646956f38dd39573085d72cbc0",
  "unanchored_tip": "0000000000000000000000000000000000000000000000000000000000000000",
  "tenure_height": 523,
  "exit_at_block_height": null,
  "is_fully_synced": false
}

Get PoX details

get

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

Query parameters
tipstringOptional

The Stacks chain tip to query from. If tip == latest, the query will be run from the latest known tip (includes unconfirmed state).

Responses
200
Success
application/json
get
GET /v2/pox HTTP/1.1
Host: localhost:20443
Accept: */*
200

Success

{
  "contract_id": "SP000000000000000000002Q6VF78.pox",
  "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
    }
  ]
}

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_addressstringRequired

Stacks address

contract_namestringRequired

Contract name

trait_contract_addressstringRequired

Trait Stacks address

trait_contract_namestringRequired

Trait contract name

trait_namestringRequired

Trait name

Query parameters
tipstringOptional

The Stacks chain tip to query from. If tip == "latest", the query will be run from the latest known tip (includes unconfirmed state). If the tip is left unspecified, the stacks chain tip will be selected (only includes confirmed state).

Responses
200
Success
application/json
get
GET /v2/traits/{contract_address}/{contract_name}/{trait_contract_address}/{trait_contract_name}/{trait_name} HTTP/1.1
Host: localhost:20443
Accept: */*
200

Success

{
  "$ref": "./api/trait/get-is-trait-implemented.example.json"
}

Get the MARF value for a given key

post

Attempt to fetch the value of a MARF key.

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

Path parameters
clarity_marf_keystringRequired

MARF key

Query parameters
proofintegerOptional

Returns object without the proof field when set to 0

tipstringOptional

The Stacks chain tip to query from. If tip == latest, the query will be run from the latest known tip (includes unconfirmed state).

Responses
200
Success
application/json
400
Failed to retrieve MARF key
post
POST /v2/clarity/marf/{clarity_marf_key} HTTP/1.1
Host: localhost:20443
Accept: */*
{
  "data": "0x0a0c000000010a6d6f6e737465722d69640100000000000000000000000000000001",
  "proof": "0x123..."
}

Get the contract metadata for the metadata key

post

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_addressstringRequired

Stacks address

contract_namestringRequired

Contract name

clarity_metadata_keystringRequired

Metadata key

Query parameters
tipstringOptional

The Stacks chain tip to query from. If tip == latest, the query will be run from the latest known tip (includes unconfirmed state).

Responses
200
Success
application/json
400
Failed to retrieve constant value from contract
post
POST /v2/clarity/metadata/{contract_address}/{contract_name}/{clarity_metadata_key} HTTP/1.1
Host: localhost:20443
Accept: */*
{
  "data": "'{\"contract_identifier\":{...}, \"private_function_types\":{...}'"
}

Get the value of a constant inside a contract

post

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_addressstringRequired

Stacks address

contract_namestringRequired

Contract name

constant_namestringRequired

Constant name

Query parameters
tipstringOptional

The Stacks chain tip to query from. If tip == latest, the query will be run from the latest known tip (includes unconfirmed state).

Responses
200
Success
application/json
400
Failed to retrieve constant value from contract
post
POST /v2/constant_val/{contract_address}/{contract_name}/{constant_name} HTTP/1.1
Host: localhost:20443
Accept: */*
{
  "data": "0x01ce..."
}

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
200
Information for the given reward cycle
application/json
400
Could not fetch the given reward set
application/json
get
GET /v3/stacker_set/{cycle_number} HTTP/1.1
Host: localhost:20443
Accept: */*
{
  "stacker_set": {
    "rewarded_addresses": [
      {
        "Standard": [
          {
            "bytes": "dc5f18421006ee2b98ab972edfa7268a981e3f00",
            "version": 26
          },
          "SerializeP2PKH"
        ]
      }
    ],
    "signers": [
      {
        "signing_key": "02d0a27e4f1bf186b4391eecfcc4d4a0d403684ad089b477b8548a69dd6378bf26",
        "slots": 1,
        "stacked_amt": 2143020000000000
      }
    ],
    "start_cycle_state": {
      "missed_reward_slots": []
    }
  }
}

Fetch a Nakamoto block

get

Fetch a Nakamoto block by its index block hash.

Path parameters
block_idstringRequired

The block's ID hash

Responses
200
The raw SIP-003-encoded block will be returned.
application/octet-stream
Responsestring · binary
404
The block could not be found
application/text-plain
get
GET /v3/blocks/{block_id} HTTP/1.1
Host: localhost:20443
Accept: */*
binary

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

Query parameters
tipstringOptional

The Stacks chain tip to query from. If tip == latest or empty, the query will be run from the latest known tip.

Responses
200
The raw SIP-003-encoded block will be returned.
application/octet-stream
Responsestring · binary
404
The block could not be found
application/text-plain
get
GET /v3/blocks/height/{block_height} HTTP/1.1
Host: localhost:20443
Accept: */*
binary

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
200
Metadata about the ongoing tenure
application/json
get
GET /v3/tenures/info HTTP/1.1
Host: localhost:20443
Accept: */*
200

Metadata about the ongoing tenure

{
  "consensus_hash": "4c5a49be0e34dc603b66f090fd07d28a2f76a2ad",
  "parent_consensus_hash": "fa8a04af41957499afdd4082b9b702ffca9a4370",
  "parent_tenure_start_block_id": "0cfec8433849d353ad6b2fe1173da143e3d4a3ab452588a14eb074d0181ac202",
  "reward_cycle": 8,
  "tenure_start_block_id": "0425099d51547c714df6a7864c040c1a605b198ff07f71d19a823139c88a35f8",
  "tip_block_id": "52d64f5e47abc7666c4fed3fe850f381f93f2d588ee2a92a4e07b44f14588d5e",
  "tip_height": 416
}

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
200
SIP-003-encoded Nakamoto blocks, concatenated together
application/octet-stream
Responsestring · binary
get
GET /v3/tenures/{block_id} HTTP/1.1
Host: localhost:20443
Accept: */*
200

SIP-003-encoded Nakamoto blocks, concatenated together

binary

Fetch information about evaluated burnchain blocks (i.e., sortitions).

get

Fetch sortition information about a burnchain block. If the lookup_kind and lookup parameters are empty, it will return information about the latest burn block.

Path parameters
lookup_kindstringOptional

The style of lookup that should be performed. If not given, the most recent burn block processed will be returned. Otherwise, the lookup_kind should be one of the following strings:

  • consensus - find the burn block using the consensus hash supplied in the lookup field.
  • burn_height - find the burn block using the burn block height supplied in the lookup field.
  • burn - find the burn block using the burn block hash supplied in the lookup field.
  • latest_and_last - return information about the latest burn block with a winning miner and the previous such burn block
lookupstringOptional

The value to use for the lookup if lookup_kind is consensus, burn_height, or burn

Responses
200
Information for the burn block or in the case of `latest_and_last`, multiple burn blocks
application/json
get
GET /v3/sortitions/{lookup_kind}/{lookup} HTTP/1.1
Host: localhost:20443
Accept: */*
200

Information for the burn block or in the case of latest_and_last, multiple burn blocks

{
  "0": {
    "burn_block_hash": "0x046f54cd1924a5d80fc3b8186d0334b7521acae90f9e136e2bee680c720d0e83",
    "burn_block_height": 231,
    "burn_header_timestamp": 1726797570,
    "sortition_id": "0x8a5116b7b4306dc4f6db290d1adfff9e1347f3e921bb793fc4c33e2ff05056e2",
    "parent_sortition_id": "0xdaf479110cf859e58c56b6ae941f8a14e7c7992c57027183dfbda4a4b820897c",
    "consensus_hash": "0x8d2c51db737597a93191f49bcdc9c7bb44b90892",
    "was_sortition": true,
    "miner_pk_hash160": "0x6bc51b33e9f3626944eb879147e18111581f8f9b",
    "stacks_parent_ch": "0x697357c72da55b759b1d6b721676c92c69f0b490",
    "last_sortition_ch": "0x697357c72da55b759b1d6b721676c92c69f0b490",
    "committed_block_hash": "0xeea47d6d639c565027110e192e308fb11656183d5c077bcd718d830652800183",
    "vrf_seed": "0x48b754acc291a5bfad1354ee19bbc471f14af2b21dc7eccc0f929bd16798defe"
  }
}

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
signerstringRequired

Hex-encoded compressed Secp256k1 public key of signer

cycle_numberintegerRequired

Reward cycle number

Responses
200
Number of blocks signed
text/plain
ResponseintegerExample: 7
get
GET /v3/signer/{signer}/{cycle_number} HTTP/1.1
Host: localhost:20443
Accept: */*
200

Number of blocks signed

7
  • Introduction
  • Stacks Node RPC API endpoints
  • POSTBroadcast raw transaction
  • GETGet contract interface
  • POSTGet specific data-map inside a contract
  • GETGet contract source
  • POSTCall read-only function
  • GETGet account info
  • POSTGet approximate fees for the given transaction
  • GETGet estimated fee
  • GETGet Core API info
  • GETGet PoX details
  • GETGet trait implementation details
  • POSTGet the MARF value for a given key
  • POSTGet the contract metadata for the metadata key
  • POSTGet the value of a constant inside a contract
  • POSTValidate a proposed Stacks block
  • GETFetch the stacker and signer set information for a given cycle.
  • GETFetch a Nakamoto block
  • GETFetch a Nakamoto block by its height and optional tip
  • GETFetch metadata about the ongoing Nakamoto tenure
  • GETFetch a sequence of Nakamoto blocks in a tenure
  • GETFetch information about evaluated burnchain blocks (i.e., sortitions).
  • GETGet number of blocks signed by signer during a given reward cycle

Broadcast raw transaction

post

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

Body
string · binaryOptional
Responses
200
Transaction ID of successful post of a raw tx to the node's mempool
text/plain
ResponsestringExample: "e161978626f216b2141b156ade10501207ae535fa365a13ef5d7a7c9310a09f2"
400
Rejections result in a 400 error
application/json
post
POST /v2/transactions HTTP/1.1
Host: localhost:20443
Content-Type: application/octet-stream
Accept: */*
Content-Length: 379

"binary format of 00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000"
"e161978626f216b2141b156ade10501207ae535fa365a13ef5d7a7c9310a09f2"

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

Path parameters
contract_addressstringRequired

Stacks address

contract_namestringRequired

Contract name

map_namestringRequired

Map name

Query parameters
proofintegerOptional

Returns object without the proof field when set to 0

tipstringOptional

The Stacks chain tip to query from. If tip == latest, the query will be run from the latest known tip (includes unconfirmed state).

Body
stringOptional
Responses
200
Success
application/json
400
Failed loading data map
post
POST /v2/map_entry/{contract_address}/{contract_name}/{map_name} HTTP/1.1
Host: localhost:20443
Content-Type: application/json
Accept: */*
Content-Length: 6

"text"
{
  "data": "0x0a0c000000010a6d6f6e737465722d69640100000000000000000000000000000001",
  "proof": "0x123..."
}

Call read-only function

post

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:

Path parameters
contract_addressstringRequired

Stacks address

contract_namestringRequired

Contract name

function_namestringRequired

Function name

Query parameters
tipstringOptional

The Stacks chain tip to query from. If tip == latest, the query will be run from the latest known tip (includes unconfirmed state).

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

argumentsstring[]Required

An array of hex serialized Clarity values

Responses
200
Success
application/json
post
POST /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name} HTTP/1.1
Host: localhost:20443
Content-Type: application/json
Accept: */*
Content-Length: 102

{
  "sender": "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info",
  "arguments": [
    "0x0011...",
    "0x00231..."
  ]
}
200

Success

{
  "okay": true,
  "result": "0x111..."
}

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
200
Estimated fees for the transaction
application/json
post
POST /v2/fees/transaction HTTP/1.1
Host: localhost:20443
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "estimated_len": 350,
  "transaction_payload": "021af942874ce525e87f21bbe8c121b12fac831d02f4086765742d696e666f0b7570646174652d696e666f00000000"
}
200

Estimated fees for the transaction

{
  "$ref": "./api/core-node/post-fee-transaction-response.example.json"
}

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.

Body
anyOptional
Responses
202
Block proposal has been accepted for processing. The result will be returned via the event observer.
application/json
400
Endpoint not enabled.
401
Unauthorized.
429
There is an ongoing proposal validation being processed, the new request cannot be accepted until the prior request has been processed.
application/json
post
POST /v3/block_proposal HTTP/1.1
Host: localhost:20443
Content-Type: application/json
Accept: */*
Content-Length: 63

{
  "$ref": "./api/core-node/post-block-proposal-req.example.json"
}
{
  "message": "Block proposal is processing, result will be returned via the event observer",
  "result": "Accepted"
}