[werner-stacks]

Description

The Stacks Blockchain API section rendered a static copy of the node RPC spec (Dec 2025) plus a hand-made Bitcoin Staking spec, so it didn't match the API Hiro ships. This points the section at the GitBook spec stacks-blockchain-api, which pulls Hiro's openapi.yaml from hirosystems/stacks-blockchain-api main and refreshes automatically. Hiro stays the source of truth.

Page changes

• Added: Burn Blocks, Faucets, Mempool, Proof of Transfer, Search, Tokens, Staking
• Kept (same slugs, now Hiro content): Transactions, Smart Contracts, Accounts, Info, Blocks, Models
• Removed: Mining, Signers, Atlas, Stacker DB, Fees (node RPC endpoints, still under Stacks Node RPC) and Bitcoin Staking (replaced by Staking); redirects added in .gitbook.yaml

[CLAassistant]

All committers have signed the CLA.

[cuevasm]

Nice, moving the section onto Hiro's spec will be good.

The current "Blockchain API" pages are really the Dec 2025 node RPC snapshot (Mining, Atlas, Stacker DB etc.), so this fixes the mislabel. I also checked Hiro's Staking tag against our old bitcoin-staking spec: it covers all 10 of our endpoints plus 5 new ones, and ours had already drifted. Good to retire it.

AI review with coaching below:

1. Bitcoin Staking page identity. Hiro uses the Staking tag but never declares it in the top-level tags, so the page will render as plain "Staking" with no description, at /staking instead of /bitcoin-staking. The redirect currently sends the old URL to the Blockchain API README, not the new page. Since .gitbook.yaml can only target files, can we add a site-level redirect in GitBook to /reference/api/stacks-blockchain-api/staking? Longer term, a small upstream PR to declare the tag with a description would fix the title. With Bond 2 coming up, partner materials link to that URL, so I'd like this one sorted before merge.

2. Testnet server. Our old spec listed api.private-1.hiro.so as the Bitcoin Staking testnet. Hiro's only lists mainnet. Partners use that for rehearsals, so let's call it out somewhere.

3. Empty tags. Hiro declares Fees, Names, and Stacking Rewards with zero operations. Can you check the preview? If GitBook renders an empty Fees page, it'll sit on the old slug and the fees redirect won't fire.

4. models: true. Hiro's spec has no components.schemas (everything is inline), so the Models page will be empty. I'd flip it to false.

5. Validation warnings. GitBook logged ~2.8k warnings processing the spec, mostly the type: 'null' inside anyOf pattern in a 3.0.3 file. Mesh API has the same class and renders fine, but please eyeball a few endpoints with nullable fields in the preview.

6. Source URL. The GitBook spec pulls from hirosystems/stacks-blockchain-api/main, but the README links to stx-labs/.../master. Same content today, but let's point it at the canonical stx-labs one.

7. Cleanup after merge. There's a stacks-node-rpc-4-0-4-test spec in the org pointing at Hiro's file. It looks like a leftover. Once this is live, let's delete that and retire stacks-blockchain-api-dereferenced and bitcoin-staking.

Happy to approve once 1, 3 and 4 are addressed and the preview looks clean. 2, 6 and 7 can be follow-ups if easier.

[werner-stacks]

@cuevasm thanks for the feedback I addressed 1, 3 and 4 in the latest commit.

Preview. There's no GitBook preview on PRs here, so I rendered the computed page list from the stacks-blockchain-api spec through GitBook's API. Generated pages: Accounts, Blocks, Burn Blocks, Faucets, Info, Search, Smart Contracts, Tokens, Transactions, Mempool, Proof Of Transfer, Models. The new Bitcoin Staking page (below) is in GitBook CR #49 for a visual check.

1. Bitcoin Staking. Worse than "plain Staking": GitBook only builds pages for tags declared in tags, so Hiro's undeclared Staking tag produced no page at all. Fixed without a site redirect: api/stacks-blockchain-api/bitcoin-staking.md is now a regular page at the same URL and title, with one openapi-operation block per staking endpoint (all 15), all reading from Hiro's spec. I removed the bitcoin-staking redirect, since the URL resolves again. Trade-off: a 16th staking endpoint needs a new block until Hiro declares the tag. The upstream PR to declare it is a follow-up.

3. Empty tags. Confirmed in the computed list: Fees, Names and Stacking Rewards produce no pages, so the fees redirect fires.

4. Models. Hiro's components.schemas is empty, so I set models: false. There's no Models page now; models now redirects to the section README.

2, 6 and 7 as follow-ups. One more for later: GitBook title-cases the tag as "Proof Of Transfer".