Documentation Powered by ReDoc

Stacks 2.0 Blockchain API (1.0.0)

Download OpenAPI specification:Download

This is the documentation for the Stacks 2.0 Blockchain API.

It is comprised of two parts; the Stacks Blockchain API and the Stacks Core API.

Run in Postman

Faucets

Get STX tokens

Get STX tokens for the testnet

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

Get BTC tokens for the testnet

query Parameters
address
required
string

BTC address

Responses

Response samples

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

Transactions

Get recent transactions

Get 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

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

Get all recently-broadcast mempool transactions

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

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

Get all recently-broadcast mempool transactions

query Parameters
limit
integer

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 transaction

Get a specific transaction by 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

Get raw transaction by ID

path Parameters
tx_id
required
string

Hash of transaction

Responses

Response samples

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

Broadcast raw transaction

Broadcast 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 in a block

Get all transactions in block

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 in a block

Get all transactions in block by 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

Get all transactions for address 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": [
    ]
}

Microblocks

Get recent microblocks

query Parameters
limit
integer

Max number of microblocks to fetch

offset
integer

Index of the first microblock to fetch

Responses

Response samples

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

Get microblock

Get 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

This contains 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": [
    ]
}

Blocks

Get recent blocks

Get all recently mined blocks

query Parameters
limit
integer

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

Get a specific block by hash

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": [
    ]
}

Get block

Get a specific block by 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": [
    ]
}

Burnchain

Get recent reward slot holders

Array of the Bitcoin addresses that would validly receive PoX commitments.

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 reward slot holder entries for the given address

Array of the Bitcoin addresses that would validly receive PoX commitments.

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

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

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 recent burnchain reward for the given recipient

Get 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

Get the total burnchain (e.g. Bitcoin) rewards for the given recipient

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

Smart Contracts

Get contract info

Get contract info using the 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 contract events

Get contract events using a 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

Get contract interface using a 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] and [Contract Name] in the URL path. The map is identified with [Map Name].

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

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

path Parameters
contract_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

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

path Parameters
contract_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": "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info",
  • "arguments": [
    ]
}

Response samples

Content type
application/json
Example
success
success
fail
null

Accounts

Get account balances

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

Responses

Response samples

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

Get account STX balance

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

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

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

Responses

Response samples

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

Get account transactions 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

Responses

Response samples

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

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

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

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

Responses

Response samples

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

Get inbound STX transfers

Get 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

Responses

Response samples

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

Get nft events

Get 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

Responses

Response samples

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

Get account info

Get the account data for the provided principal

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

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

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

Fees

Get estimated fee

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

Responses

Response samples

Content type
application/json
1

Info

Get Core API info

Get Core API information

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

Get Blockchain API status

Responses

Response samples

Content type
application/json
{
  • "status": "ready"
}

Get the network target block time

Responses

Response samples

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

Get a given network's target block time

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

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

Responses

Response samples

Content type
text/plain
123.456789

Get circulating STX supply in plain text format

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)

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 PoX details

Get 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
}

Search

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

Responses

Response samples

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

Rosetta

Get List of Available Networks

This endpoint returns a list of NetworkIdentifiers that the Rosetta server supports.

Responses

Response samples

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

Get Network Options

This endpoint returns 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

This endpoint returns 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

A BlockRequest is utilized to make a block request on the /block endpoint.

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

A BlockTransactionRequest is used to fetch 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
object (RosettaBlockIdentifier)

The block_identifier uniquely identifies a block in a particular network.

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

Get all Transaction Identifiers in the mempool.

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

A MempoolTransactionRequest is utilized to retrieve a transaction from the mempool.

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

TODO

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

TODO

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

TODO

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

BNS

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

Fetch a list of all namespaces known to the node.

Responses

Response samples

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

Fetch a list of names from the 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"
]

Fetch 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"
]

Fetch name details.

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

Fetch 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"
}

Fetches 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": [
    ]
}

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": [
    ]
}

Fetch 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"
]

Fetches 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 Blockstack 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
[
  • {
    },
  • {
    }
]