Stacks Blockchain API

March 11, 2026 · View on GitHub

CI GitHub Releases Docker Pulls NPM client package

A Fastify-based REST API with real-time WebSocket and Socket.IO support for the Stacks blockchain. It indexes on-chain data from a Stacks node into PostgreSQL and exposes it through a rich set of RESTful endpoints, a full OpenAPI specification, and real-time event streams.

Table of Contents

Features

  • Nakamoto support — full support for Nakamoto blocks, tenures, signer signatures, and NakamotoCoinbase / TenureChange transaction types
  • Comprehensive REST API — v1 and v2 endpoints covering blocks, transactions, accounts, smart contracts, NFTs, fungible tokens, BNS (Bitcoin Name System), PoX / stacking, burn chain rewards, and more
  • Real-time streaming — subscribe to blocks, microblocks, mempool transactions, address activity, STX balance changes, and NFT events via WebSocket (JSON-RPC) or Socket.IO
  • Client library — type-safe TypeScript/JS client for REST and real-time APIs (@stacks/blockchain-api-client)
  • OpenAPI specification — auto-generated from route definitions; powers Redoc documentation, Postman collections, and the TypeScript client
  • Stacks node RPC proxy — transparently proxies requests to the underlying Stacks node's /v2/* endpoints, with optional fee estimation
  • Multiple run modes — default (read-write), read-only, and write-only modes for flexible scaling
  • Prometheus metrics — built-in /metrics endpoint for monitoring
  • SNP integration — Stacks Nakamoto Protocol event streaming via Redis
  • BNS — full Bitcoin Name System support including name lookups, namespaces, subdomains, zonefiles, and pricing
  • BTC & STX faucets — testnet/regtest faucet endpoints for development

Quick Start

Local Development with Clarinet

The easiest way to run the API locally is with Clarinet, which spins up a full devnet environment (Bitcoin node, Stacks node, API, and PostgreSQL):

clarinet devnet start

See the Clarinet documentation to get started.

Production

Use the official Docker image for mainnet or testnet:

docker pull hirosystems/stacks-blockchain-api

The API cannot run standalone — it requires a running Stacks node and a PostgreSQL database. See Deployment for details, or refer to the Stacks node operator guide.

API Endpoints

Extended API v2

The recommended versioned endpoints:

GroupPrefixKey Endpoints
Blocks/extended/v2/blocksList blocks, get by height/hash, list transactions, signer signatures, average block times
Burn Blocks/extended/v2/burn-blocksList burn blocks, get by height/hash, list Stacks blocks per burn block, PoX transactions
Block Tenures/extended/v2/block-tenuresList blocks for a given tenure height
Addresses/extended/v2/addressesTransactions for address, transaction events, STX balance, FT balances, PoX transactions by BTC address
PoX/extended/v2/poxPoX cycles, signers per cycle, stackers per signer
Smart Contracts/extended/v2/smart-contractsContract deployment status
Mempool/extended/v2/mempoolMempool fee priorities

Extended API v1

GroupPrefixKey Endpoints
Transactions/extended/v1/txRecent, by ID, raw, by block hash/height, mempool, mempool stats, events
Blocks/extended/v1/blockList, by height, by hash, by burn block height/hash
Microblocks/extended/v1/microblockList, by hash, unanchored transactions
Accounts/extended/v1/addressSTX balance, all balances, transactions, assets, inbound transfers, nonces, mempool
Tokens/extended/v1/tokensNFT holdings, NFT history, NFT mints, FT holders
Smart Contracts/extended/v1/contractBy trait, by ID, contract events
Search/extended/v1/searchUniversal search (blocks, transactions, contracts, addresses)
PoX/extended/v1/pox2, pox3, pox4PoX events, stacker info, delegations
STX Supply/extended/v1/stx_supplyTotal, circulating, legacy format
Burn Chain/extended/v1/burnchainReward slot holders, rewards, total rewards
Fee Rate/extended/v1/fee_rateFee rate estimation
Info/extended/v1/infoNetwork block times
Faucets/extended/v1/faucetsBTC and STX testnet faucets

BNS (Bitcoin Name System)

PrefixEndpoints
/v1/namesList names, get name details, zonefiles, subdomains
/v1/namespacesList namespaces, names in a namespace
/v1/addressesResolve blockchain address to names
/v2/pricesNamespace and name pricing

Stacks Node RPC Proxy

All requests to /v2/* (e.g. /v2/info, /v2/fees/transaction) are proxied to the connected Stacks core node.

Run Modes

The API supports three run modes, controlled by the STACKS_API_MODE environment variable:

Default (read-write)

Runs the event server (ingests data from a Stacks node) and the API server. This is the standard mode for a single-instance deployment.

# STACKS_API_MODE is unset or set to any value other than readonly/writeonly

Read-only

Runs only the API server. Reads data from PostgreSQL but does not ingest events. Requires a separate write-only instance populating the same database.

Useful for horizontally scaling API instances behind a load balancer. Read-only instances fully support WebSocket and Socket.IO subscriptions.

STACKS_API_MODE=readonly

Write-only

Runs only the event server. Ingests Stacks node events into PostgreSQL but does not serve any API endpoints.

Useful when consuming blockchain data directly from the database without the overhead of an HTTP server.

STACKS_API_MODE=writeonly

Configuration

Configuration is done via environment variables. A .env file in the project root is loaded automatically via dotenv-flow.

Required

VariableDescription
STACKS_CHAIN_IDChain ID — 0x00000001 (mainnet) or 0x80000000 (testnet)
STACKS_BLOCKCHAIN_API_HOSTAPI server bind host
STACKS_BLOCKCHAIN_API_PORTAPI server port (typically 3999)
STACKS_CORE_RPC_HOSTStacks node RPC host
STACKS_CORE_RPC_PORTStacks node RPC port

PostgreSQL

VariableDescriptionDefault
PG_CONNECTION_URIFull connection URI (overrides individual vars)—
PG_HOSTDatabase host—
PG_PORTDatabase port5432
PG_USERDatabase user—
PG_PASSWORDDatabase password—
PG_DATABASEDatabase name—
PG_SCHEMADatabase schema—
PG_SSLEnable SSLfalse
PG_CONNECTION_POOL_MAXMax pool size10
PG_IDLE_TIMEOUTIdle timeout (seconds)30
PG_MAX_LIFETIMEMax connection lifetime (seconds)60

A PG_PRIMARY_* prefix is available for all PostgreSQL variables to configure a separate primary connection used for LISTEN/NOTIFY.

Event Server

VariableDescriptionDefault
STACKS_CORE_EVENT_HOSTEvent server bind host127.0.0.1
STACKS_CORE_EVENT_PORTEvent server port3700
STACKS_CORE_EVENT_BODY_LIMITMax event body size (bytes)500000000

RPC Proxy

VariableDescriptionDefault
STACKS_CORE_PROXY_HOSTProxy host (falls back to RPC host)—
STACKS_CORE_PROXY_PORTProxy port (falls back to RPC port)—
STACKS_CORE_PROXY_BODY_LIMITProxy body limit (bytes)10000000
STACKS_CORE_FEE_ESTIMATOR_ENABLEDEnable fee estimator proxyfalse

Redis (optional)

VariableDescriptionDefault
REDIS_NOTIFIER_ENABLEDEnable Redis-based index notifierfalse
REDIS_URLRedis URL—
SNP_EVENT_STREAMINGEnable SNP Redis streamingfalse
SNP_REDIS_URLSNP Redis URL—

Other

VariableDescriptionDefault
STACKS_API_MODERun mode (readonly, writeonly, or default)—
STACKS_API_LOG_LEVELLog level—
STACKS_PROFILER_PORTEnable profiler on this port—
IBD_MODE_UNTIL_BLOCKInitial block download mode until block height—
BNS_IMPORT_DIRDirectory with V1 BNS export data—
STACKS_SHUTDOWN_FORCE_KILL_TIMEOUTGraceful shutdown timeout (seconds)60

Development

Prerequisites

  • Node.js >= 22
  • Docker (for service dependencies)

Setup

git clone https://github.com/hirosystems/stacks-blockchain-api.git
cd stacks-blockchain-api
npm install

Running Locally

The quickest way to start with all dependencies (PostgreSQL, Stacks node, Bitcoin node):

npm run dev:integrated

This uses Docker Compose to start the service dependencies and runs the API in development mode.

Alternatively, use the VS Code "Launch: w/ postgres" debug configuration.

Verify the server is running:

http://localhost:3999/extended/v1/status

Building

npm run build        # Compile TypeScript
npm run build:docs   # Generate OpenAPI spec and Redoc docs
npm run build:client # Generate client types from OpenAPI spec

Testing

npm test                        # Run all tests
npm run test:api                # API endpoint tests
npm run test:bns                # BNS tests
npm run test:2.5                # PoX-4 / stacking tests
npm run test:event-replay       # Event replay tests
npm run test:snp                # SNP ingestion tests

Integration tests spin up their own PostgreSQL via Docker:

npm run test:integration

Linting

npm run lint        # ESLint + Prettier
npm run lint:fix    # Auto-fix

OpenAPI Spec Generation

The OpenAPI specification is generated directly from Fastify route definitions:

npm run generate:openapi    # Generate docs/openapi.yaml and docs/openapi.json
npm run generate:redoc      # Generate Redoc HTML documentation
npm run generate:postman    # Generate Postman collection
npm run generate:client     # Generate TypeScript client types

Event Replay

When upgrading to a new major version with breaking database schema changes, the database must be rebuilt. Event replay allows re-ingesting historical events without a full chain re-sync.

Using stacks-event-replay

The recommended approach is the stacks-event-replay tool. Follow its installation instructions.

Manual Export / Import

  1. Stop the API process (allow in-progress writes to finish).

  2. Export events:

    node ./lib/index.js export-events --file /tmp/stacks-node-events.tsv

  3. Update to the new API version.

  4. Import events (this drops all existing tables):

    node ./lib/index.js import-events --file /tmp/stacks-node-events.tsv --wipe-db --force

    Import modes via --mode:

    • archival (default) — imports all events from genesis
    • pruned — skips mempool and microblock events until near chain tip, trading historical data for speed

Deployment

Requirements

  • PostgreSQL 14 or newer
  • A synced Stacks node configured to emit events to the API
  • (Optional) Redis, for SNP streaming or index notifications in HA setups

Docker

docker pull hirosystems/stacks-blockchain-api

The image runs node ./lib/index.js and expects the environment variables described in Configuration.

A standalone regtest Dockerfile is also available at docker/standalone-regtest.Dockerfile, which bundles the API, Stacks node, Bitcoin node, and PostgreSQL into a single image for testing.

Upgrading

Major version upgrades (e.g., 7.x to 8.x) may include breaking database schema changes. Use Event Replay to rebuild the database. Check the CHANGELOG for details on each release.

Bugs and Feature Requests

  1. Search for existing issues — check existing and closed issues before opening a new one.
  2. Open a new issue — use the appropriate issue template with as much detail as possible.
  3. Response SLA — the team evaluates issues Monday through Friday and aims to respond within 7 business days.

For personal support or transaction status questions, use the #support channel on Discord.

Contributing

Development happens in the open on GitHub. Read below to learn how to contribute.

Please read the Code of Conduct before participating.

Issues

Report bugs and request features via the GitHub issue tracker. Include reproduction steps and as much context as possible.

Pull Requests

Pull requests should target the develop branch, not master.

Community

  • Discord — chat with other developers and the Hiro team
  • hiro.so — product updates and mailing list
  • Twitter / X — follow Hiro for announcements

License

GPL-3.0 — see LICENSE for details.