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

Design

Stacks Core API vs Stacks Blockchain API

The blockchain's Rust implementation exposes a JSON RPC endpoint ("Stacks Core API"), which can be used to interface with the blockchain. It can be used directly. See the documentation for the stacks-blockchain in its Github repository

All /v2/ routes a proxied to a Blockstack PBC-hosted Stacks Node. For a trustless architecture, you should make these requests to a self-hosted node.

All /extended/ routes are provided by the Stacks 2.0 Blockchain API directly. They extend the Stacks Core API capabilities to make it easier to integrate with.

Pagination

To make API responses more compact, lists returned by the API are paginated. For lists, the response body includes:

  • limit: the number of list items return per response
  • offset: the number of elements to skip (starting from 0)
  • total: the number of all available list items
  • results: the array of list items (length of array equals the set limit)

Using the limit and offset properties, you can paginate through the entire list by increasing the offset by the limit until you reach the total.

Client Library

A generated JS Client is available for consumption of this API. The client enables typesafe REST and WebSocket communication. Please review the client documentation for more details.

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 '@blockstack/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

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