Documentation Powered by ReDoc

Stacks Blockchain API (v1.0.6)

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

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

query Parameters
unanchored
boolean
Default: false

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

until_block
string

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

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

query Parameters
unanchored
boolean
Default: false

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

until_block
string

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

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

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

path Parameters
principal
required
string

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

query Parameters
limit
integer

max number of account transactions to fetch

offset
integer

index of first account transaction to fetch

height
number

Filter for transactions only at this given block height

unanchored
boolean
Default: false

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

until_block
string

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": 4989,
  • "results": [
    ]
}

Get account transaction information for specific transaction

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

path Parameters
principal
required
string

Stacks address or a contract identifier

tx_id
required
string

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.

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

path Parameters
principal
required
string

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

query Parameters
limit
integer

max number of account transactions to fetch

offset
integer

index of first account transaction to fetch

height
number

Filter for transactions only at this given block height

unanchored
boolean
Default: false

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

until_block
string

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

Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0)

query Parameters
block_height
number

Optionally get the nonce at a given block height

block_hash
string

Optionally get the nonce at a given block hash

Responses

Response samples

Content type
application/json
{
  • "last_mempool_tx_nonce": 5,
  • "last_executed_tx_nonce": 2,
  • "possible_next_nonce": 6,
  • "detected_missing_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

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

query Parameters
limit
integer

max number of account assets to fetch

offset
integer

index of first account assets to fetch

unanchored
boolean
Default: false

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

until_block
string

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

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

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

query Parameters
limit
integer

number of items to return

offset
integer

number of items to skip

height
number

Filter for transfers only at this given block height

unanchored
boolean
Default: false

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

until_block
string

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": 0,
  • "results": [
    ]
}

Get nft events

Retrieves a list of all nfts owned by an address, contains the clarity value of the identifier of the nft

path Parameters
principal
required
string

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

query Parameters
limit
integer

number of items to return

offset
integer

number of items to skip

unanchored
boolean
Default: false

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

until_block
string

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": 1,
  • "nft_events": [
    ]
}

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

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

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 recent blocks

Retrieves a list of recently mined blocks

query Parameters
limit
integer <= 200
Default: 20

max number of blocks to fetch

offset
integer

index of first block to fetch

Responses

Response samples

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

Get block by hash

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

path Parameters
hash
required
string

Hash of the block

Responses

Response samples

Content type
application/json
{
  • "canonical": true,
  • "height": 3275,
  • "hash": "0xe77ba8cf6bb7c0e4f64adc83356289ed467d31a22354907b4bb814590058430f",
  • "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
}

Get block by height

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

path Parameters
height
required
number

Height of the block

Responses

Response samples

Content type
application/json
{
  • "canonical": true,
  • "height": 3275,
  • "hash": "0xe77ba8cf6bb7c0e4f64adc83356289ed467d31a22354907b4bb814590058430f",
  • "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
}

Get block by burnchain block hash

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

path Parameters
burn_block_hash
required
string

Hash of the burnchain block

Responses

Response samples

Content type
application/json
{
  • "canonical": true,
  • "height": 3275,
  • "hash": "0xe77ba8cf6bb7c0e4f64adc83356289ed467d31a22354907b4bb814590058430f",
  • "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
}

Get block by burnchain height

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

path Parameters
burn_block_height
required
number

Height of the burn chain block

Responses

Response samples

Content type
application/json
{
  • "canonical": true,
  • "height": 3275,
  • "hash": "0xe77ba8cf6bb7c0e4f64adc83356289ed467d31a22354907b4bb814590058430f",
  • "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
}

Faucets

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

Get STX tokens

Retrieves STX tokens into you TestNet STX address.

query Parameters
address
required
string

STX address

stacking
boolean
Default: false

Request the amount of STX needed for stacking

Responses

Response samples

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

Get BTC tokens

Retrieves BTC tokens into your TestNet BTC address.

query Parameters
address
required
string

BTC address

Responses

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

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
}

Fungible Tokens

Read-only endpoints to obtain fungible token details

Stacks Documentation - Tokens

Fungible tokens metadata list

Retrieves list of fungible tokens with their metadata. More information on Fungible Tokens on the Stacks blockchain can be found here.

query Parameters
limit
integer

max number of tokens to fetch

offset
integer

index of first tokens to fetch

Responses

Response samples

Content type
application/json
{}

Fungible tokens metadata for contract id

Retrieves the metadata for fungible tokens for a given contract id

path Parameters
contractId
required
string

token's contract id

Responses

Response samples

Content type
application/json
{}

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
}

Get Blockchain API status

Retrieves the current status of the blockchain API, including the server version

Responses

Response samples

Content type
application/json
{
  • "server_version": "stacks-blockchain-api v0.64.1 (master:439d4f46)",
  • "status": "ready"
}

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"

Which network to retrieve the target block time of

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

query Parameters
height
number

The block height at which to query supply details from, if not provided then the latest block height is used

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.

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.

query Parameters
height
number

The block height at which to query supply details from, if not provided then the latest block height is used

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": "ST000000000000000000002AMW42H.pox",
  • "first_burnchain_block_height": 0,
  • "min_amount_ustx": 150000000000,
  • "registration_window_length": 250,
  • "rejection_fraction": 25,
  • "reward_cycle_id": 0,
  • "reward_cycle_length": 1000,
  • "rejection_votes_left_required": 1000,
  • "total_liquid_supply_ustx": 1000000000
}

Microblocks

Read-only endpoints to obtain microblocks details

Stacks Documentation - Microblocks

Get recent microblocks

Retrieves a list of microblocks.

query Parameters
limit
integer <= 200
Default: 20

Max number of microblocks to fetch

offset
integer

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

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": "STX",
  • "amount": "4000000000"
}

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
{
  • "name_price": {
    }
}

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
required
integer
Example: page=23

names are returned in pages of size 100, so specify the page number.

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
required
integer
Example: page=23

names are returned in pages of size 100, so specify the page number.

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 History

Retrieves a history of all blockchain records of a registered name.

path Parameters
name
required
string
Example: muneeb.id

name to query

query Parameters
page
required
integer

the page (in 20-entry pages) of the history to fetch

Responses

Response samples

Content type
application/json
{
  • "zonefile": "$ORIGIN muneeb.id\n$TTL 3600\n_http._tcp IN URI 10 1 \"https://blockstack.s3.amazonaws.com/muneeb.id\"\n"
}

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
{
  • "$schema": "http://json-schema.org/draft-07/schema",
  • "$id": "bns-fetch-historical-zone-file-response",
  • "title": "BnsFetchHistoricalZoneFileResponse",
  • "description": "Fetches the historical zonefile specified by the username and zone hash.",
  • "required": [ ],
  • "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": [
    ]
}

Get All Subdomains

Retrieves a list of all subdomains known to the node.

query Parameters
page
required
integer
Example: page=3

names are returned in pages of size 100, so specify the page number.

Responses

Response samples

Content type
application/json
[
  • "collegeinfogeek.verified.podcast",
  • "collider.verified.podcast",
  • "combatandclassics.verified.podcast",
  • "combatjack.verified.podcast",
  • "comedybangbang.verified.podcast",
  • "comedybutton.verified.podcast",
  • "commonsense.verified.podcast",
  • "concilio002.personal.id"
]

Get Subdomain at Transaction

Retrieves the list of subdomain operations processed by a given transaction. The returned array includes subdomain operations that have not yet been accepted as part of any subdomain’s history (checkable via the accepted field). If the given transaction ID does not correspond to a Stacks transaction that introduced new subdomain operations, and empty array will be returned.

path Parameters
txid
required
string
Example: d04d708472ea3c147f50e43264efdb1535f71974053126dc4db67b3ac19d41fe

transaction id

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Non-Fungible Tokens

Read-only endpoints to obtain non-fungible token details

Stacks Documentation - Tokens

Non fungible tokens metadata list

Retrieves a list of non fungible tokens with their metadata. More information on Non-Fungible Tokens on the Stacks blockchain can be found here.

query Parameters
limit
integer

max number of tokens to fetch

offset
integer

index of first tokens to fetch

Responses

Response samples

Content type
application/json
{}

Non fungible tokens metadata for contract id

Retrieves metadata for non fungible tokens for a given contract id. More information on Non-Fungible Tokens on the Stacks blockchain can be found here.

path Parameters
contractId
required
string

token's contract id

Responses

Response samples

Content type
application/json
{}

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
{
  • "network_identifier": {
    },
  • "metadata": { }
}

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
{
  • "network_identifier": {
    },
  • "metadata": { }
}

Response samples

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

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) (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": {
    },
  • "block_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) (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) (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 transcations 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
{
  • "network_identifier": {
    },
  • "metadata": { }
}

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": "string"
}

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.

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": "string"
}

Response samples

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

Generate an Unsigned Transaction and Signing Payloads

Generate and unsigned transaction from operations and metadata

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": [
    ],
  • "public_keys": [
    ],
  • "metadata": {
    }
}

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

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": "string",
  • "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

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 contract info

Retrieves details of a contract with a given contract_id

path Parameters
contract_id
required
string

Contract identifier formatted as <contract_address>.<contract_name>

query Parameters
unanchored
boolean
Default: false

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

Responses

Response samples

Content type
application/json
{
  • "tx_id": "0x8122b7ae041120ddc9e2f8108e165912e40ad146399d42d6e6cbca7fd2c8ac28",
  • "tx_status": "success",
  • "tx_type": "smart_contract",
  • "fee_rate": "3000",
  • "sender_address": "STJTXEJPJPPVDNA9B052NSRRBGQCFNKVS178VGH1",
  • "sponsored": false,
  • "post_condition_mode": "allow",
  • "is_unanchored": false,
  • "microblock_hash": "",
  • "microblock_sequence": 2147483647,
  • "microblock_canonical": true,
  • "block_hash": "0x105685d3d4f251d73b75865b192cefb111dd49f67b8970a95094dc7ecf826caa",
  • "block_height": 3196,
  • "burn_block_time": 1594228322,
  • "canonical": true,
  • "tx_index": 1,
  • "post_conditions": [ ],
  • "smart_contract": {
    },
  • "events": [
    ]
}

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

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

Contract identifier formatted as <contract_address>.<contract_name>

query Parameters
limit
integer

max number of contract events to fetch

offset
integer

index of first contract event to fetch

unanchored
boolean
Default: false

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

Stacks address

contract_name
required
string

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

Stacks address

contract_name
required
string

Contract name

map_name
required
string

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
"string"

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

Stacks address

contract_name
required
string

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

Stacks address

contract_name
required
string

Contract name

function_name
required
string

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": "string",
  • "arguments": [
    ]
}

Response samples

Content type
application/json
Example
success
success
fail
null

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

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

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

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

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

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

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

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

max number of transactions to fetch

offset
integer

index of first transaction to fetch

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

Filter by transaction type

unanchored
boolean
Default: false

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.

query Parameters
sender_address
string

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

limit
integer <= 200
Default: 96

max number of mempool transactions to fetch

offset
integer

index of first mempool transaction to fetch

unanchored
boolean
Default: false

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

index of first mempool transaction to fetch

Responses

Response samples

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

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

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

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

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

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

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

Request samples

Content type
application/octet-stream
binary format of 00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000

Response samples

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

Transactions by block hash

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

path Parameters
block_hash
required
string

Hash of block

query Parameters
limit
integer

max number of transactions to fetch

offset
integer

index of first transaction to fetch

Responses

Response samples

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

Transactions by block height

Retrieves all transactions within a block at a given height

path Parameters
height
required
integer

Height of block

query Parameters
limit
integer

max number of transactions to fetch

offset
integer

index of first transaction to fetch

unanchored
boolean
Default: false

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

Transactions for the address

query Parameters
limit
integer

max number of transactions to fetch

offset
integer

index of first transaction to fetch

unanchored
boolean
Default: false

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

Responses

Response samples

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