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.

Batch transaction lookups

GET /extended/v1/tx/multiple → GET /extended/v3/transactions/batch

Ids are supplied the same way — repeated (?tx_id=A&tx_id=B) or comma-separated (?tx_id=A,B), up to 20 — but the response differs in two ways that need code changes, not just a URL swap:

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.

Mempool

The mempool is now a resource with a summary, rather than a stats sub-route of transactions. v1 returned four parallel maps keyed by transaction type, so a question about one type meant joining four objects, and a question about the whole mempool was not answerable at all — percentiles cannot be averaged. v3 inverts the nesting: top-level metrics cover the whole mempool, with a by_type breakdown underneath.

Mempool field mapping

Each metric is still { p25, p50, p75, p95 }, null when a bucket is empty. The top-level count always equals the sum of the per-type counts. Versioned smart-contract transactions are counted as smart_contract, as in v1.

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

Stacking events

The /extended/v1/pox{2,3,4} routes read the pox-2, pox-3, and pox-4 event tables and have no pox-5 counterpart, so like the burnchain reward endpoints they serve historical data only. The pox-5 equivalent differs per route — two have a partial one, two have none — so there is no single replacement to point them all at.

The pool-delegation mapping is the closest to a like-for-like swap: a pox-4 pool aggregating delegators corresponds to a pox-5 signer with stakers.

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.

Search

v1 resolved one exact identifier to a single entity. v3 is a real search: the term moves from the path to a q query parameter, and it can be the beginning of an identifier as well as a complete one. Contract and asset names match anywhere in the name, so ?q=arkadiko finds the contracts and tokens named after it.

There is no pagination; narrow the term to surface something that did not appear. Terms have minimum lengths: 8 characters for hex, 6 for an address, 3 for a contract or asset name. Block heights have no minimum, and a term that fits none of these forms returns 400.

Faucets

All three are testnet-only. The request and response both change shape:

The amount is keyed by the asset it is denominated in — stx in µSTX, btc and sbtc in satoshis — so the response says which token was sent and in what units. txRaw is gone, and the BTC faucet's transaction id is now 0x-prefixed like the Stacks ones.

The size flags have no v3 equivalent. If you relied on stacking=true to get enough STX to stack, or need more than the fixed amount for testing, reach out on Discord to request a custom faucet transaction.

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

As of API 9.4.0, every /extended/v1 data endpoint is deprecated. The one route that is not is GET /extended, which reports the API's version and chain tip. It is service metadata rather than part of the versioned data API, so it has no v3 counterpart and does not need one.

These /extended/v2 routes are also current and have no v3 successor: 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.