From be2db538092b5018b8f94346777fe3bed6587951 Mon Sep 17 00:00:00 2001
From: Rafa Cardenas <253999660+rafa-stacks@users.noreply.github.com>
Date: Tue, 27 Oct 2026 10:10:29 -0600
Subject: [PATCH] docs: update stacks api reference and v3 migration guide for
v9.7.1
---
.../accounts/get-principal-balance-ft.mdx | 2 +-
.../accounts/get-principal-balances-nft.mdx | 2 +-
.../accounts/get-principal-mining-rewards.mdx | 12 +
.../accounts/get-principal-mining-summary.mdx | 12 +
.../accounts/get-principal-nonces.mdx | 2 +-
.../reference/accounts/meta.json | 4 +-
.../get-bitcoin-block-stacks-blocks.mdx | 12 +
.../bitcoin-blocks/get-bitcoin-block.mdx | 12 +
.../bitcoin-blocks/get-bitcoin-blocks.mdx | 12 +
.../reference/bitcoin-blocks/meta.json | 5 +
.../reference/blocks/average-times.mdx | 4 +-
.../reference/blocks/get-block.mdx | 12 -
.../blocks/get-blocks-by-burn-block.mdx | 12 -
.../reference/blocks/get-blocks.mdx | 12 -
.../reference/blocks/get-stacks-block.mdx | 12 +
.../reference/blocks/get-stacks-blocks.mdx | 12 +
.../reference/blocks/meta.json | 5 +-
.../reference/burn-blocks/get-burn-block.mdx | 12 -
.../reference/burn-blocks/get-burn-blocks.mdx | 12 -
.../reference/burn-blocks/meta.json | 5 -
.../reference/info/status.mdx | 4 +-
.../mempool/transaction-fee-priorities.mdx | 6 +-
.../reference/smart-contracts/status.mdx | 2 +-
.../reference/staking/get-bond.mdx | 2 +-
.../reference/staking/get-cycle-signers.mdx | 2 +-
.../staking/get-principal-staking-summary.mdx | 2 +-
.../staking/get-staking-signer-stakers.mdx | 2 +-
.../reference/staking/get-staking-signers.mdx | 2 +-
.../v1-to-v3-migration.mdx | 206 ++++++++++++++----
29 files changed, 278 insertions(+), 123 deletions(-)
create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-mining-rewards.mdx
create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-mining-summary.mdx
create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/get-bitcoin-block-stacks-blocks.mdx
create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/get-bitcoin-block.mdx
create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/get-bitcoin-blocks.mdx
create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/meta.json
delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-block.mdx
delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-blocks-by-burn-block.mdx
delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-blocks.mdx
create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-stacks-block.mdx
create mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-stacks-blocks.mdx
delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/burn-blocks/get-burn-block.mdx
delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/burn-blocks/get-burn-blocks.mdx
delete mode 100644 content/docs/en/apis/stacks-blockchain-api/reference/burn-blocks/meta.json
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-balance-ft.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-balance-ft.mdx
index af0df2ac1..0b2faaf2c 100644
--- a/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-balance-ft.mdx
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-balance-ft.mdx
@@ -1,7 +1,7 @@
---
title: Get principal FT balance
sidebarTitle: Principal FT balance
-description: Get a principal's balance of a single fungible token.
+description: "Get a principal's balance of a single fungible token. Returns a zero balance if the principal does not currently hold the token."
full: true
---
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-balances-nft.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-balances-nft.mdx
index 8c76e38ca..6a8cc6e24 100644
--- a/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-balances-nft.mdx
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-balances-nft.mdx
@@ -1,7 +1,7 @@
---
title: Get principal NFT balances
sidebarTitle: Principal NFT balances
-description: Get the non-fungible token instances currently owned by a principal, ordered by asset identifier and value.
+description: "Get the non-fungible token instances currently owned by a principal, ordered by asset identifier and value. Optionally filtered to a single asset class via `asset_identifier`."
full: true
---
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-mining-rewards.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-mining-rewards.mdx
new file mode 100644
index 000000000..3ab501171
--- /dev/null
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-mining-rewards.mdx
@@ -0,0 +1,12 @@
+---
+title: Get principal mining rewards
+sidebarTitle: Principal mining rewards
+description: "Returns the matured miner rewards credited to a principal, most recent first. Miner rewards are credited to the recipient's STX balance when they mature, without a transaction or STX event, so they don't appear in the principal's transactions or transfers. Each reward reports the `block` it matured (and was credited) in and the `source_block` whose reward matured; a parent-miner share of fees reports the same `source_block` as the miner reward it was paid alongside. Only rewards on the canonical chain are listed; zero-value rewards are left out."
+full: true
+---
+
+
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-mining-summary.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-mining-summary.mdx
new file mode 100644
index 000000000..12a85a38f
--- /dev/null
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-mining-summary.mdx
@@ -0,0 +1,12 @@
+---
+title: Get principal mining summary
+sidebarTitle: Principal mining summary
+description: "A one-call overview of a principal's mining: its lifetime matured miner rewards (coinbase and fees, in µSTX), counting only rewards on the canonical chain. The individual rewards are paginated at `/principals/:principal/mining/rewards`."
+full: true
+---
+
+
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-nonces.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-nonces.mdx
index 9e3defa75..8224d8a2b 100644
--- a/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-nonces.mdx
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/accounts/get-principal-nonces.mdx
@@ -1,7 +1,7 @@
---
title: Get principal nonces
sidebarTitle: Principal nonces
-description: "Get a Stacks account's latest nonce state by inspecting its confirmed (anchored + microblock) transactions and the mempool, including the nonce to use for its next transaction."
+description: "Get a Stacks account's latest nonce state by inspecting its confirmed transactions and the mempool, including the nonce to use for its next transaction. Only standard principals have nonces; contract principals are not valid."
full: true
---
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/accounts/meta.json b/content/docs/en/apis/stacks-blockchain-api/reference/accounts/meta.json
index bf6cdd511..b25d06910 100644
--- a/content/docs/en/apis/stacks-blockchain-api/reference/accounts/meta.json
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/accounts/meta.json
@@ -5,7 +5,9 @@
"get-principal-balances-ft",
"get-principal-balance-ft",
"get-principal-balances-nft",
- "get-principal-nonces"
+ "get-principal-nonces",
+ "get-principal-mining-summary",
+ "get-principal-mining-rewards"
],
"defaultOpen": false
}
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/get-bitcoin-block-stacks-blocks.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/get-bitcoin-block-stacks-blocks.mdx
new file mode 100644
index 000000000..64c0903ab
--- /dev/null
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/get-bitcoin-block-stacks-blocks.mdx
@@ -0,0 +1,12 @@
+---
+title: Get Bitcoin block Stacks blocks
+sidebarTitle: Bitcoin block Stacks blocks
+description: Retrieves the summaries of the canonical Stacks blocks confirmed by a single canonical Bitcoin block, newest first.
+full: true
+---
+
+
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/get-bitcoin-block.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/get-bitcoin-block.mdx
new file mode 100644
index 000000000..3c0b0deb8
--- /dev/null
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/get-bitcoin-block.mdx
@@ -0,0 +1,12 @@
+---
+title: Get Bitcoin block
+sidebarTitle: Bitcoin block
+description: "Retrieves a single canonical Bitcoin block, by height, hash, or `latest`, with its time (see the Bitcoin blocks list). A height above the Bitcoin tip returns the future block with no hash and its projected time."
+full: true
+---
+
+
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/get-bitcoin-blocks.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/get-bitcoin-blocks.mdx
new file mode 100644
index 000000000..274615c3b
--- /dev/null
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/get-bitcoin-blocks.mdx
@@ -0,0 +1,12 @@
+---
+title: Get Bitcoin blocks
+sidebarTitle: Bitcoin blocks
+description: Retrieves canonical Bitcoin blocks, newest first. Each block carries its header time once the API has learned it from a Stacks block anchored to it, an interpolated time for a past block no Stacks block anchored to, and a projected time for the newest blocks no Stacks block has anchored to yet.
+full: true
+---
+
+
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/meta.json b/content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/meta.json
new file mode 100644
index 000000000..392e720a0
--- /dev/null
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/bitcoin-blocks/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Bitcoin Blocks",
+ "pages": ["get-bitcoin-blocks", "get-bitcoin-block", "get-bitcoin-block-stacks-blocks"],
+ "defaultOpen": false
+}
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/blocks/average-times.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/blocks/average-times.mdx
index 38a77a175..ca9fc044a 100644
--- a/content/docs/en/apis/stacks-blockchain-api/reference/blocks/average-times.mdx
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/blocks/average-times.mdx
@@ -1,7 +1,7 @@
---
title: Get average block times
sidebarTitle: Average times
-description: Retrieves average block times.
+description: Retrieves average block times (in seconds).
full: true
---
@@ -9,4 +9,4 @@ full: true
document="./openapi/stacks-blockchain-api.json"
operations={[{ path: '/extended/v2/blocks/average-times', method: 'get' }]}
hasHead={false}
-/>
\ No newline at end of file
+/>
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-block.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-block.mdx
deleted file mode 100644
index e6be690de..000000000
--- a/content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-block.mdx
+++ /dev/null
@@ -1,12 +0,0 @@
----
-title: Get block
-sidebarTitle: Block
-description: Retrieves a single block.
-full: true
----
-
-
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-blocks-by-burn-block.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-blocks-by-burn-block.mdx
deleted file mode 100644
index d1083c3db..000000000
--- a/content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-blocks-by-burn-block.mdx
+++ /dev/null
@@ -1,12 +0,0 @@
----
-title: Get blocks by burn block
-sidebarTitle: Blocks by burn block
-description: Retrieves a list of blocks confirmed by a specific burn block.
-full: true
----
-
-
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-blocks.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-blocks.mdx
deleted file mode 100644
index 3e2f0a54d..000000000
--- a/content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-blocks.mdx
+++ /dev/null
@@ -1,12 +0,0 @@
----
-title: Get blocks
-sidebarTitle: Blocks
-description: Retrieves a list of recently mined blocks.
-full: true
----
-
-
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-stacks-block.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-stacks-block.mdx
new file mode 100644
index 000000000..48cbf995e
--- /dev/null
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-stacks-block.mdx
@@ -0,0 +1,12 @@
+---
+title: Get block
+sidebarTitle: Block
+description: "Retrieves a single canonical Stacks block with its details, by height, block hash, index block hash, or `latest`."
+full: true
+---
+
+
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-stacks-blocks.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-stacks-blocks.mdx
new file mode 100644
index 000000000..da10e869d
--- /dev/null
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/blocks/get-stacks-blocks.mdx
@@ -0,0 +1,12 @@
+---
+title: Get blocks
+sidebarTitle: Blocks
+description: Retrieves the summaries of canonical Stacks blocks, newest first.
+full: true
+---
+
+
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/blocks/meta.json b/content/docs/en/apis/stacks-blockchain-api/reference/blocks/meta.json
index 46c759db2..849ca45bc 100644
--- a/content/docs/en/apis/stacks-blockchain-api/reference/blocks/meta.json
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/blocks/meta.json
@@ -1,9 +1,8 @@
{
"title": "Blocks",
"pages": [
- "get-block",
- "get-blocks",
- "get-blocks-by-burn-block",
+ "get-stacks-blocks",
+ "get-stacks-block",
"average-times",
"get-block-by-block-time",
"get-signer-signatures-for-block",
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/burn-blocks/get-burn-block.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/burn-blocks/get-burn-block.mdx
deleted file mode 100644
index b000df29a..000000000
--- a/content/docs/en/apis/stacks-blockchain-api/reference/burn-blocks/get-burn-block.mdx
+++ /dev/null
@@ -1,12 +0,0 @@
----
-title: Get burn block
-sidebarTitle: Burn block
-description: Retrieves a single burn block.
-full: true
----
-
-
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/burn-blocks/get-burn-blocks.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/burn-blocks/get-burn-blocks.mdx
deleted file mode 100644
index 3e78c83f0..000000000
--- a/content/docs/en/apis/stacks-blockchain-api/reference/burn-blocks/get-burn-blocks.mdx
+++ /dev/null
@@ -1,12 +0,0 @@
----
-title: Get burn blocks
-sidebarTitle: Burn blocks
-description: Retrieves a list of recent burn blocks.
-full: true
----
-
-
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/burn-blocks/meta.json b/content/docs/en/apis/stacks-blockchain-api/reference/burn-blocks/meta.json
deleted file mode 100644
index 6b753d1be..000000000
--- a/content/docs/en/apis/stacks-blockchain-api/reference/burn-blocks/meta.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
- "title": "Burn Blocks",
- "pages": ["get-burn-blocks", "get-burn-block"],
- "defaultOpen": false
-}
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/info/status.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/info/status.mdx
index e6992fdc5..6e26470b5 100644
--- a/content/docs/en/apis/stacks-blockchain-api/reference/info/status.mdx
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/info/status.mdx
@@ -1,7 +1,7 @@
---
-title: Get API status
+title: API status
sidebarTitle: API status
-description: Retrieves the running status of the Stacks Blockchain API.
+description: Retrieves the running status of the Stacks Blockchain API, including the server version and current chain tip information.
full: true
---
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/mempool/transaction-fee-priorities.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/mempool/transaction-fee-priorities.mdx
index 819f22e26..7847ac5db 100644
--- a/content/docs/en/apis/stacks-blockchain-api/reference/mempool/transaction-fee-priorities.mdx
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/mempool/transaction-fee-priorities.mdx
@@ -1,7 +1,7 @@
---
-title: Get transaction fee priorities
+title: Get mempool transaction fee priorities
sidebarTitle: Transaction fee priorities
-description: Retrieves estimated fee priorities (in micro-STX) for all transactions that are currently in the mempool. Also returns priorities separated by transaction type.
+description: Returns estimated fee priorities (in micro-STX) for all transactions that are currently in the mempool. Also returns priorities separated by transaction type.
full: true
---
@@ -9,4 +9,4 @@ full: true
document="./openapi/stacks-blockchain-api.json"
operations={[{ path: '/extended/v2/mempool/fees', method: 'get' }]}
hasHead={false}
-/>
\ No newline at end of file
+/>
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/status.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/status.mdx
index a764a517d..8c0f82f39 100644
--- a/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/status.mdx
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/smart-contracts/status.mdx
@@ -1,5 +1,5 @@
---
-title: Get contracts status
+title: Get smart contracts status
sidebarTitle: Contracts status
description: Retrieves the deployment status of multiple smart contracts.
full: true
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-bond.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-bond.mdx
index 087a3cee5..41d50c487 100644
--- a/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-bond.mdx
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-bond.mdx
@@ -1,7 +1,7 @@
---
title: Get bond
sidebarTitle: Bond
-description: Get bond
+description: "Get a bond. A bond that has not been set up yet but still can be (its activation height is ahead of the chain tip) is returned with a `projected` status and only the schedule pox-5 will assign it, which follows from its index."
full: true
---
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-cycle-signers.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-cycle-signers.mdx
index 7a3bae0f0..3d2b8cf3f 100644
--- a/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-cycle-signers.mdx
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-cycle-signers.mdx
@@ -1,7 +1,7 @@
---
title: Get cycle signers
sidebarTitle: Cycle signers
-description: "Get the signer set of a PoX cycle, including each signer's weight, staked amount, and the signer manager contracts whose registered signing key (via `register-signer`) was this key when the cycle's reward set was calculated. Each manager also lists its live `grant-signer-key` authorizations, and keys registered after the reward set was calculated are surfaced as pending updates that take effect next cycle."
+description: "Get the signer set of a PoX cycle, including each signer's weight, staked amount, and the signer manager contracts whose registered signing key was this key when the cycle's reward set was calculated."
full: true
---
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-principal-staking-summary.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-principal-staking-summary.mdx
index 11a3f2a54..cfd5a4b7c 100644
--- a/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-principal-staking-summary.mdx
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-principal-staking-summary.mdx
@@ -1,7 +1,7 @@
---
title: Get principal staking summary
sidebarTitle: Principal staking summary
-description: "A one-call overview of a principal's staking: its pox-5 STX-staking position (locked STX and its sBTC rewards) plus aggregate totals across all of its bond positions."
+description: "A one-call overview of a principal's staking: its pox-5 STX-staking position (locked STX and its sBTC rewards) plus aggregate totals across all of its bond positions. The per-bond breakdown is paginated at `/principals/:principal/staking/bonds`."
full: true
---
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-staking-signer-stakers.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-staking-signer-stakers.mdx
index 5f9058698..aa505cebf 100644
--- a/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-staking-signer-stakers.mdx
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-staking-signer-stakers.mdx
@@ -1,7 +1,7 @@
---
title: Get staking signer stakers
sidebarTitle: Staking signer stakers
-description: List the stakers that belong to a pox-5 signer, across both direct STX staking and BTC/sBTC bond staking.
+description: List the stakers that belong to a pox-5 signer, across both direct STX staking and BTC/sBTC bond staking. Each entry indicates which staking type(s) the staker participates in under this signer.
full: true
---
diff --git a/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-staking-signers.mdx b/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-staking-signers.mdx
index 59b358d0f..04ee055d8 100644
--- a/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-staking-signers.mdx
+++ b/content/docs/en/apis/stacks-blockchain-api/reference/staking/get-staking-signers.mdx
@@ -1,7 +1,7 @@
---
title: Get staking signers
sidebarTitle: Staking signers
-description: Get the registered pox-5 staking signers and their current signing keys.
+description: "Get the all-time registry of pox-5 staking signers: every signer principal that has ever registered a signer key, with its most recently registered key. Registrants are never removed from this registry, even if they are no longer part of the current cycle's signer set."
full: true
---
diff --git a/content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx b/content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx
index af68305b8..a93ec3e9e 100644
--- a/content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx
+++ b/content/docs/en/apis/stacks-blockchain-api/v1-to-v3-migration.mdx
@@ -64,10 +64,18 @@ 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
+### Every timestamp has an ISO twin
-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.
+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.
:::callout
type: warn
@@ -86,8 +94,10 @@ v3 equivalent ships, and filter client-side where you can.
| --- | --- |
| `GET /extended/v1/tx` | `GET /extended/v3/transactions` |
| `GET /extended/v1/tx/{tx_id}` | `GET /extended/v3/transactions/{tx_id}` |
+| `GET /extended/v1/tx/multiple` | `GET /extended/v3/transactions/batch` |
| `GET /extended/v1/tx/{tx_id}/raw` | Stacks node RPC `GET /v3/transaction/{tx_id}` |
| `GET /extended/v1/tx/mempool` | `GET /extended/v3/mempool/transactions` |
+| `GET /extended/v1/tx/mempool/stats` | `GET /extended/v3/mempool` |
| `GET /extended/v1/tx/block/{block_hash}` | `GET /extended/v3/blocks/{height_or_hash}/transactions` |
| `GET /extended/v1/tx/block_height/{height}` | `GET /extended/v3/blocks/{height_or_hash}/transactions` |
| `GET /extended/v1/tx/events` | No direct replacement — see [Endpoints without a v3 replacement](#endpoints-without-a-v3-replacement) |
@@ -95,6 +105,15 @@ v3 equivalent ships, and filter client-side where you can.
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
| v1 field | v3 field |
@@ -114,8 +133,9 @@ block height, a block hash, or the literal `latest`.
| `parent_block_hash` | `parent_block.hash` (single-transaction endpoint only) |
| `burn_block_height` | `bitcoin_block.height` |
| `burn_block_time` | `bitcoin_block.time` |
-| `block_time_iso` | Removed — derive from `block.time` |
-| `burn_block_time_iso` | Removed — derive from `bitcoin_block.time` |
+| `block_time_iso` | `block.time_iso` |
+| `burn_block_time_iso` | `bitcoin_block.time_iso` |
+| `event_count` | `event_count` (in summaries as well as the single-transaction endpoint) |
| `execution_cost_*` | `execution_cost.*` — e.g. `execution_cost_runtime` becomes `execution_cost.runtime` |
| `contract_call.function_args` | Same path, only with `?include=function_args` |
| `smart_contract.source_code` | Same path, only with `?include=source_code` |
@@ -187,7 +207,7 @@ class, not a list.
| `total_sent` | Removed |
| `total_received` | Removed |
| `total_fees_sent` | Removed |
-| `total_miner_rewards_received` | Removed |
+| `total_miner_rewards_received` | Moved to `GET /extended/v3/principals/{principal}/mining` → `rewards.total` |
| `token_offering_locked` | Removed |
:::callout
@@ -201,6 +221,21 @@ locked STX is excluded. If you were subtracting `locked` yourself, stop.
v1 accepted `until_block` and `unanchored` 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
@@ -253,20 +288,77 @@ 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.
+| Deprecated v1 endpoint | v3 replacement |
+| --- | --- |
+| `GET /extended/v1/block` | `GET /extended/v3/blocks` |
+| `GET /extended/v1/block/{hash}` | `GET /extended/v3/blocks/{height_or_hash}` |
+| `GET /extended/v1/block/by_height/{height}` | `GET /extended/v3/blocks/{height_or_hash}` |
+| `GET /extended/v1/block/by_burn_block_height/{burn_block_height}` | `GET /extended/v3/bitcoin-blocks/{height_or_hash}/blocks` |
+| `GET /extended/v1/block/by_burn_block_hash/{burn_block_hash}` | `GET /extended/v3/bitcoin-blocks/{height_or_hash}/blocks` |
-| Deprecated v1 endpoint | Replacement |
+`{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](#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".
+
+| v1 / v2 field | v3 field |
| --- | --- |
-| `GET /extended/v1/block` | `GET /extended/v2/blocks` |
-| `GET /extended/v1/block/{hash}` | `GET /extended/v2/blocks/{height_or_hash}` |
-| `GET /extended/v1/block/by_height/{height}` | `GET /extended/v2/blocks/{height_or_hash}` |
-| `GET /extended/v1/block/by_burn_block_height/{burn_block_height}` | `GET /extended/v2/burn-blocks/{height_or_hash}/blocks` |
-| `GET /extended/v1/block/by_burn_block_hash/{burn_block_hash}` | `GET /extended/v2/burn-blocks/{height_or_hash}/blocks` |
+| `height` | `height` |
+| `hash` | `hash` |
+| `index_block_hash` | `index_hash` |
+| `block_time` | `time` |
+| `block_time_iso` | `time_iso` |
+| `tenure_height` | `tenure_height` (`null` for a Nakamoto block indexed before tenure heights were recorded) |
+| `tx_count` (v2) / `txs` (v1) | `tx_count` — fetch the transactions from `GET /extended/v3/blocks/{height_or_hash}/transactions` |
+| `burn_block_hash` | `bitcoin_block.hash` |
+| `burn_block_height` | `bitcoin_block.height` |
+| `burn_block_time` | `bitcoin_block.time` (detail only) |
+| `burn_block_time_iso` | `bitcoin_block.time_iso` (detail only) |
+| `parent_block_hash` | `parent_block.hash` (detail only) |
+| `parent_index_block_hash` | `parent_block.index_hash` (detail only) |
+| `execution_cost_*` | `execution_cost.*` (detail only) |
+| `miner_txid` | Removed |
+| `canonical` | Removed — v3 only returns canonical blocks |
+| `parent_microblock_*`, `microblocks_*`, `microblock_tx_count` | Removed — microblocks no longer exist |
+| — | `size` (new, detail only: total transaction bytes; `null` for blocks indexed before sizes were recorded) |
+
+### Bitcoin blocks
-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`.
+v3 renames "burn blocks" to **Bitcoin blocks**:
+
+| Deprecated v2 endpoint | v3 replacement |
+| --- | --- |
+| `GET /extended/v2/burn-blocks` | `GET /extended/v3/bitcoin-blocks` |
+| `GET /extended/v2/burn-blocks/{height_or_hash}` | `GET /extended/v3/bitcoin-blocks/{height_or_hash}` |
+| `GET /extended/v2/burn-blocks/{height_or_hash}/blocks` | `GET /extended/v3/bitcoin-blocks/{height_or_hash}/blocks` |
+
+| v2 field | v3 field |
+| --- | --- |
+| `burn_block_height` | `height` |
+| `burn_block_hash` | `hash` (`null` for a future block) |
+| `burn_block_time` | `time` |
+| `burn_block_time_iso` | `time_iso` |
+| `stacks_blocks` | `stacks_block_count` — list them with `GET /extended/v3/bitcoin-blocks/{height_or_hash}/blocks` |
+| `total_tx_count` | `tx_count` |
+| `avg_block_time` | Removed — use `GET /extended/v2/blocks/average-times` |
+| — | `projected_time`, `projected_time_iso` (new) |
+
+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
@@ -333,6 +425,44 @@ 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.
+
+| Deprecated v1 endpoint | Replacement |
+| --- | --- |
+| `GET /extended/v1/pox4/events` | None — there is no global pox-5 event feed |
+| `GET /extended/v1/pox4/tx/{tx_id}` | None — v3 transaction events do not carry decoded pox operations |
+| `GET /extended/v1/pox4/stacker/{principal}` | `GET /extended/v3/principals/{principal}/staking` for the current pox-5 position (no event history) |
+| `GET /extended/v1/pox4/{pool_principal}/delegations` | `GET /extended/v3/staking/signers/{principal}/stakers` |
+
+The same deprecation applies under the `pox2` and `pox3` prefixes.
+
+## Search
+
+| Deprecated v1 endpoint | v3 replacement |
+| --- | --- |
+| `GET /extended/v1/search/{id}` | `GET /extended/v3/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
+
+| Deprecated v1 endpoint | v3 replacement |
+| --- | --- |
+| `POST /extended/v1/faucets/stx` | `POST /extended/v3/faucets/stx` |
+| `POST /extended/v1/faucets/btc` | `POST /extended/v3/faucets/btc` |
+| `POST /extended/v1/faucets/sbtc` | `POST /extended/v3/faucets/sbtc` |
+
+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
| Deprecated v1 endpoint | Replacement |
@@ -519,6 +649,8 @@ These are deprecated with no successor. Plan around them rather than swapping a
| `GET /extended/v1/microblock/unanchored/txs` | Same. |
| `GET /extended/v1/tokens/nft/mints` | Mint events for an asset class. Retired rather than migrated — the endpoint serves negligible traffic. A single instance's mint is the oldest entry in `GET /extended/v3/tokens/nft/{asset_identifier}/{value}/history`, but there is no collection-wide mint feed. |
| `GET /extended/v1/faucets/btc/{address}` | Testnet-only BTC balance helper. No replacement. |
+| `GET /extended/v1/pox4/events` | Historical pox-4-and-earlier event feed. No pox-5 equivalent. |
+| `GET /extended/v1/pox4/tx/{tx_id}` | Historical pox-4-and-earlier events for one transaction. v3 transaction events do not decode pox operations. |
## Also deprecated: v2 endpoints
@@ -532,32 +664,30 @@ migrated from v1 to v2, these are your next hop.
| `GET /extended/v2/addresses/{principal}/balances/stx` | `GET /extended/v3/principals/{principal}/balances/stx` |
| `GET /extended/v2/addresses/{principal}/balances/ft` | `GET /extended/v3/principals/{principal}/balances/ft` |
| `GET /extended/v2/addresses/{principal}/balances/ft/{token}` | `GET /extended/v3/principals/{principal}/balances/ft/{asset_identifier}` |
+| `GET /extended/v2/blocks` | `GET /extended/v3/blocks` |
+| `GET /extended/v2/blocks/{height_or_hash}` | `GET /extended/v3/blocks/{height_or_hash}` |
| `GET /extended/v2/blocks/{height_or_hash}/transactions` | `GET /extended/v3/blocks/{height_or_hash}/transactions` |
+| `GET /extended/v2/burn-blocks` | `GET /extended/v3/bitcoin-blocks` |
+| `GET /extended/v2/burn-blocks/{height_or_hash}` | `GET /extended/v3/bitcoin-blocks/{height_or_hash}` |
+| `GET /extended/v2/burn-blocks/{height_or_hash}/blocks` | `GET /extended/v3/bitcoin-blocks/{height_or_hash}/blocks` |
+
+See [Blocks](#blocks) for the block and Bitcoin block field mappings.
+
+:::callout
+type: info
+### The v2 block routes outlive the sunset
+The six v2 block and burn block routes above carry the deprecation `Warning` header but are
+exempt from the sunset: they keep serving after the other deprecated endpoints start returning
+`410 Gone`. Migrate them anyway, since new block fields only land in v3.
+:::
## 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:
+Every `/extended/v1` route is now deprecated except the API status endpoint, `GET /extended`.
-| Area | Endpoint |
-| --- | --- |
-| Transactions | `GET /extended/v1/tx/multiple` |
-| Transactions | `GET /extended/v1/tx/mempool/stats` |
-| Stacking | `GET /extended/v1/pox4/events` |
-| Stacking | `GET /extended/v1/pox4/tx/{tx_id}` |
-| Stacking | `GET /extended/v1/pox4/stacker/{principal}` |
-| Stacking | `GET /extended/v1/pox4/{pool_principal}/delegations` |
-| Search | `GET /extended/v1/search/{id}` |
-| Faucets | `POST /extended/v1/faucets/stx` |
-| Faucets | `POST /extended/v1/faucets/btc` |
-| Faucets | `POST /extended/v1/faucets/sbtc` |
-| Status | `GET /extended` |
-
-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/*`,
+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](#stacking-rewards).