Documentation Powered by Redocly

Stacks Blockchain API (v7.11.0-beta.7)

Download OpenAPI specification:Download

Welcome to the API reference overview for the Stacks Blockchain API.

Download Postman collection

Accounts

Read-only endpoints to obtain Stacks account details

Stacks Documentation - Accounts

Get account balances

Retrieves total account balance information for a given Address or Contract Identifier. This includes the balances of STX Tokens, Fungible Tokens and Non-Fungible Tokens for the account.

path Parameters
principal
required
string
Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0

Stacks address or a Contract identifier

query Parameters
unanchored
boolean
Default: false
Example: unanchored=true

Include transaction data from unanchored (i.e. unconfirmed) microblocks

until_block
string
Example: until_block=60000

returned data representing the state up until that point in time, rather than the current block.

Responses

Response samples

Content type
application/json
{
  • "stx": {
    },
  • "fungible_tokens": { },
  • "non_fungible_tokens": { }
}

Get account STX balance

Retrieves STX token balance for a given Address or Contract Identifier.

path Parameters
principal
required
string
Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0

Stacks address or a Contract identifier.

query Parameters
unanchored
boolean
Default: false
Example: unanchored=true

Include transaction data from unanchored (i.e. unconfirmed) microblocks.

until_block
string
Example: until_block=60000

returned data representing the state up until that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time.

Responses

Response samples

Content type
application/json
{
  • "balance": "1000000",
  • "total_sent": "0",
  • "total_received": "1000000",
  • "lock_tx_id": "0xec94e7d20af8979b44d17a0520c126bf742b999a0fc7ddbcbe0ab21b228ecc8c",
  • "locked": "50000",
  • "lock_height": 100,
  • "burnchain_lock_height": 100,
  • "burnchain_unlock_height": 200
}

Get account transactions Deprecated

Retrieves a list of all Transactions for a given Address or Contract Identifier. More information on Transaction types can be found here.

If you need to actively monitor new transactions for an address or contract id, we highly recommend subscribing to WebSockets or Socket.io for real-time updates.

path Parameters
principal
required
string
Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0

Stacks address or a Contract identifier

query Parameters
limit
integer
Example: limit=42000

max number of account transactions to fetch

offset
integer
Example: offset=42000

index of first account transaction to fetch

height
number
Example: height=42000

Filter for transactions only at this given block height

unanchored
boolean
Default: false
Example: unanchored=true

Include transaction data from unanchored (i.e. unconfirmed) microblocks

until_block
string
Example: until_block=60000

returned data representing the state up until that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time.

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 4989,
  • "results": [
    ]
}

Get account transaction information for specific transaction Deprecated

Retrieves transaction details for a given Transaction Id tx_id, for a given account or contract Identifier.

path Parameters
principal
required
string
Example: SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE

Stacks address or a contract identifier

tx_id
required
string
Example: 0x34d79c7cfc2fe525438736733e501a4bf0308a5556e3e080d1e2c0858aad7448

Transaction id

Responses

Response samples

Content type
application/json
{
  • "tx_id": "0x34d79c7cfc2fe525438736733e501a4bf0308a5556e3e080d1e2c0858aad7448",
  • "tx_type": "contract_call",
  • "nonce": 11,
  • "fee_rate": "346",
  • "sender_address": "SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE",
  • "sponsored": false,
  • "post_condition_mode": "deny",
  • "tx_status": "success",
  • "block_hash": "0x13d1b4ad35c95bca209397420fb8af104d2929d91993ba056d7a1ca5470095f9",
  • "block_height": 3246,
  • "burn_block_time": 1613009951,
  • "burn_block_time_iso": "2021-02-11T02:19:11.000Z",
  • "canonical": true,
  • "is_unanchored": false,
  • "microblock_hash": "0x590a1bb1d7bcbeafce0a9fc8f8a69e369486192d14687fe95fbe4dc1c71d49df",
  • "microblock_sequence": 5,
  • "microblock_canonical": true,
  • "tx_index": 1,
  • "tx_result": {
    },
  • "post_conditions": [
    ],
  • "contract_call": {
    },
  • "events": [ ],
  • "event_count": 4
}

Get account transactions including STX transfers for each transaction. Deprecated

Retrieve all transactions for an account or contract identifier including STX transfers for each transaction.

path Parameters
principal
required
string
Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0

Stacks address or a Contract identifier

query Parameters
limit
integer
Example: limit=20

max number of account transactions to fetch

offset
integer
Example: offset=10

index of first account transaction to fetch

height
number
Example: height=66119

Filter for transactions only at this given block height

unanchored
boolean
Default: false
Example: unanchored=true

Include transaction data from unanchored (i.e. unconfirmed) microblocks

until_block
string
Example: until_block=60000

returned data representing the state up until that point in time, rather than the current block.

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 2,
  • "results": [
    ]
}

Get the latest nonce used by an account

Retrieves the latest nonce values used by an account by inspecting the mempool, microblock transactions, and anchored transactions.

path Parameters
principal
required
string
Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0

Stacks address

query Parameters
block_height
number
Example: block_height=66119

Optionally get the nonce at a given block height.

block_hash
string
Example: block_hash=0x72d53f3cba39e149dcd42708e535bdae03d73e60d2fe853aaf61c0b392f521e9

Optionally get the nonce at a given block hash. Note - Use either of the query parameters but not both at a time.

Responses

Response samples

Content type
application/json
{
  • "last_mempool_tx_nonce": 5,
  • "last_executed_tx_nonce": 2,
  • "possible_next_nonce": 6,
  • "detected_missing_nonces": [
    ],
  • "detected_mempool_nonces": [ ]
}

Get account assets

Retrieves a list of all assets events associated with an account or a Contract Identifier. This includes Transfers, Mints.

path Parameters
principal
required
string
Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0

Stacks address or a Contract identifier

query Parameters
limit
integer
Example: limit=20

max number of account assets to fetch

offset
integer
Example: offset=42000

index of first account assets to fetch

unanchored
boolean
Default: false
Example: unanchored=true

Include transaction data from unanchored (i.e. unconfirmed) microblocks

until_block
string
Example: until_block=60000

returned data representing the state at that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time.

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 0,
  • "results": [
    ]
}

Get inbound STX transfers

Retrieves a list of STX transfers with memos to the given principal. This includes regular transfers from a stx-transfer transaction type, and transfers from contract-call transactions a the send-many-memo bulk sending contract.

path Parameters
principal
required
string
Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0

Stacks address or a Contract identifier

query Parameters
limit
integer

number of items to return

offset
integer
Example: offset=42000

number of items to skip

height
number

Filter for transfers only at this given block height

unanchored
boolean
Default: false
Example: unanchored=true

Include transaction data from unanchored (i.e. unconfirmed) microblocks

until_block
string
Example: until_block=60000

returned data representing the state up until that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time.

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 0,
  • "results": [
    ]
}

Get account info

Retrieves the account data for a given Account or a Contract Identifier

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

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

path Parameters
principal
required
string
Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0

Stacks address or a Contract identifier

query Parameters
proof
integer

Returns object without the proof field if set to 0

tip
string

The Stacks chain tip to query from

Responses

Response samples

Content type
application/json
{
  • "balance": "0x0000000000000000000000000007a120",
  • "locked": "0x0000000000000000000000000007a120",
  • "unlock_height": 126,
  • "nonce": 2867,
  • "balance_proof": "0xabce",
  • "nonce_proof": "0xabcd"
}

Blocks

Read-only endpoints to obtain Stacks block details

Get blocks by burn block

Retrieves a list of blocks confirmed by a specific burn block

path Parameters
required
integer or string

filter by burn block height, hash, or the constant latest to filter for the most recent burn block

query Parameters
limit
integer
Example: limit=20

max number of blocks to fetch

offset
integer
Example: offset=0

index of first burn block to fetch

Responses

Response samples

Content type
application/json
{
  • "limit": 1,
  • "offset": 0,
  • "total": 21707,
  • "results": [
    ]
}

Get blocks

Retrieves a list of recently mined blocks

query Parameters
limit
integer
Example: limit=20

max number of blocks to fetch

offset
integer
Example: offset=0

index of first burn block to fetch

Responses

Response samples

Content type
application/json
{
  • "limit": 1,
  • "offset": 0,
  • "total": 21707,
  • "results": [
    ]
}

Get average block times

Retrieves average block times (in seconds)

Responses

Response samples

Content type
application/json
{
  • "last_1h": 846.75,
  • "last_24h": 635.2,
  • "last_7d": 731.26,
  • "last_30d": 738.67
}

Get block

Retrieves a single block

path Parameters
required
integer or string

filter by block height, hash, index block hash or the constant latest to filter for the most recent block

Responses

Response samples

Content type
application/json
{
  • "canonical": true,
  • "height": 3275,
  • "hash": "0xe77ba8cf6bb7c0e4f64adc83356289ed467d31a22354907b4bb814590058430f",
  • "block_time": 1594233639,
  • "block_time_iso": "2020-08-27T16:41:26.000Z",
  • "index_block_hash": "0x918697ef63f9d8bdf844c3312b299e72a231cde542f3173f7755bb8c1cdaf3a7",
  • "parent_block_hash": "0x75ab21ef25cbff2caa14c27d830ed7886a4d1522e1b6f9e5dc3b59ccf73ed49f",
  • "parent_index_block_hash": "0x4262db117659d1ca9406970c8f44ffd3d8f11f8e18c591d2e3960f4070107756",
  • "burn_block_time": 1594233639,
  • "burn_block_time_iso": "2020-08-27T16:41:26.000Z",
  • "burn_block_hash": "0xb154c008df2101023a6d0d54986b3964cee58119eed14f5bed98e15678e18fe2",
  • "burn_block_height": 654439,
  • "miner_txid": "0xd7d56070277ccd87b42acf0c91f915dd181f9db4cf878a4e95518bc397c240cc",
  • "tx_count": 3,
  • "execution_cost_read_count": 2477,
  • "execution_cost_read_length": 1659409,
  • "execution_cost_runtime": 2520952000,
  • "execution_cost_write_count": 608,
  • "execution_cost_write_length": 80170
}

Get recent blocks Deprecated

NOTE: This endpoint is deprecated in favor of Get blocks.

Retrieves a list of recently mined blocks

If you need to actively monitor new blocks, we highly recommend subscribing to WebSockets or Socket.io for real-time updates.

query Parameters
limit
integer <= 30
Default: 20

max number of blocks to fetch

offset
integer
Example: offset=42000

index of first block to fetch

Responses

Response samples

Content type
application/json
{
  • "limit": 1,
  • "offset": 0,
  • "total": 21707,
  • "results": [
    ]
}

Get block by hash Deprecated

NOTE: This endpoint is deprecated in favor of Get block.

Retrieves block details of a specific block for a given chain height. You can use the hash from your latest block ('get_block_list' API) to get your block details.

path Parameters
hash
required
string
Example: 0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79

Hash of the block

Responses

Response samples

Content type
application/json
{
  • "canonical": true,
  • "height": 3275,
  • "hash": "0xe77ba8cf6bb7c0e4f64adc83356289ed467d31a22354907b4bb814590058430f",
  • "block_time": 1594233639,
  • "block_time_iso": "2020-08-27T16:41:26.000Z",
  • "index_block_hash": "0x918697ef63f9d8bdf844c3312b299e72a231cde542f3173f7755bb8c1cdaf3a7",
  • "parent_block_hash": "0x75ab21ef25cbff2caa14c27d830ed7886a4d1522e1b6f9e5dc3b59ccf73ed49f",
  • "burn_block_time": 1594233639,
  • "burn_block_time_iso": "2020-08-27T16:41:26.000Z",
  • "burn_block_hash": "0xb154c008df2101023a6d0d54986b3964cee58119eed14f5bed98e15678e18fe2",
  • "burn_block_height": 654439,
  • "miner_txid": "0xd7d56070277ccd87b42acf0c91f915dd181f9db4cf878a4e95518bc397c240cc",
  • "parent_microblock_hash": "0x590a1bb1d7bcbeafce0a9fc8f8a69e369486192d14687fe95fbe4dc1c71d49df",
  • "parent_microblock_sequence": 2,
  • "txs": [
    ],
  • "microblocks_accepted": [
    ],
  • "microblocks_streamed": [
    ],
  • "execution_cost_read_count": 2477,
  • "execution_cost_read_length": 1659409,
  • "execution_cost_runtime": 2520952000,
  • "execution_cost_write_count": 608,
  • "execution_cost_write_length": 80170,
  • "microblock_tx_count": {
    }
}

Get block by height Deprecated

NOTE: This endpoint is deprecated in favor of Get block.

Retrieves block details of a specific block at a given block height

path Parameters
height
required
number
Example: 10000

Height of the block

Responses

Response samples

Content type
application/json
{
  • "canonical": true,
  • "height": 3275,
  • "hash": "0xe77ba8cf6bb7c0e4f64adc83356289ed467d31a22354907b4bb814590058430f",
  • "block_time": 1594233639,
  • "block_time_iso": "2020-08-27T16:41:26.000Z",
  • "index_block_hash": "0x918697ef63f9d8bdf844c3312b299e72a231cde542f3173f7755bb8c1cdaf3a7",
  • "parent_block_hash": "0x75ab21ef25cbff2caa14c27d830ed7886a4d1522e1b6f9e5dc3b59ccf73ed49f",
  • "burn_block_time": 1594233639,
  • "burn_block_time_iso": "2020-08-27T16:41:26.000Z",
  • "burn_block_hash": "0xb154c008df2101023a6d0d54986b3964cee58119eed14f5bed98e15678e18fe2",
  • "burn_block_height": 654439,
  • "miner_txid": "0xd7d56070277ccd87b42acf0c91f915dd181f9db4cf878a4e95518bc397c240cc",
  • "parent_microblock_hash": "0x590a1bb1d7bcbeafce0a9fc8f8a69e369486192d14687fe95fbe4dc1c71d49df",
  • "parent_microblock_sequence": 2,
  • "txs": [
    ],
  • "microblocks_accepted": [
    ],
  • "microblocks_streamed": [
    ],
  • "execution_cost_read_count": 2477,
  • "execution_cost_read_length": 1659409,
  • "execution_cost_runtime": 2520952000,
  • "execution_cost_write_count": 608,
  • "execution_cost_write_length": 80170,
  • "microblock_tx_count": {
    }
}

Get block by burnchain block hash Deprecated

NOTE: This endpoint is deprecated in favor of Get blocks.

Retrieves block details of a specific block for a given burnchain block hash

path Parameters
burn_block_hash
required
string
Example: 0x00000000000000000002bba732926cf68b6eda3e2cdbc2a85af79f10efeeeb10

Hash of the burnchain block

Responses

Response samples

Content type
application/json
{
  • "canonical": true,
  • "height": 3275,
  • "hash": "0xe77ba8cf6bb7c0e4f64adc83356289ed467d31a22354907b4bb814590058430f",
  • "block_time": 1594233639,
  • "block_time_iso": "2020-08-27T16:41:26.000Z",
  • "index_block_hash": "0x918697ef63f9d8bdf844c3312b299e72a231cde542f3173f7755bb8c1cdaf3a7",
  • "parent_block_hash": "0x75ab21ef25cbff2caa14c27d830ed7886a4d1522e1b6f9e5dc3b59ccf73ed49f",
  • "burn_block_time": 1594233639,
  • "burn_block_time_iso": "2020-08-27T16:41:26.000Z",
  • "burn_block_hash": "0xb154c008df2101023a6d0d54986b3964cee58119eed14f5bed98e15678e18fe2",
  • "burn_block_height": 654439,
  • "miner_txid": "0xd7d56070277ccd87b42acf0c91f915dd181f9db4cf878a4e95518bc397c240cc",
  • "parent_microblock_hash": "0x590a1bb1d7bcbeafce0a9fc8f8a69e369486192d14687fe95fbe4dc1c71d49df",
  • "parent_microblock_sequence": 2,
  • "txs": [
    ],
  • "microblocks_accepted": [
    ],
  • "microblocks_streamed": [
    ],
  • "execution_cost_read_count": 2477,
  • "execution_cost_read_length": 1659409,
  • "execution_cost_runtime": 2520952000,
  • "execution_cost_write_count": 608,
  • "execution_cost_write_length": 80170,
  • "microblock_tx_count": {
    }
}

Get block by burnchain height Deprecated

NOTE: This endpoint is deprecated in favor of Get blocks.

Retrieves block details of a specific block for a given burn chain height

path Parameters
burn_block_height
required
number
Example: 744603

Height of the burn chain block

Responses

Response samples

Content type
application/json
{
  • "canonical": true,
  • "height": 3275,
  • "hash": "0xe77ba8cf6bb7c0e4f64adc83356289ed467d31a22354907b4bb814590058430f",
  • "block_time": 1594233639,
  • "block_time_iso": "2020-08-27T16:41:26.000Z",
  • "index_block_hash": "0x918697ef63f9d8bdf844c3312b299e72a231cde542f3173f7755bb8c1cdaf3a7",
  • "parent_block_hash": "0x75ab21ef25cbff2caa14c27d830ed7886a4d1522e1b6f9e5dc3b59ccf73ed49f",
  • "burn_block_time": 1594233639,
  • "burn_block_time_iso": "2020-08-27T16:41:26.000Z",
  • "burn_block_hash": "0xb154c008df2101023a6d0d54986b3964cee58119eed14f5bed98e15678e18fe2",
  • "burn_block_height": 654439,
  • "miner_txid": "0xd7d56070277ccd87b42acf0c91f915dd181f9db4cf878a4e95518bc397c240cc",
  • "parent_microblock_hash": "0x590a1bb1d7bcbeafce0a9fc8f8a69e369486192d14687fe95fbe4dc1c71d49df",
  • "parent_microblock_sequence": 2,
  • "txs": [
    ],
  • "microblocks_accepted": [
    ],
  • "microblocks_streamed": [
    ],
  • "execution_cost_read_count": 2477,
  • "execution_cost_read_length": 1659409,
  • "execution_cost_runtime": 2520952000,
  • "execution_cost_write_count": 608,
  • "execution_cost_write_length": 80170,
  • "microblock_tx_count": {
    }
}

Burn Blocks

Read-only endpoints to obtain burn block details

Get burn blocks

Retrieves a list of recent burn blocks

query Parameters
limit
integer <= 30
Default: 20

max number of burn blocks to fetch

offset
integer
Example: offset=42000

index of first burn block to fetch

Responses

Response samples

Content type
application/json
{
  • "limit": 1,
  • "offset": 0,
  • "total": 21707,
  • "results": [
    ]
}

Get burn block

Retrieves a single burn block

path Parameters
required
integer or string

filter by burn block height, hash, or the constant latest to filter for the most recent burn block

Responses

Response samples

Content type
application/json
{
  • "burn_block_time": 1594233639,
  • "burn_block_time_iso": "2020-08-27T16:41:26.000Z",
  • "burn_block_hash": "0xb154c008df2101023a6d0d54986b3964cee58119eed14f5bed98e15678e18fe2",
  • "burn_block_height": 654439,
  • "stacks_blocks": [
    ],
  • "avg_block_time": 15.3,
  • "total_tx_count": 728
}

Faucets

Endpoints to request STX or BTC tokens (not possible on Mainnet)

Get STX testnet tokens

Add 500 STX tokens to the specified testnet address. Testnet STX addresses begin with ST. If the stacking parameter is set to true, the faucet will add the required number of tokens for individual stacking to the specified testnet address.

The endpoint returns the transaction ID, which you can use to view the transaction in the Stacks Explorer. The tokens are delivered once the transaction has been included in an anchor block.

A common reason for failed faucet transactions is that the faucet has run out of tokens. If you are experiencing failed faucet transactions to a testnet address, you can get help in Discord.

Note: This is a testnet only endpoint. This endpoint will not work on the mainnet.

query Parameters
address
required
string
Example: address=ST3M7N9Q9HDRM7RVP1Q26P0EE69358PZZAZD7KMXQ

A valid testnet STX address

stacking
boolean
Default: false

Request the amount of STX tokens needed for individual address stacking

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "txId": "0xf2f0402f9f4c4d43b382690c4f7b97e24d5ff5dd5c619e3615daa64dca7ef4bc",
  • "txRaw": "80800000000400164247d6f2b425ac5771423ae6c80c754f7172b0000000000000003200000000000000b400008537046ff1008368baaa3ff2235122c556b89dad4f9df0639b924cf32a44b866497e49846b24191e711b21faaae96ca0542e4a140168484740b94211cececb3303020000000000051ab52c45b1a7977204f17ac0b6f48306aea2dbb8e9000000000007a12046617563657400000000000000000000000000000000000000000000000000000000"
}

Add testnet BTC tokens to address

Add 1 BTC token to the specified testnet BTC address.

The endpoint returns the transaction ID, which you can use to view the transaction in a testnet Bitcoin block explorer. The tokens are delivered once the transaction has been included in a block.

Note: This is a testnet only endpoint. This endpoint will not work on the mainnet.

query Parameters
address
required
string
Example: address=2N4M94S1ZPt8HfxydXzL2P7qyzgVq7MHWts

A valid testnet BTC address

Request Body schema: application/json
address
string

BTC testnet address

Responses

Request samples

Content type
application/json
{
  • "address": "2N4M94S1ZPt8HfxydXzL2P7qyzgVq7MHWts"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "txId": "0xf2f0402f9f4c4d43b382690c4f7b97e24d5ff5dd5c619e3615daa64dca7ef4bc",
  • "txRaw": "80800000000400164247d6f2b425ac5771423ae6c80c754f7172b0000000000000003200000000000000b400008537046ff1008368baaa3ff2235122c556b89dad4f9df0639b924cf32a44b866497e49846b24191e711b21faaae96ca0542e4a140168484740b94211cececb3303020000000000051ab52c45b1a7977204f17ac0b6f48306aea2dbb8e9000000000007a12046617563657400000000000000000000000000000000000000000000000000000000"
}

Fees

Read-only endpoints to obtain fee details

Get estimated fee

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

Responses

Response samples

Content type
application/json
1

Fetch fee rate Deprecated

NOTE: This endpoint is deprecated in favor of Get approximate fees for a given transaction.

Retrieves estimated fee rate.

Request Body schema: application/json
transaction
required
string

A serialized transaction

Responses

Request samples

Content type
application/json
{
  • "transaction": "0x5e9f3933e358df6a73fec0d47ce3e1062c20812c129f5294e6f37a8d27c051d9"
}

Response samples

Content type
application/json
{
  • "fee_rate": 360
}

Get approximate fees for a 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)

Request Body schema: application/json
transaction_payload
required
string
estimated_len
integer

Responses

Request samples

Content type
application/json
{
  • "estimated_len": 350,
  • "transaction_payload": "021af942874ce525e87f21bbe8c121b12fac831d02f4086765742d696e666f0b7570646174652d696e666f00000000"
}

Response samples

Content type
application/json
{
  • "cost_scalar_change_by_byte": 0.00476837158203125,
  • "estimated_cost": {
    },
  • "estimated_cost_scalar": 14,
  • "estimations": [
    ]
}

Info

Read-only endpoints to obtain network, Proof-of-Transfer, Stacking, STX token, and node information

Get Core API info

Retrieves information about the Core API including the server version

Responses

Response samples

Content type
application/json
{
  • "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",
  • "exit_at_block_height": null
}

API status

Retrieves the running status of the Stacks Blockchain API, including the server version and current chain tip information.

Responses

Response samples

Content type
application/json
{
  • "server_version": "stacks-blockchain-api v1.0.7 (master:77b25878)",
  • "status": "ready",
  • "chain_tip": {
    }
}

Get the network target block time

Retrieves the target block times for mainnet and testnet. The block time is hardcoded and will change throughout the implementation phases of the testnet.

Responses

Response samples

Content type
application/json
{
  • "testnet": {
    },
  • "mainnet": {
    }
}

Get a given network's target block time

Retrieves the target block time for a given network. The network can be mainnet or testnet. The block time is hardcoded and will change throughout the implementation phases of the testnet.

path Parameters
network
required
string
Enum: "testnet" "mainnet"
Example: mainnet

the target block time for a given network (testnet, mainnet).

Responses

Response samples

Content type
application/json
{
  • "target_block_time": 600
}

Get total and unlocked STX supply

Retrieves the total and unlocked STX supply. More information on Stacking can be found [here] (https://docs.stacks.co/understand-stacks/stacking). Note: This uses the estimated future total supply for the year 2050.

query Parameters
height
number
Example: height=200

Supply details are queried from specified block height. If the block height is not specified, the latest block height is taken as default value. Note that the block height is referred to the stacks blockchain.

Responses

Response samples

Content type
application/json
{
  • "unlocked_percent": "71.99",
  • "total_stx": "1352464600.000000",
  • "unlocked_stx": "973705260.219817",
  • "block_height": 3210
}

Get total STX supply in plain text format

Retrieves the total supply for STX tokens as plain text. Note: this uses the estimated future total supply for the year 2050.

Responses

Response samples

Content type
text/plain
123.456789

Get circulating STX supply in plain text format

Retrieves the STX tokens currently in circulation that have been unlocked as plain text.

Responses

Response samples

Content type
text/plain
123.456789

Get total and unlocked STX supply (results formatted the same as the legacy 1.0 API)

Retrieves total supply of STX tokens including those currently in circulation that have been unlocked. Note: this uses the estimated future total supply for the year 2050.

query Parameters
height
number
Example: height=200

Supply details are queried from specified block height. If the block height is not specified, the latest block height is taken as default value.

Responses

Response samples

Content type
application/json
{
  • "unlockedPercent": "71.99",
  • "totalStacks": "1352464600.000000",
  • "totalStacksFormatted": "1,352,464,600.000000",
  • "unlockedSupply": "973705260.219817",
  • "unlockedSupplyFormatted": "973,705,260.219817",
  • "blockHeight": "665746"
}

Get Proof-of-Transfer details

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

Responses

Response samples

Content type
application/json
{
  • "contract_id": "SP000000000000000000002Q6VF78.pox",
  • "pox_activation_threshold_ustx": 67694186237302,
  • "first_burnchain_block_height": 666050,
  • "prepare_phase_block_length": 100,
  • "reward_phase_block_length": 2000,
  • "reward_slots": 4000,
  • "rejection_fraction": 25,
  • "total_liquid_supply_ustx": 1353883724746042,
  • "current_cycle": {
    },
  • "next_cycle": {
    },
  • "min_amount_ustx": 90000000000,
  • "prepare_cycle_length": 100,
  • "reward_cycle_id": 50,
  • "reward_cycle_length": 2100,
  • "rejection_votes_left_required": 338470931186500,
  • "next_reward_cycle_in": 327
}

Microblocks

Read-only endpoints to obtain microblocks details

Stacks Documentation - Microblocks

Get recent microblocks

Retrieves a list of microblocks.

If you need to actively monitor new microblocks, we highly recommend subscribing to WebSockets or Socket.io for real-time updates.

query Parameters
limit
integer <= 200
Default: 20
Example: limit=100

Max number of microblocks to fetch

offset
integer
Example: offset=42000

Index of the first microblock to fetch

Responses

Response samples

Content type
application/json
{
  • "limit": 30,
  • "offset": 0,
  • "total": 0,
  • "results": [
    ]
}

Get microblock

Retrieves a specific microblock by hash

path Parameters
hash
required
string
Example: 0x3bfcdf84b3012adb544cf0f6df4835f93418c2269a3881885e27b3d58eb82d47

Hash of the microblock

Responses

Response samples

Content type
application/json
{
  • "canonical": true,
  • "microblock_canonical": true,
  • "microblock_hash": "string",
  • "microblock_sequence": 0,
  • "microblock_parent_hash": "string",
  • "block_height": 0,
  • "parent_block_height": 0,
  • "parent_block_hash": "string",
  • "parent_burn_block_hash": "string",
  • "parent_burn_block_time": 0,
  • "parent_burn_block_time_iso": "string",
  • "parent_burn_block_height": 0,
  • "block_hash": "string",
  • "txs": [
    ]
}

Get the list of current transactions that belong to unanchored microblocks

Retrieves transactions that have been streamed in microblocks but not yet accepted or rejected in an anchor block

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "results": [
    ]
}

Names

Read-only endpoints realted to the Blockchain Naming System on Stacks

Stacks Documentation - Blockchain Naming System

Get Namespace Price

Retrieves the price of a namespace. The amount given will be in the smallest possible units of the currency.

path Parameters
tld
required
string
Example: id

the namespace to fetch price for

Responses

Response samples

Content type
application/json
{
  • "units": "string",
  • "amount": "string"
}

Get Name Price

Retrieves the price of a name. The amount given will be in the smallest possible units of the currency.

path Parameters
name
required
string
Example: muneeb.id

the name to query price information for

Responses

Response samples

Content type
application/json
{
  • "units": "string",
  • "amount": "string"
}

Get All Namespaces

Retrieves a list of all namespaces known to the node.

Responses

Response samples

Content type
application/json
{
  • "namespaces": [
    ]
}

Get Namespace Names

Retrieves a list of names within a given namespace.

path Parameters
tld
required
string
Example: id

the namespace to fetch names from.

query Parameters
page
integer
Example: page=22

namespace values are defaulted to page 1 with 100 results. You can query specific page results by using the 'page' query parameter.

Responses

Response samples

Content type
application/json
[
  • "aldenquimby.id",
  • "aldeoryn.id",
  • "alderete.id",
  • "aldert.id",
  • "aldi.id",
  • "aldighieri.id"
]

Get All Names

Retrieves a list of all names known to the node.

query Parameters
page
integer
Example: page=22

names are defaulted to page 1 with 100 results. You can query specific page results by using the 'page' query parameter.

Responses

Response samples

Content type
application/json
[
  • "aldenquimby.id",
  • "aldeoryn.id",
  • "alderete.id",
  • "aldert.id",
  • "aldi.id",
  • "aldighieri.id"
]

Get Name Details

Retrieves details of a given name including the address, status and last transaction id - last_txid.

path Parameters
name
required
string
Example: muneeb.id

fully-qualified name

Responses

Response samples

Content type
application/json
{
  • "address": "1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs",
  • "blockchain": "bitcoin",
  • "expire_block": 599266,
  • "grace_period": false,
  • "last_txid": "1edfa419f7b83f33e00830bc9409210da6c6d1db60f99eda10c835aa339cad6b",
  • "renewal_deadline": 604266,
  • "resolver": null,
  • "status": "registered",
  • "zonefile": "$ORIGIN muneeb.id\n$TTL 3600\n_http._tcp IN URI 10 1 \"https://gaia.blockstack.org/hub/1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs/0/profile.json\"\n",
  • "zonefile_hash": "37aecf837c6ae9bdc9dbd98a268f263dacd00361"
}

Get Name Subdomains

Retrieves the list of subdomains for a specific name

path Parameters
name
required
string
Example: id.blockstack

fully-qualified name

Responses

Response samples

Content type
application/json
[
  • "address_test.id.blockstack",
  • "previous_subdomain.id.blockstack",
  • "subdomain.id.blockstack",
  • "zonefile_test.id.blockstack",
  • "zone_test.id.blockstack"
]

Get Zone File

Retrieves a user’s raw zone file. This only works for RFC-compliant zone files. This method returns an error for names that have non-standard zone files.

path Parameters
name
required
string
Example: bar.test

fully-qualified name

Responses

Response samples

Content type
application/json
{
  • "zonefile": "$ORIGIN bar.test\n$TTL 3600\n_https._tcp URI 10 1 \"https://gaia.blockstack.org/hub/17Zijx61Sp7SbVfRTdETo7PhizJHYEUxbY/profile.json\"\n"
}

Get Historical Zone File

Retrieves the historical zonefile specified by the username and zone hash.

path Parameters
name
required
string
Example: muneeb.id

fully-qualified name

zoneFileHash
required
string
Example: b100a68235244b012854a95f9114695679002af9

zone file hash

Responses

Response samples

Content type
application/json
{
  • "title": "BnsFetchHistoricalZoneFileResponse",
  • "description": "Fetches the historical zonefile specified by the username and zone hash.",
  • "anyOf": [
    ]
}

Get Names Owned by Address

Retrieves a list of names owned by the address provided.

path Parameters
blockchain
required
string
Example: bitcoin

the layer-1 blockchain for the address

address
required
string
Example: 1QJQxDas5JhdiXhEbNS14iNjr8auFT96GP

the address to lookup

Responses

Response samples

Content type
application/json
{
  • "names": [
    ]
}

Non-Fungible Tokens

Read-only endpoints to obtain non-fungible token details

Stacks Documentation - Tokens

Non-Fungible Token holdings

Retrieves the list of Non-Fungible Tokens owned by the given principal (STX address or Smart Contract ID). Results can be filtered by one or more asset identifiers and can include metadata about the transaction that made the principal own each token.

More information on Non-Fungible Tokens on the Stacks blockchain can be found here.

query Parameters
principal
required
string
Example: principal=SPNWZ5V2TPWGQGVDR6T7B6RQ4XMGZ4PXTEE0VQ0S.marketplace-v3

token owner's STX address or Smart Contract ID

asset_identifiers
Array of strings
Example: asset_identifiers=SPQZF23W7SEYBFG5JQ496NMY0G7379SRYEDREMSV.Candy::candy

identifiers of the token asset classes to filter for

limit
integer
Default: 50

max number of tokens to fetch

offset
integer
Default: 0
Example: offset=42000

index of first tokens to fetch

unanchored
boolean
Default: false
Example: unanchored=true

whether or not to include tokens from unconfirmed transactions

tx_metadata
boolean
Default: false

whether or not to include the complete transaction metadata instead of just tx_id. Enabling this option can affect performance and response times.

Responses

Response samples

Content type
application/json
Example
{
  • "limit": 50,
  • "offset": 0,
  • "total": 3,
  • "results": [
    ]
}

Non-Fungible Token history

Retrieves all events relevant to a Non-Fungible Token. Useful to determine the ownership history of a particular asset.

More information on Non-Fungible Tokens on the Stacks blockchain can be found here.

query Parameters
asset_identifier
required
string
Example: asset_identifier=SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild::The-Explorer-Guild

token asset class identifier

value
required
string
Example: value=0x0100000000000000000000000000000803

hex representation of the token's unique value

limit
integer
Default: 50

max number of events to fetch

offset
integer
Default: 0
Example: offset=42000

index of first event to fetch

unanchored
boolean
Default: false
Example: unanchored=true

whether or not to include events from unconfirmed transactions

tx_metadata
boolean
Default: false

whether or not to include the complete transaction metadata instead of just tx_id. Enabling this option can affect performance and response times.

Responses

Response samples

Content type
application/json
Example
{
  • "limit": 50,
  • "offset": 0,
  • "total": 2,
  • "results": [
    ]
}

Non-Fungible Token mints

Retrieves all mint events for a Non-Fungible Token asset class. Useful to determine which NFTs of a particular collection have been claimed.

More information on Non-Fungible Tokens on the Stacks blockchain can be found here.

query Parameters
asset_identifier
required
string
Example: asset_identifier=SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild::The-Explorer-Guild

token asset class identifier

limit
integer
Default: 50

max number of events to fetch

offset
integer
Default: 0
Example: offset=42000

index of first event to fetch

unanchored
boolean
Default: false
Example: unanchored=true

whether or not to include events from unconfirmed transactions

tx_metadata
boolean
Default: false

whether or not to include the complete transaction metadata instead of just tx_id. Enabling this option can affect performance and response times.

Responses

Response samples

Content type
application/json
Example
{
  • "limit": 5,
  • "offset": 0,
  • "total": 2503,
  • "results": [
    ]
}

Rosetta

Endpoints to support the Rosetta API open blockchain standard

Hiro Documentation - Rosetta Support

Get List of Available Networks

Retrieves a list of NetworkIdentifiers that the Rosetta server supports.

Responses

Response samples

Content type
application/json
{
  • "network_identifiers": [
    ]
}

Get Network Options

Retrieves the version information and allowed network-specific types for a NetworkIdentifier. Any NetworkIdentifier returned by /network/list should be accessible here. Because options are retrievable in the context of a NetworkIdentifier, it is possible to define unique options for each network.

Request Body schema: application/json
required
object (NetworkIdentifier)

The network_identifier specifies which network a particular object is associated with.

metadata
object

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "version": {
    },
  • "allow": {
    }
}

Get Network Status

Retrieves the current status of the network requested. Any NetworkIdentifier returned by /network/list should be accessible here.

Request Body schema: application/json
required
object (NetworkIdentifier)

The network_identifier specifies which network a particular object is associated with.

metadata
object

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "current_block_identifier": {
    },
  • "current_block_timestamp": 0,
  • "genesis_block_identifier": {
    },
  • "oldest_block_identifier": {
    },
  • "sync_status": {
    },
  • "peers": [
    ],
  • "current_burn_block_height": 0
}

Get an Account Balance

An AccountBalanceRequest is utilized to make a balance request on the /account/balance endpoint. If the block_identifier is populated, a historical balance query should be performed.

Request Body schema: application/json
required
object (NetworkIdentifier)

The network_identifier specifies which network a particular object is associated with.

required
object (RosettaAccount)

The account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated).

RosettaBlockIdentifierHash (object) or RosettaBlockIdentifierHeight (object) or RosettaPartialBlockIdentifier (object) (RosettaPartialBlockIdentifier)

When fetching data by BlockIdentifier, it may be possible to only specify the index or hash. If neither property is specified, it is assumed that the client is making a request at the current block.

Responses

Request samples

Content type
application/json
{
  • "network_identifier": {
    },
  • "account_identifier": {
    }
}

Response samples

Content type
application/json
{
  • "block_identifier": {
    },
  • "balances": [
    ],
  • "coins": [
    ],
  • "metadata": {
    }
}

Get a Block

Retrieves the Block information for a given block identifier including a list of all transactions in the block.

Request Body schema: application/json
required
object (NetworkIdentifier)

The network_identifier specifies which network a particular object is associated with.

required
RosettaBlockIdentifierHash (object) or RosettaBlockIdentifierHeight (object) or RosettaPartialBlockIdentifier (object) (RosettaPartialBlockIdentifier)

When fetching data by BlockIdentifier, it may be possible to only specify the index or hash. If neither property is specified, it is assumed that the client is making a request at the current block.

Responses

Request samples

Content type
application/json
{
  • "network_identifier": {
    },
  • "block_identifier": {
    }
}

Response samples

Content type
application/json
{
  • "block": {
    },
  • "other_transactions": [
    ]
}

Get a Block Transaction

Retrieves a Transaction included in a block that is not returned in a BlockResponse.

Request Body schema: application/json
required
object (NetworkIdentifier)

The network_identifier specifies which network a particular object is associated with.

required
RosettaBlockIdentifierHash (object) or RosettaBlockIdentifierHeight (object) or RosettaPartialBlockIdentifier (object) (RosettaPartialBlockIdentifier)

When fetching data by BlockIdentifier, it may be possible to only specify the index or hash. If neither property is specified, it is assumed that the client is making a request at the current block.

required
object (TransactionIdentifier)

The transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.

Responses

Request samples

Content type
application/json
{
  • "network_identifier": {
    },
  • "block_identifier": {
    },
  • "transaction_identifier": {
    }
}

Response samples

Content type
application/json
{
  • "transaction": {
    }
}

Get All Mempool Transactions

Retrieves a list of transactions currently in the mempool for a given network.

Request Body schema: application/json
required
object (NetworkIdentifier)

The network_identifier specifies which network a particular object is associated with.

metadata
object

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "transaction_identifiers": [
    ],
  • "metadata": { }
}

Get a Mempool Transaction

Retrieves transaction details from the mempool for a given transaction id from a given network.

Request Body schema: application/json
required
object (NetworkIdentifier)

The network_identifier specifies which network a particular object is associated with.

required
object (TransactionIdentifier)

The transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.

Responses

Request samples

Content type
application/json
{
  • "network_identifier": {
    },
  • "transaction_identifier": {
    }
}

Response samples

Content type
application/json
{
  • "transaction": {
    },
  • "metadata": { }
}

Derive an AccountIdentifier from a PublicKey

Retrieves the Account Identifier information based on a Public Key for a given network

Request Body schema: application/json
required
object (NetworkIdentifier)

The network_identifier specifies which network a particular object is associated with.

required
object (RosettaPublicKey)

PublicKey contains a public key byte array for a particular CurveType encoded in hex. Note that there is no PrivateKey struct as this is NEVER the concern of an implementation.

metadata
object

Responses

Request samples

Content type
application/json
{
  • "network_identifier": {
    },
  • "public_key": {
    },
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "address": "string",
  • "account_identifier": {
    },
  • "metadata": { }
}

Get the Hash of a Signed Transaction

Retrieves the network-specific transaction hash for a signed transaction.

Request Body schema: application/json
required
object (NetworkIdentifier)

The network_identifier specifies which network a particular object is associated with.

signed_transaction
required
string

Signed transaction

Responses

Request samples

Content type
application/json
{
  • "network_identifier": {
    },
  • "signed_transaction": "0x80800000000400539886f96611ba3ba6cef9618f8c78118b37c5be000000000000000000000000000000b400017a33a91515ef48608a99c6adecd2eb258e11534a1acf66348f5678c8e2c8f83d243555ed67a0019d3500df98563ca31321c1a675b43ef79f146e322fe08df75103020000000000051a1ae3f911d8f1d46d7416bfbe4b593fd41eac19cb000000000007a12000000000000000000000000000000000000000000000000000000000000000000000"
}

Response samples

Content type
application/json
{
  • "transaction_identifier": {
    },
  • "metadata": { }
}

Get Metadata for Transaction Construction

To Do

Request Body schema: application/json
required
object (NetworkIdentifier)

The network_identifier specifies which network a particular object is associated with.

required
object (RosettaOptions)

The options that will be sent directly to /construction/metadata by the caller.

Array of objects (RosettaPublicKey)

Responses

Request samples

Content type
application/json
{
  • "network_identifier": {
    },
  • "options": {
    },
  • "public_keys": [
    ]
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "suggested_fee": [
    ]
}

Parse a Transaction

TODO

Request Body schema: application/json
required
object (NetworkIdentifier)

The network_identifier specifies which network a particular object is associated with.

signed
required
boolean

Signed is a boolean indicating whether the transaction is signed.

transaction
required
string

This must be either the unsigned transaction blob returned by /construction/payloads or the signed transaction blob returned by /construction/combine.

Responses

Request samples

Content type
application/json
{
  • "network_identifier": {
    },
  • "signed": true,
  • "transaction": "string"
}

Response samples

Content type
application/json
{
  • "operations": [
    ],
  • "signers": [
    ],
  • "account_identifier_signers": [
    ],
  • "metadata": { }
}

Create a Request to Fetch Metadata

TODO

Request Body schema: application/json
required
object (NetworkIdentifier)

The network_identifier specifies which network a particular object is associated with.

required
Array of objects (RosettaOperation)
metadata
object
Array of objects (RosettaMaxFeeAmount)
suggested_fee_multiplier
integer

The caller can also provide a suggested fee multiplier to indicate that the suggested fee should be scaled. This may be used to set higher fees for urgent transactions or to pay lower fees when there is less urgency. It is assumed that providing a very low multiplier (like 0.0001) will never lead to a transaction being created with a fee less than the minimum network fee (if applicable). In the case that the caller provides both a max fee and a suggested fee multiplier, the max fee will set an upper bound on the suggested fee (regardless of the multiplier provided).

Responses

Request samples

Content type
application/json
{
  • "network_identifier": {
    },
  • "operations": [
    ],
  • "metadata": { },
  • "max_fee": [
    ],
  • "suggested_fee_multiplier": 0
}

Response samples

Content type
application/json
{
  • "options": {
    },
  • "required_public_keys": [
    ]
}

Submit a Signed Transaction

Submit a pre-signed transaction to the node. The examples below are illustrative only. You'll need to use your wallet to generate actual values to use them in the request payload.

Request Body schema: application/json
required
object (NetworkIdentifier)

The network_identifier specifies which network a particular object is associated with.

signed_transaction
required
string

Signed transaction

Responses

Request samples

Content type
application/json
{
  • "network_identifier": {
    },
  • "signed_transaction": "0x80800000000400539886f96611ba3ba6cef9618f8c78118b37c5be000000000000000000000000000000b400017a33a91515ef48608a99c6adecd2eb258e11534a1acf66348f5678c8e2c8f83d243555ed67a0019d3500df98563ca31321c1a675b43ef79f146e322fe08df75103020000000000051a1ae3f911d8f1d46d7416bfbe4b593fd41eac19cb000000000007a12000000000000000000000000000000000000000000000000000000000000000000000"
}

Response samples

Content type
application/json
{
  • "transaction_identifier": {
    },
  • "metadata": { }
}

Generate an Unsigned Transaction and Signing Payloads

Generate an unsigned transaction from operations and metadata. The examples below are illustrative only. You'll need to use your wallet to generate actual values to use them in the request payload.

Request Body schema: application/json
required
object (NetworkIdentifier)

The network_identifier specifies which network a particular object is associated with.

required
Array of objects (RosettaOperation)
Array of objects (RosettaPublicKey)
object

Responses

Request samples

Content type
application/json
{
  • "network_identifier": {
    },
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "unsigned_transaction": "string",
  • "payloads": [
    ]
}

Create Network Transaction from Signatures

Take unsigned transaction and signature, combine both and return signed transaction. The examples below are illustrative only. You'll need to use your wallet to generate actual values to use them in the request payload.

Request Body schema: application/json
required
object (NetworkIdentifier)

The network_identifier specifies which network a particular object is associated with.

unsigned_transaction
required
string
required
Array of objects (RosettaSignature)

Responses

Request samples

Content type
application/json
{
  • "network_identifier": {
    },
  • "unsigned_transaction": "00000000010400539886f96611ba3ba6cef9618f8c78118b37c5be0000000000000000000000000000006400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003020000000000051ab71a091b4b8b7661a661c620966ab6573bc2dcd3000000000007a12074657374207472616e73616374696f6e000000000000000000000000000000000000",
  • "signatures": [
    ]
}

Response samples

Content type
application/json
{
  • "signed_transaction": "string"
}

Search

Read-only endpoints to search for accounts, blocks, smart contracts, and transactions

Search

Search blocks, transactions, contracts, or accounts by hash/ID

path Parameters
id
required
string
Example: 0xcf8b233f19f6c07d2dc1963302d2436efd36e9afac127bf6582824a13961c06d

The hex hash string for a block or transaction, account address, or contract address

query Parameters
include_metadata
boolean

This includes the detailed data for purticular hash in the response

Responses

Response samples

Content type
application/json
{
  • "found": true,
  • "result": {
    }
}

Smart Contracts

Read-only endpoints to obtain Clarity smart contract details

Stacks Documentation - Clarity Smart Contracts

Get smart contracts status

Retrieves the deployment status of multiple smart contracts.

query Parameters
contract_id
required
Array of strings
Example: contract_id=SPQZF23W7SEYBFG5JQ496NMY0G7379SRYEDREMSV.Candy

contract ids to fetch status for

Responses

Response samples

Content type
application/json
{
  • "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-bridged-v1-1": {
    },
  • "SP1JTCR202ECC6333N7ZXD7MK7E3ZTEEE1MJ73C60.name-registrar": {
    },
  • "SP4SZE494VC2YC5JYG7AYFQ44F5Q4PYV7DVMDPBG.stacking-dao-core-v1": {
    },
  • "SP4SZE494VC2YC5JYG7AYFQ44F5Q4PYV7DVMDPBG.stacking-dao-core": {
    }
}

Get contract info

Retrieves details of a contract with a given contract_id

path Parameters
contract_id
required
string
Example: SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C.satoshibles

Contract identifier formatted as <contract_address>.<contract_name>

query Parameters
unanchored
boolean
Default: false
Example: unanchored=true

Include transaction data from unanchored (i.e. unconfirmed) microblocks

Responses

Response samples

Content type
application/json
{
  • "tx_id": "0xb8b822f30a063fda8f9d44a23530a562a1ed93867d5977fbb12b1c284736edbb",
  • "canonical": true,
  • "contract_id": "SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.btc-ft-swap",
  • "block_height": 23131,
  • "source_code": "(use-trait fungible-token 'SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.sip-010-trait-ft-standard.sip-010-trait) (define-constant expiry u100) (define-map swaps uint {sats: uint, btc-receiver: (buff 40), amount: uint, ft-receiver: (optional principal), ft-sender: principal, when: uint, done: uint, ft: principal}) (define-data-var next-id uint u0) (define-private (find-out (entry {scriptPubKey: (buff 128), value: (buff 8)}) (result {pubscriptkey: (buff 40), out: (optional {scriptPubKey: (buff 128), value: uint})})) (if (is-eq (get scriptPubKey entry) (get pubscriptkey result)) (merge result {out: (some {scriptPubKey: (get scriptPubKey entry), value: (get uint32 (unwrap-panic (contract-call? 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.clarity-bitcoin-lib-v1 read-uint32 {txbuff: (get value entry), index: u0})))})}) result)) (define-public (get-out-value (tx { version: (buff 4), ins: (list 8 {outpoint: {hash: (buff 32), index: (buff 4)}, scriptSig: (buff 256), sequence: (buff 4)}), outs: (list 8 {value: (buff 8), scriptPubKey: (buff 128)}), locktime: (buff 4)}) (pubscriptkey (buff 40))) (ok (fold find-out (get outs tx) {pubscriptkey: pubscriptkey, out: none}))) ;; create a swap between btc and fungible token (define-public (create-swap (sats uint) (btc-receiver (buff 40)) (amount uint) (ft-receiver (optional principal)) (ft <fungible-token>)) (let ((id (var-get next-id))) (asserts! (map-insert swaps id {sats: sats, btc-receiver: btc-receiver, amount: amount, ft-receiver: ft-receiver, ft-sender: tx-sender, when: block-height, done: u0, ft: (contract-of ft)}) ERR_INVALID_ID) (var-set next-id (+ id u1)) (match (contract-call? ft transfer amount tx-sender (as-contract tx-sender) (some 0x636174616d6172616e2073776170)) success (ok id) error (err (* error u1000))))) (define-public (set-ft-receiver (id uint)) (let ((swap (unwrap! (map-get? swaps id) ERR_INVALID_ID))) (if (is-none (get ft-receiver swap)) (begin (asserts! (map-set swaps id (merge swap {ft-receiver: (some tx-sender)})) ERR_NATIVE_FAILURE) (ok true)) ERR_ALREADY_DONE))) ;; any user can cancle the swap after the expiry period (define-public (cancel (id uint) (ft <fungible-token>)) (let ((swap (unwrap! (map-get? swaps id) ERR_INVALID_ID))) (asserts! (is-eq (contract-of ft) (get ft swap)) ERR_INVALID_FUNGIBLE_TOKEN) (asserts! (< (+ (get when swap) expiry) block-height) ERR_TOO_EARLY) (asserts! (is-eq (get done swap) u0) ERR_ALREADY_DONE) (asserts! (map-set swaps id (merge swap {done: u1})) ERR_NATIVE_FAILURE) (as-contract (contract-call? ft transfer (get amount swap) tx-sender (get ft-sender swap) (some 0x72657665727420636174616d6172616e2073776170))))) ;; any user can submit a tx that contains the swap (define-public (submit-swap (id uint) (block { version: (buff 4), parent: (buff 32), merkle-root: (buff 32), timestamp: (buff 4), nbits: (buff 4), nonce: (buff 4), height: uint }) (tx {version: (buff 4), ins: (list 8 {outpoint: {hash: (buff 32), index: (buff 4)}, scriptSig: (buff 256), sequence: (buff 4)}), outs: (list 8 {value: (buff 8), scriptPubKey: (buff 128)}), locktime: (buff 4)}) (proof { tx-index: uint, hashes: (list 12 (buff 32)), tree-depth: uint }) (ft <fungible-token>)) (let ((swap (unwrap! (map-get? swaps id) ERR_INVALID_ID)) (tx-buff (contract-call? 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.clarity-bitcoin-lib-v1 concat-tx tx))) (match (contract-call? 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.clarity-bitcoin-lib-v1 was-tx-mined block tx-buff proof) result (begin (asserts! result ERR_VERIFICATION_FAILED) (asserts! (is-eq (get done swap) u0) ERR_ALREADY_DONE) (match (get out (unwrap! (get-out-value tx (get btc-receiver swap)) ERR_NATIVE_FAILURE)) out (if (>= (get value out) (get sats swap)) (begin (asserts! (is-eq (contract-of ft) (get ft swap)) ERR_INVALID_FUNGIBLE_TOKEN) (asserts! (map-set swaps id (merge swap {done: u1})) ERR_NATIVE_FAILURE) (as-contract (contract-call? ft transfer (get amount swap) tx-sender (unwrap! (get ft-receiver swap) ERR_NO_FT_RECEIVER) (some 0x636174616d6172616e2073776170)))) ERR_TX_VALUE_TOO_SMALL) ERR_TX_NOT_FOR_RECEIVER)) error (err (* error u1000))))) (define-constant ERR_VERIFICATION_FAILED (err u1)) (define-constant ERR_FAILED_TO_PARSE_TX (err u2)) (define-constant ERR_INVALID_ID (err u3)) (define-constant ERR_TOO_EARLY (err u4)) (define-constant ERR_TX_VALUE_TOO_SMALL (err u5)) (define-constant ERR_TX_NOT_FOR_RECEIVER (err u6)) (define-constant ERR_ALREADY_DONE (err u7)) (define-constant ERR_INVALID_FUNGIBLE_TOKEN (err u8)) (define-constant ERR_NO_FT_RECEIVER (err u9)) (define-constant ERR_NATIVE_FAILURE (err u99)) ",
  • "abi": "{\"maps\":[{\"key\":\"uint128\",\"name\":\"swaps\",\"value\":{\"tuple\":[{\"name\":\"amount\",\"type\":\"uint128\"},{\"name\":\"btc-receiver\",\"type\":{\"buffer\":{\"length\":40}}},{\"name\":\"done\",\"type\":\"uint128\"},{\"name\":\"ft\",\"type\":\"principal\"},{\"name\":\"ft-receiver\",\"type\":{\"optional\":\"principal\"}},{\"name\":\"ft-sender\",\"type\":\"principal\"},{\"name\":\"sats\",\"type\":\"uint128\"},{\"name\":\"when\",\"type\":\"uint128\"}]}}],\"functions\":[{\"args\":[{\"name\":\"entry\",\"type\":{\"tuple\":[{\"name\":\"scriptPubKey\",\"type\":{\"buffer\":{\"length\":128}}},{\"name\":\"value\",\"type\":{\"buffer\":{\"length\":8}}}]}},{\"name\":\"result\",\"type\":{\"tuple\":[{\"name\":\"out\",\"type\":{\"optional\":{\"tuple\":[{\"name\":\"scriptPubKey\",\"type\":{\"buffer\":{\"length\":128}}},{\"name\":\"value\",\"type\":\"uint128\"}]}}},{\"name\":\"pubscriptkey\",\"type\":{\"buffer\":{\"length\":40}}}]}}],\"name\":\"find-out\",\"access\":\"private\",\"outputs\":{\"type\":{\"tuple\":[{\"name\":\"out\",\"type\":{\"optional\":{\"tuple\":[{\"name\":\"scriptPubKey\",\"type\":{\"buffer\":{\"length\":128}}},{\"name\":\"value\",\"type\":\"uint128\"}]}}},{\"name\":\"pubscriptkey\",\"type\":{\"buffer\":{\"length\":40}}}]}}},{\"args\":[{\"name\":\"id\",\"type\":\"uint128\"},{\"name\":\"ft\",\"type\":\"trait_reference\"}],\"name\":\"cancel\",\"access\":\"public\",\"outputs\":{\"type\":{\"response\":{\"ok\":\"bool\",\"error\":\"uint128\"}}}},{\"args\":[{\"name\":\"sats\",\"type\":\"uint128\"},{\"name\":\"btc-receiver\",\"type\":{\"buffer\":{\"length\":40}}},{\"name\":\"amount\",\"type\":\"uint128\"},{\"name\":\"ft-receiver\",\"type\":{\"optional\":\"principal\"}},{\"name\":\"ft\",\"type\":\"trait_reference\"}],\"name\":\"create-swap\",\"access\":\"public\",\"outputs\":{\"type\":{\"response\":{\"ok\":\"uint128\",\"error\":\"uint128\"}}}},{\"args\":[{\"name\":\"tx\",\"type\":{\"tuple\":[{\"name\":\"ins\",\"type\":{\"list\":{\"type\":{\"tuple\":[{\"name\":\"outpoint\",\"type\":{\"tuple\":[{\"name\":\"hash\",\"type\":{\"buffer\":{\"length\":32}}},{\"name\":\"index\",\"type\":{\"buffer\":{\"length\":4}}}]}},{\"name\":\"scriptSig\",\"type\":{\"buffer\":{\"length\":256}}},{\"name\":\"sequence\",\"type\":{\"buffer\":{\"length\":4}}}]},\"length\":8}}},{\"name\":\"locktime\",\"type\":{\"buffer\":{\"length\":4}}},{\"name\":\"outs\",\"type\":{\"list\":{\"type\":{\"tuple\":[{\"name\":\"scriptPubKey\",\"type\":{\"buffer\":{\"length\":128}}},{\"name\":\"value\",\"type\":{\"buffer\":{\"length\":8}}}]},\"length\":8}}},{\"name\":\"version\",\"type\":{\"buffer\":{\"length\":4}}}]}},{\"name\":\"pubscriptkey\",\"type\":{\"buffer\":{\"length\":40}}}],\"name\":\"get-out-value\",\"access\":\"public\",\"outputs\":{\"type\":{\"response\":{\"ok\":{\"tuple\":[{\"name\":\"out\",\"type\":{\"optional\":{\"tuple\":[{\"name\":\"scriptPubKey\",\"type\":{\"buffer\":{\"length\":128}}},{\"name\":\"value\",\"type\":\"uint128\"}]}}},{\"name\":\"pubscriptkey\",\"type\":{\"buffer\":{\"length\":40}}}]},\"error\":\"none\"}}}},{\"args\":[{\"name\":\"id\",\"type\":\"uint128\"}],\"name\":\"set-ft-receiver\",\"access\":\"public\",\"outputs\":{\"type\":{\"response\":{\"ok\":\"bool\",\"error\":\"uint128\"}}}},{\"args\":[{\"name\":\"id\",\"type\":\"uint128\"},{\"name\":\"block\",\"type\":{\"tuple\":[{\"name\":\"height\",\"type\":\"uint128\"},{\"name\":\"merkle-root\",\"type\":{\"buffer\":{\"length\":32}}},{\"name\":\"nbits\",\"type\":{\"buffer\":{\"length\":4}}},{\"name\":\"nonce\",\"type\":{\"buffer\":{\"length\":4}}},{\"name\":\"parent\",\"type\":{\"buffer\":{\"length\":32}}},{\"name\":\"timestamp\",\"type\":{\"buffer\":{\"length\":4}}},{\"name\":\"version\",\"type\":{\"buffer\":{\"length\":4}}}]}},{\"name\":\"tx\",\"type\":{\"tuple\":[{\"name\":\"ins\",\"type\":{\"list\":{\"type\":{\"tuple\":[{\"name\":\"outpoint\",\"type\":{\"tuple\":[{\"name\":\"hash\",\"type\":{\"buffer\":{\"length\":32}}},{\"name\":\"index\",\"type\":{\"buffer\":{\"length\":4}}}]}},{\"name\":\"scriptSig\",\"type\":{\"buffer\":{\"length\":256}}},{\"name\":\"sequence\",\"type\":{\"buffer\":{\"length\":4}}}]},\"length\":8}}},{\"name\":\"locktime\",\"type\":{\"buffer\":{\"length\":4}}},{\"name\":\"outs\",\"type\":{\"list\":{\"type\":{\"tuple\":[{\"name\":\"scriptPubKey\",\"type\":{\"buffer\":{\"length\":128}}},{\"name\":\"value\",\"type\":{\"buffer\":{\"length\":8}}}]},\"length\":8}}},{\"name\":\"version\",\"type\":{\"buffer\":{\"length\":4}}}]}},{\"name\":\"proof\",\"type\":{\"tuple\":[{\"name\":\"hashes\",\"type\":{\"list\":{\"type\":{\"buffer\":{\"length\":32}},\"length\":12}}},{\"name\":\"tree-depth\",\"type\":\"uint128\"},{\"name\":\"tx-index\",\"type\":\"uint128\"}]}},{\"name\":\"ft\",\"type\":\"trait_reference\"}],\"name\":\"submit-swap\",\"access\":\"public\",\"outputs\":{\"type\":{\"response\":{\"ok\":\"bool\",\"error\":\"uint128\"}}}}],\"variables\":[{\"name\":\"ERR_ALREADY_DONE\",\"type\":{\"response\":{\"ok\":\"none\",\"error\":\"uint128\"}},\"access\":\"constant\"},{\"name\":\"ERR_FAILED_TO_PARSE_TX\",\"type\":{\"response\":{\"ok\":\"none\",\"error\":\"uint128\"}},\"access\":\"constant\"},{\"name\":\"ERR_INVALID_FUNGIBLE_TOKEN\",\"type\":{\"response\":{\"ok\":\"none\",\"error\":\"uint128\"}},\"access\":\"constant\"},{\"name\":\"ERR_INVALID_ID\",\"type\":{\"response\":{\"ok\":\"none\",\"error\":\"uint128\"}},\"access\":\"constant\"},{\"name\":\"ERR_NATIVE_FAILURE\",\"type\":{\"response\":{\"ok\":\"none\",\"error\":\"uint128\"}},\"access\":\"constant\"},{\"name\":\"ERR_NO_FT_RECEIVER\",\"type\":{\"response\":{\"ok\":\"none\",\"error\":\"uint128\"}},\"access\":\"constant\"},{\"name\":\"ERR_TOO_EARLY\",\"type\":{\"response\":{\"ok\":\"none\",\"error\":\"uint128\"}},\"access\":\"constant\"},{\"name\":\"ERR_TX_NOT_FOR_RECEIVER\",\"type\":{\"response\":{\"ok\":\"none\",\"error\":\"uint128\"}},\"access\":\"constant\"},{\"name\":\"ERR_TX_VALUE_TOO_SMALL\",\"type\":{\"response\":{\"ok\":\"none\",\"error\":\"uint128\"}},\"access\":\"constant\"},{\"name\":\"ERR_VERIFICATION_FAILED\",\"type\":{\"response\":{\"ok\":\"none\",\"error\":\"uint128\"}},\"access\":\"constant\"},{\"name\":\"expiry\",\"type\":\"uint128\",\"access\":\"constant\"},{\"name\":\"next-id\",\"type\":\"uint128\",\"access\":\"variable\"}],\"fungible_tokens\":[],\"non_fungible_tokens\":[]}"
}

Get contracts by trait

Retrieves a list of contracts based on the following traits listed in JSON format - functions, variables, maps, fungible tokens and non-fungible tokens

query Parameters
trait_abi
required
string

JSON abi of the trait.

limit
integer

max number of contracts fetch

offset
integer
Example: offset=42000

index of first contract event to fetch

Responses

Response samples

Content type
application/json
{
  • "offset": 0,
  • "limit": 10,
  • "result": [
    ]
}

Get contract events

Retrieves a list of events that have been triggered by a given contract_id

path Parameters
contract_id
required
string
Example: SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C.satoshibles

Contract identifier formatted as <contract_address>.<contract_name>

query Parameters
limit
integer

max number of contract events to fetch

offset
integer
Example: offset=42000

index of first contract event to fetch

unanchored
boolean
Default: false
Example: unanchored=true

Include transaction data from unanchored (i.e. unconfirmed) microblocks

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "results": [
    ]
}

Get contract interface

Retrieves a contract interface with a given contract_address and contract name

path Parameters
contract_address
required
string
Example: SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C

Stacks address

contract_name
required
string
Example: satoshibles

Contract name

query Parameters
tip
string

The Stacks chain tip to query from

Responses

Response samples

Content type
application/json
{
  • "functions": [
    ],
  • "variables": [
    ],
  • "maps": [
    ],
  • "fungible_tokens": [
    ],
  • "non_fungible_tokens": [
    ]
}

Get specific data-map inside a contract

Attempt to fetch data from a contract data map. The contract is identified with Stacks Address contract_address and Contract Name contract_address 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_address
required
string
Example: SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11

Stacks address

contract_name
required
string
Example: newyorkcitycoin-core-v2

Contract name

map_name
required
string
Example: approved-contracts

Map name

query Parameters
proof
integer

Returns object without the proof field when set to 0

tip
string

The Stacks chain tip to query from

Request Body schema: application/json

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

string

Responses

Request samples

Content type
application/json
"0x0100000000000000000000000000000095"

Response samples

Content type
application/json
{
  • "data": "0x0a0c000000010a6d6f6e737465722d69640100000000000000000000000000000001",
  • "proof": "0x123..."
}

Get contract source

Retrieves 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_address
required
string
Example: SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C

Stacks address

contract_name
required
string
Example: satoshibles

Contract name

query Parameters
proof
integer

Returns object without the proof field if set to 0

tip
string

The Stacks chain tip to query from

Responses

Response samples

Content type
application/json
{
  • "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..."
}

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:

path Parameters
contract_address
required
string
Example: SP187Y7NRSG3T9Z9WTSWNEN3XRV1YSJWS81C7JKV7

Stacks address

contract_name
required
string
Example: imaginary-friends-zebras

Contract name

function_name
required
string
Example: get-token-uri

Function name

query Parameters
tip
string

The Stacks chain tip to query from

Request Body schema: 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.

sender
required
string

The simulated tx-sender

arguments
required
Array of strings

An array of hex serialized Clarity values

Responses

Request samples

Content type
application/json
{
  • "sender": "STM9EQRAB3QAKF8NKTP15WJT7VHH4EWG3DJB4W29",
  • "arguments": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "okay": true,
  • "result": "0x111..."
}

Stacking Rewards

Read-only endpoints to obtain Stacking reward details

Stacks Documentation - Stacking

Get recent reward slot holders

Retrieves a list of the Bitcoin addresses that would validly receive Proof-of-Transfer commitments.

query Parameters
limit
integer <= 250
Default: 96

max number of items to fetch

offset
integer
Example: offset=42000

index of the first items to fetch

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 2,
  • "results": [
    ]
}

Get recent reward slot holder entries for the given address

Retrieves a list of the Bitcoin addresses that would validly receive Proof-of-Transfer commitments for a given reward slot holder recipient address.

path Parameters
address
required
string
Example: 36hQtSEXBMevo5chpxhfAGiCTSC34QKgda

Reward slot holder recipient address. Should either be in the native burnchain's format (e.g. B58 for Bitcoin), or if a STX principal address is provided it will be encoded as into the equivalent burnchain format

query Parameters
limit
integer

max number of items to fetch

offset
integer
Example: offset=42000

index of the first items to fetch

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 2,
  • "results": [
    ]
}

Get recent burnchain reward recipients

Retrieves a list of recent burnchain (e.g. Bitcoin) reward recipients with the associated amounts and block info

query Parameters
limit
integer <= 250
Default: 96

max number of rewards to fetch

offset
integer
Example: offset=42000

index of first rewards to fetch

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "results": [
    ]
}

Get recent burnchain reward for the given recipient

Retrieves a list of recent burnchain (e.g. Bitcoin) rewards for the given recipient with the associated amounts and block info

path Parameters
address
required
string
Example: 36hQtSEXBMevo5chpxhfAGiCTSC34QKgda

Reward recipient address. Should either be in the native burnchain's format (e.g. B58 for Bitcoin), or if a STX principal address is provided it will be encoded as into the equivalent burnchain format

query Parameters
limit
integer

max number of rewards to fetch

offset
integer
Example: offset=42000

index of first rewards to fetch

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "results": [
    ]
}

Get total burnchain rewards for the given recipient

Retrieves the total burnchain (e.g. Bitcoin) rewards for a given recipient address

path Parameters
address
required
string
Example: 36hQtSEXBMevo5chpxhfAGiCTSC34QKgda

Reward recipient address. Should either be in the native burnchain's format (e.g. B58 for Bitcoin), or if a STX principal address is provided it will be encoded as into the equivalent burnchain format

Responses

Response samples

Content type
application/json
{
  • "reward_recipient": "1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6",
  • "reward_amount": "18000"
}

Transactions

Endpoints to obtain transaction details and to broadcast transactions to the network

Hiro Documentation - Transactions

Get recent transactions

Retrieves all recently mined transactions

If using TypeScript, import typings for this response from our types package:

import type { TransactionResults } from '@stacks/stacks-blockchain-api-types';

query Parameters
limit
integer <= 200
Default: 96
Example: limit=100

max number of transactions to fetch

offset
integer
Example: offset=42000

index of first transaction to fetch

type
Array of strings
Items Enum: "coinbase" "token_transfer" "smart_contract" "contract_call" "poison_microblock" "tenure_change"
Example: type=coinbase

Filter by transaction type

from_address
string

Option to filter results by sender address

to_address
string

Option to filter results by recipient address

sort_by
string
Default: "block_height"
Enum: "block_height" "burn_block_time" "fee"
Example: sort_by=burn_block_time

Option to sort results by block height, timestamp, or fee

start_time
integer
Example: start_time=1704067200

Filter by transactions after this timestamp (unix timestamp in seconds)

end_time
integer
Example: end_time=1706745599

Filter by transactions before this timestamp (unix timestamp in seconds)

contract_id
string
Example: contract_id=SP000000000000000000002Q6VF78.pox-4

Filter by contract call transactions involving this contract ID

function_name
string
Example: function_name=delegate-stx

Filter by contract call transactions involving this function name

order
string
Default: "desc"
Enum: "asc" "desc"
Example: order=desc

Option to sort results in ascending or descending order

unanchored
boolean
Default: false
Example: unanchored=true

Include transaction data from unanchored (i.e. unconfirmed) microblocks

Responses

Response samples

Content type
application/json
{
  • "limit": 10,
  • "offset": 0,
  • "total": 101922,
  • "results": [
    ]
}

Get mempool transactions

Retrieves all transactions that have been recently broadcast to the mempool. These are pending transactions awaiting confirmation.

If you need to monitor new transactions, we highly recommend subscribing to WebSockets or Socket.io for real-time updates.

query Parameters
sender_address
string
Example: sender_address=SP1GPBP8NBRXDRJBFQBV7KMAZX1Z7W2RFWJEH0V10

Filter to only return transactions with this sender address.

recipient_address
string

Filter to only return transactions with this recipient address (only applicable for STX transfer tx types).

address
string

Filter to only return transactions with this address as the sender or recipient (recipient only applicable for STX transfer tx types).

order_by
string
Enum: "age" "size" "fee"
Example: order_by=fee

Option to sort results by transaction age, size, or fee rate.

order
string
Enum: "asc" "desc"
Example: order=asc

Option to sort results in ascending or descending order.

limit
integer <= 50
Default: 20
Example: limit=20

max number of mempool transactions to fetch

offset
integer
Example: offset=42000

index of first mempool transaction to fetch

unanchored
boolean
Default: false
Example: unanchored=true

Include transaction data from unanchored (i.e. unconfirmed) microblocks

Responses

Response samples

Content type
application/json
{
  • "limit": 96,
  • "offset": 0,
  • "total": 5,
  • "results": [
    ]
}

Get dropped mempool transactions

Retrieves all recently-broadcast transactions that have been dropped from the mempool.

Transactions are dropped from the mempool if:

  • they were stale and awaiting garbage collection or,
  • were expensive, or
  • were replaced with a new fee
query Parameters
limit
integer <= 200
Default: 96

max number of mempool transactions to fetch

offset
integer
Example: offset=42000

index of first mempool transaction to fetch

Responses

Response samples

Content type
application/json
{
  • "limit": 96,
  • "offset": 0,
  • "total": 5,
  • "results": [
    ]
}

Get statistics for mempool transactions

Queries for transactions counts, age (by block height), fees (simple average), and size. All results broken down by transaction type and percentiles (p25, p50, p75, p95).

Responses

Response samples

Content type
application/json
{
  • "tx_type_counts": {
    },
  • "tx_simple_fee_averages": {
    },
  • "tx_ages": {
    },
  • "tx_byte_sizes": {
    }
}

Get list of details for transactions

Retrieves a list of transactions for a given list of transaction IDs

If using TypeScript, import typings for this response from our types package:

import type { Transaction } from '@stacks/stacks-blockchain-api-types';

query Parameters
tx_id
required
Array of strings
Example: tx_id=0x0a411719e3bfde95f9e227a2d7f8fac3d6c646b1e6cc186db0e2838a2c6cd9c0&tx_id=0xfbe6412b46e9db87df991a0d043ff47eb58019f770208cf48e2380337cc31785&tx_id=0x178b77678a758d9f29a147d6399315c83d0f1baf114431fbe4d3587aa5fbba6f

Array of transaction ids

event_offset
integer
Default: 0

The number of events to skip

event_limit
integer
Default: 96

The numbers of events to return

unanchored
boolean
Default: false
Example: unanchored=true

Include transaction data from unanchored (i.e. unconfirmed) microblocks

Responses

Response samples

Content type
application/json
{
  • "0x8911000000000000000000000000000000000000000000000000000000000000": {
    },
  • "0x8915000000000000000000000000000000000000000000000000000000000000": {
    },
  • "0x8912000000000000000000000000000000000000000000000000000000000000": {
    },
  • "0x8914000000000000000000000000000000000000000000000000000000000000": {
    }
}

Get transaction

Retrieves transaction details for a given transaction ID

import type { Transaction } from '@stacks/stacks-blockchain-api-types';

path Parameters
tx_id
required
string
Example: 0x0a411719e3bfde95f9e227a2d7f8fac3d6c646b1e6cc186db0e2838a2c6cd9c0

Hash of transaction

query Parameters
event_offset
integer
Default: 0

The number of events to skip

event_limit
integer
Default: 96

The numbers of events to return

unanchored
boolean
Default: false
Example: unanchored=true

Include transaction data from unanchored (i.e. unconfirmed) microblocks

Responses

Response samples

Content type
application/json
{
  • "tx_id": "0x5e9f3933e358df6a73fec0d47ce3e1062c20812c129f5294e6f37a8d27c051d9",
  • "tx_status": "success",
  • "tx_type": "coinbase",
  • "fee_rate": "0",
  • "sender_address": "ST3WCQ6S0DFT7YHF53M8JPKGDS1N1GSSR91677XF1",
  • "sponsored": false,
  • "post_condition_mode": "deny",
  • "is_unanchored": false,
  • "microblock_hash": "",
  • "microblock_sequence": 2147483647,
  • "microblock_canonical": true,
  • "block_hash": "0x58412b50266debd0c35b1a20348ad9c0f17e5525fb155a97033256c83c9e2491",
  • "block_height": 3231,
  • "burn_block_time": 1594230455,
  • "canonical": true,
  • "tx_index": 0,
  • "tx_result": {
    },
  • "coinbase_payload": {
    }
}

Get Raw Transaction

Retrieves a hex encoded serialized transaction for a given ID

path Parameters
tx_id
required
string
Example: 0x0a411719e3bfde95f9e227a2d7f8fac3d6c646b1e6cc186db0e2838a2c6cd9c0

Hash of transaction

Responses

Response samples

Content type
application/json
{
  • "raw_tx": "0x1234"
}

Broadcast raw transaction

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

Request Body schema: application/octet-stream
string <binary>

Responses

Response samples

Content type
application/json
{
  • "error": "transaction rejected",
  • "reason": "BadNonce",
  • "reason_data": {
    },
  • "txid": "caf6fd60ae05b0c2d19ef14ab6a7670b1095d117fa7c80224c74e76214d0a791"
}

Get transactions by block

Retrieves transactions confirmed in a single block

path Parameters
required
integer or string

filter by block height, hash, index block hash or the constant latest to filter for the most recent block

Responses

Response samples

Content type
application/json
{
  • "limit": 10,
  • "offset": 0,
  • "total": 101922,
  • "results": [
    ]
}

Get address transactions

Retrieves a paginated list of confirmed transactions sent or received by a STX address or Smart Contract ID, alongside the total amount of STX sent or received and the number of STX, FT and NFT transfers contained within each transaction.

More information on Transaction types can be found here.

path Parameters
address
required
string
Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0

STX address or Smart Contract ID

query Parameters
limit
integer
Example: limit=20

Number of transactions to fetch

offset
integer
Example: offset=10

Index of first transaction to fetch

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 2,
  • "results": [
    ]
}

Get events for an address transaction

Retrieves a paginated list of all STX, FT and NFT events concerning a STX address or Smart Contract ID within a specific transaction.

path Parameters
address
required
string
Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0

STX address or Smart Contract ID

tx_id
required
string
Example: 0x0a411719e3bfde95f9e227a2d7f8fac3d6c646b1e6cc186db0e2838a2c6cd9c0

Transaction ID

query Parameters
limit
integer
Example: limit=20

Number of events to fetch

offset
integer
Example: offset=10

Index of first event to fetch

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 4,
  • "results": [
    ]
}

Transactions by block hash Deprecated

NOTE: This endpoint is deprecated in favor of Get transactions by block.

Retrieves a list of all transactions within a block for a given block hash.

path Parameters
block_hash
required
string
Example: 0x0a83d82a65460a9e711f85a44616350280040b75317dbe486a923c1131b5ff99

Hash of block

query Parameters
limit
integer
Example: limit=10

max number of transactions to fetch

offset
integer
Example: offset=42000

index of first transaction to fetch

Responses

Response samples

Content type
application/json
{
  • "limit": 10,
  • "offset": 0,
  • "total": 101922,
  • "results": [
    ]
}

Transactions by block height Deprecated

NOTE: This endpoint is deprecated in favor of Get transactions by block.

Retrieves all transactions within a block at a given height

path Parameters
height
required
integer
Example: 66119

Height of block

query Parameters
limit
integer
Example: limit=10

max number of transactions to fetch

offset
integer
Example: offset=42000

index of first transaction to fetch

unanchored
boolean
Default: false
Example: unanchored=true

Include transaction data from unanchored (i.e. unconfirmed) microblocks

Responses

Response samples

Content type
application/json
{
  • "limit": 10,
  • "offset": 0,
  • "total": 101922,
  • "results": [
    ]
}

Transactions for address

Retrieves all transactions for a given address that are currently in mempool

path Parameters
address
required
string
Example: SP197DVH8KTJGX4STM61QN0WJV8Y9QJWXV83ZGNR9

Transactions for the address

query Parameters
limit
integer
Example: limit=90

max number of transactions to fetch

offset
integer
Example: offset=42000

index of first transaction to fetch

unanchored
boolean
Default: false
Example: unanchored=true

Include transaction data from unanchored (i.e. unconfirmed) microblocks

Responses

Response samples

Content type
application/json
{
  • "limit": 96,
  • "offset": 0,
  • "total": 5,
  • "results": [
    ]
}

Transaction Events

Retrieves the list of events filtered by principal (STX address or Smart Contract ID), transaction id or event types. The list of event types is ('smart_contract_log', 'stx_lock', 'stx_asset', 'fungible_token_asset', 'non_fungible_token_asset').

query Parameters
tx_id
string
Example: tx_id=0x29e25515652dad41ef675bd0670964e3d537b80ec19cf6ca6f1dd65d5bc642c5

Hash of transaction

address
string
Example: address=ST1HB64MAJ1MBV4CQ80GF01DZS4T1DSMX20ADCRA4

Stacks address or a Contract identifier

limit
integer
Example: limit=100

number of items to return

offset
integer
Example: offset=42000

number of items to skip

type
Array of strings
Items Enum: "smart_contract_log" "stx_lock" "stx_asset" "fungible_token_asset" "non_fungible_token_asset"
Example: type=stx_lock

Filter the events on event type

Responses

Response samples

Content type
application/json
{
  • "limit": 96,
  • "offset": 0,
  • "events": [
    ]
}

Mempool

Endpoints to obtain Mempool information

Get mempool transaction fee priorities

Returns estimated fee priorities (in micro-STX) for all transactions that are currently in the mempool. Also returns priorities separated by transaction type.

Responses

Response samples

Content type
application/json
{
  • "all": {
    },
  • "token_transfer": {
    },
  • "smart_contract": {
    },
  • "contract_call": {
    }
}

Proof of Transfer

Endpoints to get information about the Proof of Transfer consensus mechanism

Get PoX cycles

Retrieves a list of PoX cycles

query Parameters
limit
integer <= 60
Default: 20

max number of cycles to fetch

offset
integer
Example: offset=20

index of first cycle to fetch

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 3,
  • "results": [
    ]
}

Get PoX cycle

Retrieves details for a PoX cycle

path Parameters
cycle_number
required
integer
Example: 56

PoX cycle number

Responses

Response samples

Content type
application/json
{
  • "block_height": 50,
  • "cycle_number": 14,
  • "index_block_hash": "0xf5be33abc4e508bdaf2191e88339372edcb3358c44e2a31e1b9b44f2880dde09",
  • "total_signers": 3,
  • "total_stacked_amount": "1372502700000000000",
  • "total_weight": 9
}

Get signers in PoX cycle

Retrieves a list of signers in a PoX cycle

path Parameters
cycle_number
required
integer
Example: 56

PoX cycle number

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 3,
  • "results": [
    ]
}

Get signer in PoX cycle

Retrieves details for a signer in a PoX cycle

path Parameters
cycle_number
required
integer
Example: 56

PoX cycle number

signer_key
required
string
Example: 0x038e3c4529395611be9abf6fa3b6987e81d402385e3d605a073f42f407565a4a3d

Signer key

Responses

Response samples

Content type
application/json
{
  • "signing_key": "0x038e3c4529395611be9abf6fa3b6987e81d402385e3d605a073f42f407565a4a3d",
  • "signer_address": "STRYYQQ9M8KAF4NS7WNZQYY59X93XEKR31JP64CP",
  • "stacked_amount": "686251350000000000",
  • "stacked_amount_percent": 50,
  • "weight": 5,
  • "weight_percent": 55.55555555555556,
  • "solo_stacker_count": 16,
  • "pooled_stacker_count": 3615
}

Get stackers for signer in PoX cycle

Retrieves a list of stackers for a signer in a PoX cycle

path Parameters
cycle_number
required
integer
Example: 56

PoX cycle number

signer_key
required
string
Example: 0x038e3c4529395611be9abf6fa3b6987e81d402385e3d605a073f42f407565a4a3d

Signer key

Responses

Response samples

Content type
application/json
{
  • "limit": 20,
  • "offset": 0,
  • "total": 1,
  • "results": [
    ]
}

Stacking

Stacking pool members

Retrieves the list of stacking pool members for a given delegator principal.

path Parameters
pool_principal
required
string
Example: SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11

Address principal of the stacking pool delegator

query Parameters
after_block
integer

If specified, only delegation events after the given block will be included

unanchored
boolean
Default: false
Example: unanchored=true

whether or not to include Stackers from unconfirmed transactions

limit
integer <= 200
Default: 100
Example: limit=100

number of items to return

offset
integer
Default: 0
Example: offset=300

number of items to skip

Responses

Response samples

Content type
application/json
{
  • "limit": 200,
  • "offset": 0,
  • "total": 2,
  • "results": [
    ]
}