docs: update stacks api reference and v3 migration guide for v9.7.1

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

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

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
+---
+
+<APIPage
+  document="./openapi/stacks-blockchain-api.json"
+  operations={[{ path: '/extended/v3/principals/{principal}/mining/rewards', method: 'get' }]}
+  hasHead={false}
+/>

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
+---
+
+<APIPage
+  document="./openapi/stacks-blockchain-api.json"
+  operations={[{ path: '/extended/v3/principals/{principal}/mining', method: 'get' }]}
+  hasHead={false}
+/>

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

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
 }

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
+---
+
+<APIPage
+  document="./openapi/stacks-blockchain-api.json"
+  operations={[{ path: '/extended/v3/bitcoin-blocks/{height_or_hash}/blocks', method: 'get' }]}
+  hasHead={false}
+/>

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
+---
+
+<APIPage
+  document="./openapi/stacks-blockchain-api.json"
+  operations={[{ path: '/extended/v3/bitcoin-blocks/{height_or_hash}', method: 'get' }]}
+  hasHead={false}
+/>

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
+---
+
+<APIPage
+  document="./openapi/stacks-blockchain-api.json"
+  operations={[{ path: '/extended/v3/bitcoin-blocks', method: 'get' }]}
+  hasHead={false}
+/>

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
+}

content/docs/en/apis/stacks-blockchain-api/reference/blocks/average-times.mdx

@@ -1,12 +1,12 @@
 ---
 title: Get average block times
 sidebarTitle: Average times
-description: Retrieves average block times.
+description: Retrieves average block times (in seconds).
 full: true
 ---
 
 <APIPage
   document="./openapi/stacks-blockchain-api.json"
   operations={[{ path: '/extended/v2/blocks/average-times', method: 'get' }]}
   hasHead={false}
-/>
+/>

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
+---
+
+<APIPage
+  document="./openapi/stacks-blockchain-api.json"
+  operations={[{ path: '/extended/v3/blocks/{height_or_hash}', method: 'get' }]}
+  hasHead={false}
+/>

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
+---
+
+<APIPage
+  document="./openapi/stacks-blockchain-api.json"
+  operations={[{ path: '/extended/v3/blocks', method: 'get' }]}
+  hasHead={false}
+/>

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",

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

content/docs/en/apis/stacks-blockchain-api/reference/mempool/transaction-fee-priorities.mdx

@@ -1,12 +1,12 @@
 ---
-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
 ---
 
 <APIPage
   document="./openapi/stacks-blockchain-api.json"
   operations={[{ path: '/extended/v2/mempool/fees', method: 'get' }]}
   hasHead={false}
-/>
+/>

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

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

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

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

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

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