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

Microblock and unanchored fields are gone

Microblocks were removed in the Nakamoto upgrade. v3 has no microblock_hash, microblock_sequence, microblock_canonical, is_unanchored, or unanchored query parameter. There is also no canonical field. v3 only returns canonical data.

ISO timestamp duplicates are gone

v1 returned both burn_block_time and burn_block_time_iso. v3 returns Unix seconds only (block.time, bitcoin_block.time). Format them client-side.

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.

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 and unanchored on the balance endpoints. v3 always reports the current chain tip.

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 (up to 50 IDs).

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

Blocks

Blocks did not move to v3 — only the transactions in a block did. The v1 block endpoints are superseded by v2.

The v1 block responses embedded a txs array of transaction IDs. In v2 the block object carries a tx_count; fetch the transactions from GET /extended/v3/blocks/{height_or_hash}/transactions.

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.

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.

Endpoints that are not deprecated

Most of /extended/v1 is now deprecated, but these routes are not. They remain the supported way to fetch their data today:

The pox4 prefix also accepts pox2 and pox3 for historical data. Faucet endpoints are testnet-only.

Outside /extended/v1, these /extended/v2 routes are also current and have no v3 successor yet: GET /extended/v2/blocks and its siblings, GET /extended/v2/burn-blocks/*, 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.