Migrating from v1 to v3

Overview

Most /extended/v1 endpoints are now deprecated in favor of /extended/v3. The v3 API is a redesign, not a rename: it uses cursor-based pagination, splits large "kitchen sink" responses into focused resources, and nests related fields into objects instead of flattening them into prefixed keys.

Deprecated endpoints still work today. Every response from one carries a Warning header:

Warning: 299 - "Deprecated: See https://docs.hiro.so/stacks/api for more information"

At the sunset date, deprecated endpoints stop executing and return 410 Gone instead. Migrate before then.

What changed in v3

Before mapping endpoints one by one, these are the cross-cutting changes you will hit on almost every route.

Cursor pagination replaces offsets

v1 list endpoints take limit and offset and return { limit, offset, total, results }. v3 list endpoints take limit and cursor, and return { limit, total, cursor: { next, previous, current }, results }. See Pagination for the full walkthrough.

The practical consequence: you cannot jump to an arbitrary page. Walk the list with cursor.next until it is null.

Summaries by default, details on request

v3 list endpoints return a summary of each object (the fields most callers need) rather than the full record. The single-resource endpoints return the full record, and the heavy fields are opt-in via ?include=:

$ 
curl 'https://api.hiro.so/extended/v3/transactions/{tx_id}?include=function_args,post_conditions,result,source_code'Copy

Available include values on GET /extended/v3/transactions/{tx_id}: function_args, source_code, post_conditions, result. They may be repeated (?include=a&include=b) or comma-separated (?include=a,b).

This replaces the v1 exclude_function_args pattern, inverted: v1 sent everything unless you opted out, v3 sends the lean payload unless you opt in.

Nested objects replace prefixed fields

v1 flattened everything into the top level (block_height, burn_block_time, execution_cost_runtime, pending_balance_inbound). v3 groups them (block.height, bitcoin_block.time, execution_cost.runtime, mempool.inbound).

Only canonical data is returned

v1 marked records with a canonical flag. v3 has no such field: it only returns canonical data.

Every timestamp has an ISO twin

v1 returned both burn_block_time and burn_block_time_iso. v3 keeps that pairing in its nested objects: every Unix-seconds time field has a sibling time_iso (ISO 8601, UTC), e.g. block.time / block.time_iso and bitcoin_block.time / bitcoin_block.time_iso. Mempool transactions pair receipt_time with receipt_time_iso.

Hashes without 0x are redirected

Every v3 endpoint that takes a transaction id or block hash in its path answers a hash sent without the 0x prefix with a 302 redirect to the same URL with the prefix, as v1 did. Send the prefix to save the extra round trip.

Transactions

The two v1 "transactions in a block" endpoints collapse into one: {height_or_hash} accepts a block height, a block hash, or the literal latest.

GET /extended/v3/transactions/batch differs from /tx/multiple in two ways. It returns mined transactions only, so use GET /extended/v3/transactions/{tx_id} for one that may still be in the mempool. And it returns a results array rather than a map keyed by transaction id, so ids it cannot resolve are absent from the response instead of being reported as found: false.

GET /extended/v3/mempool replaces the mempool statistics endpoint with a differently shaped summary: fields are renamed and regrouped, percentiles are discrete rather than interpolated, and transaction age in blocks is replaced by receipt_block_height.

Transaction field mapping

status gained a problematic_skipped value in Epoch 4.0 alongside success, abort_by_response, and abort_by_post_condition.

Mempool transactions use receipt_time and receipt_block_height in place of block fields, and their status is one of pending or the dropped_* values.

Accounts and principals

The v1 "address" resource is the v3 "principal" resource.

v3 also adds two transfer feeds with no v1 counterpart:

• GET /extended/v3/principals/{principal}/transfers/stx/outbound — the debit side of stx_inbound.
• GET /extended/v3/principals/{principal}/transfers/ft/{asset_identifier} — a principal's history for one fungible token, credits and debits interleaved in a single feed, newest first, in the token's own base units.

All three transfer endpoints return one result per event rather than per transaction, so a transaction that moves the asset several times for this principal yields several rows. Mints have a null sender and burns a null recipient.

GET /extended/v3/principals/{principal}/balances/nft accepts an optional asset_identifier query parameter, which replaces the v1 asset_identifiers array filter. It takes a single asset class, not a list.

STX balance field mapping

GET /extended/v1/address/{principal}/stx → GET /extended/v3/principals/{principal}/balances/stx

v1 accepted until_block on the balance endpoints. v3 always reports the current chain tip.

Miner rewards

v1 only exposed a principal's miner rewards as the total_miner_rewards_received counter on the STX balance. v3 gives them their own resource:

• GET /extended/v3/principals/{principal}/mining — lifetime matured miner reward totals, { rewards: { count, coinbase, fees, total } }, in µSTX.
• GET /extended/v3/principals/{principal}/mining/rewards — the individual matured rewards, cursor-paginated, newest first. Each reports the block it matured (and was credited) in and the source_block whose reward matured.

Miner rewards are credited to the recipient's balance without a transaction or STX event, so they never appear in the principal's transactions or transfer feeds. Only canonical rewards are counted, and zero-value rewards are left out.

FT and NFT balances

GET /extended/v1/address/{principal}/balances returned FT and NFT balances as objects keyed by asset identifier, with the NFT entry being a count. v3 returns cursor-paginated arrays instead:

• GET /extended/v3/principals/{principal}/balances/ft — { asset_identifier, balance } per token, sorted by balance descending.
• GET /extended/v3/principals/{principal}/balances/ft/{asset_identifier} — a single token's balance; returns zero rather than 404 when the principal does not hold it.
• GET /extended/v3/principals/{principal}/balances/nft — one entry per owned NFT instance, { asset_identifier, value: { hex, repr } }, not a per-collection count.

The v1 total_sent / total_received counters on each token are not carried over.

Nonce field mapping

GET /extended/v1/address/{principal}/nonces → GET /extended/v3/principals/{principal}/nonces

The v1 endpoint accepted block_height and block_hash to read the nonce at a past block. v3 only reports current nonce state.

Account transactions and transfers

v1 had three overlapping endpoints. v3 has two, with a cleaner split between "which transactions touched this principal" and "what changed for this principal".

GET /extended/v3/principals/{principal}/transactions returns, per transaction:

• transaction — the transaction summary (same shape as GET /extended/v3/transactions).
• involvement — sender, sponsor, or affected.
• balance_changes.stx — { sent, received, net } in micro-STX, fee included in sent.
• affected_balances — { stx, ft, nft } booleans telling you whether it is worth fetching the detailed balance changes.

For the FT and NFT detail that v1 packed into stx_transfers / ft_transfers / nft_transfers, call GET /extended/v3/principals/{principal}/transactions/{tx_id}/balance-changes, or fetch several transactions at once with GET /extended/v3/principals/{principal}/balance-changes?tx_id=A,B,C for several IDs in one call.

Each balance change is { asset: { type, identifier? }, balance_change: { sent, received, net } }, where type is stx, ft, or nft.

Blocks

{height_or_hash} on GET /extended/v3/blocks/{height_or_hash} accepts a block height, a block hash, an index block hash, or the literal latest. The two v1 "by burn block" endpoints returned a single Stacks block; their v3 replacement returns every canonical Stacks block anchored to that Bitcoin block, as a cursor-paginated list, newest first. Since Nakamoto there are usually many.

If you already migrated to the v2 block routes (GET /extended/v2/blocks, GET /extended/v2/blocks/{height_or_hash}, GET /extended/v2/burn-blocks*), those are deprecated too and move to the same v3 endpoints — see Also deprecated: v2 endpoints.

Block field mapping

GET /extended/v3/blocks returns block summaries; GET /extended/v3/blocks/{height_or_hash} adds the fields marked "detail only".

Bitcoin blocks

v3 renames "burn blocks" to Bitcoin blocks:

The API learns a Bitcoin block's time from the Stacks blocks anchored to it. For a past Bitcoin block no Stacks block anchored to (a missed sortition, for example), time is interpolated between its neighbors. For the newest Bitcoin blocks no Stacks block has anchored to yet, time is null and projected_time carries an estimate instead. GET /extended/v3/bitcoin-blocks/{height} also accepts a height above the Bitcoin tip and returns that future block with a null hash and its projected time, rather than 404.

Smart contracts

Contract field mapping

GET /extended/v1/contract/{contract_id} → GET /extended/v3/smart-contracts/{contract_id}

Stacking rewards

The burnchain reward endpoints report the Bitcoin reward addresses and BTC payouts of the pox-1 through pox-4 reward model. That model is keyed on the pox-addr a stacker supplies when stacking, and pox-5 has no such address: stakers lock BTC or sBTC against a bond, and rewards accrue as sBTC on the Stacks layer rather than as BTC sent to a burnchain address.

These endpoints therefore serve historical pox-4-and-earlier data only. No new records are written to them once the last pox-4 lock unlocks.

For per-burn-block BTC payouts under the current model, see GET /extended/v2/burn-blocks/{height_or_hash}/pox-transactions and GET /extended/v2/addresses/{burnchain_address}/pox-transactions, which are not deprecated.

Stacking events

The pox4 event endpoints read the pox-2 through pox-4 event tables and have no pox-5 event history counterpart. They serve historical data only.

The same deprecation applies under the pox2 and pox3 prefixes.

Search

v1 took a complete hash or ID in the path and returned the first match. v3 takes the search term in the q query parameter, accepts partial terms as well as complete ones, matches block heights and token assets in addition to blocks, transactions, contracts, and accounts, and returns up to 20 ranked matches.

Faucets

The v3 faucets take the recipient as an address field in a JSON body rather than the query string, send a single fixed amount configured by the API operator (no size or stacking options), and return a transaction object plus the amount sent instead of the transaction id and raw transaction hex. They remain testnet-only.

Fees

STX supply

All four v1 supply endpoints — including the JSON one — are deprecated in favor of a single v3 endpoint.

Supply field mapping

Fungible tokens

v1 took the literal string stx in the token path parameter to mean STX holders. v3 splits that into its own route, matching how /tokens/stx/supply is already separated, and validates {asset_identifier} as a real Clarity asset identifier.

Holder field mapping

The v1 response fused total_supply into the paginated envelope as an extra top-level field. In v3 the holders response is the standard cursor envelope and nothing else, and supply is its own endpoint — { asset_identifier, total } for fungible tokens, or the existing /tokens/stx/supply for STX.

Balances are in the token's own base units. This API does not know a token's decimal precision — fetch that from the Token Metadata API.

For /tokens/stx/holders, the balance is the total µSTX held, including STX locked for stacking. It is not the spendable figure that GET /extended/v3/principals/{principal}/balances/stx reports as available.

Non-fungible tokens

asset_identifier moved from a query parameter into the path, matching the fungible token routes. The token instance moved into the path too, and is accepted in two forms:

• A plain integer — a SIP-009 token id, e.g. .../the-explorer-guild/2051/history. This is the form to use for almost every collection.
• A 0x-prefixed serialized Clarity value — required for assets not keyed by a uint. BNS names are the notable case: bns.clar defines them as { name: (buff 48), namespace: (buff 20) }, a tuple, so they have no integer id.

Field mapping

Network block times

These return hardcoded legacy values (600s mainnet, 120s testnet) that no longer reflect actual Stacks block production since the Nakamoto upgrade. For real block timing, use GET /extended/v2/blocks/average-times, which is not deprecated.

BNS

All BNS endpoints are deprecated. They are no longer maintained.

Endpoints without a v3 replacement

These are deprecated with no successor. Plan around them rather than swapping a URL.

Also deprecated: v2 endpoints

A handful of /extended/v2 routes are deprecated alongside v1 and move to v3. If you already migrated from v1 to v2, these are your next hop.

See Blocks for the block and Bitcoin block field mappings.

Endpoints that are not deprecated

Every /extended/v1 route is now deprecated except the API status endpoint, GET /extended.

These /extended/v2 routes are not deprecated and have no v3 successor yet: GET /extended/v2/blocks/average-times, GET /extended/v2/blocks/by-block-time/{timestamp}, GET /extended/v2/blocks/{height_or_hash}/signer-signatures, GET /extended/v2/block-tenures/{tenure_height}/blocks, GET /extended/v2/pox/cycles*, GET /extended/v2/mempool/fees, GET /extended/v2/smart-contracts/*, and the two pox-transactions routes noted under Stacking rewards.