[docs-agent] UTXO API: per-chain curl examples for BCH / LTC / DOGE#1302
Open
JackReacher0807 wants to merge 2 commits into
Open
[docs-agent] UTXO API: per-chain curl examples for BCH / LTC / DOGE#1302JackReacher0807 wants to merge 2 commits into
JackReacher0807 wants to merge 2 commits into
Conversation
Each UTXO chain page currently consumes the shared `src/openapi/utxo/utxo.yaml` spec, which defaults to bitcoin-mainnet and carries Bitcoin-specific examples (real BTC block hashes, real BTC txids, BTC bech32 addresses). On the Bitcoin Cash, Litecoin, and Dogecoin chain pages, that produces misleading defaults — users see BTC curl invocations under a non-BTC product header. Add three sibling OpenAPI specs that mirror the shared shape but populate every parameter and response example with chain-specific values derived from live mainnet calls: * `src/openapi/utxo-bitcoincash/utxo-bitcoincash.yaml` (servers: `bitcoincash-mainnet`, `bitcoincash-testnet`) * `src/openapi/utxo-litecoin/utxo-litecoin.yaml` (servers: `litecoin-mainnet`, `litecoin-testnet`) * `src/openapi/utxo-dogecoin/utxo-dogecoin.yaml` (servers: `dogecoin-mainnet`) Repoint the three sibling chain sections in `content/docs.yml` at their new `api-name`. Bitcoin section continues to use the existing `utxo.yaml` unchanged. Refs DOCS-83 Requested-by: @andra-catana
🔗 Preview Mode
|
🔍 Link CheckStatus: ⏭️ Skipped (no content changes) |
…s, surface broken endpoints Address review feedback from @andra-catana on PR #1302 covering the broader `utxo-api-endpoints/*` surface across BTC / BCH / LTC / DOGE: * `Send Transaction (GET)`: replace the `010000000001...` placeholder with the hex of a real already-confirmed transaction for each chain. Re-sending now responds with a meaningful Bitcoin-Core RPC error (`-27: transaction already in block chain` on BCH/LTC/DOGE, `-25: bad-txns-inputs-missingorspent` on BTC) instead of `-22: TX decode failed`, which demonstrates the request structure is correct. Description explains the example and instructs users to substitute their own signed hex. * `Send Transaction (POST)`: same realistic hex in the `text/plain` request body example, and a description callout noting the POST variant currently returns HTTP 400 `Parse error` at the Alchemy proxy regardless of body format. Points users at the working GET variant. Will follow up upstream so the proxy issue can be fixed. * `Get Tickers` / `Get Tickers List`: description callout on each endpoint noting they currently return HTTP 503 `Unable to complete request at this time` at the proxy. Schema/request shape kept for reference until the upstream service is restored. * Bitcoin `Get UTXO`: example address `bc1q0wd209cv5k9pd9mhk7nspacywcj038xxdhnt5u` is fully spent (balance 0), so "Try It" returned an empty array. Switched to `1FzWLkAahHooV3kzTgyx6qsswXJ6sCXkSR`, which has 5 stable confirmed UTXOs from blocks 745,856 – 766,367 and a steady residual balance. Response example refreshed to match. Validated via `pnpm run validate:rest` (all four UTXO specs valid) and live-tested `sendtx GET` plus `Get UTXO` against `alch-demo`. Refs DOCS-83 Requested-by: @andra-catana
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The Bitcoin Cash, Litecoin, and Dogecoin UTXO API method pages currently render bitcoin-mainnet defaults (real BTC block hashes, real BTC txids, BTC bech32 addresses) because all four UTXO chain sections in
docs.ymlreference the same sharedsrc/openapi/utxo/utxo.yaml. Example:This PR adds three sibling OpenAPI specs that mirror the shared shape but populate every parameter
exampleand responseexamplewith chain-specific values pulled from live*.g.alchemy.com/v2/docs-democalls (real block hashes for block 860730, real txids and addresses Andra supplied for each chain).Changes
src/openapi/utxo-bitcoincash/utxo-bitcoincash.yaml(servers:bitcoincash-mainnet,bitcoincash-testnet)src/openapi/utxo-litecoin/utxo-litecoin.yaml(servers:litecoin-mainnet,litecoin-testnet)src/openapi/utxo-dogecoin/utxo-dogecoin.yaml(servers:dogecoin-mainnet)content/docs.yml:api-name: utxo→api-name: utxo-bitcoincashapi-name: utxo→api-name: utxo-litecoinapi-name: utxo→api-name: utxo-dogecoinBitcoin section continues to use the existing
utxo.yamlunchanged. URLs are unaffected becauseflattened: truederives the URL segment from the section title (UTXO API Endpoints), not fromapi-name, so/docs/chains/<chain>/utxo-api-endpoints/utxo-api-endpoints/<method>remains stable across all 4 chains.Per-chain example values
block-index/{height}860730→000...e2dcd1d5c9860730→91ccb5...c93c9c03397a617ade19f8b04860730→56acd910...8582cd4d5592tx/{txid}0ddda32c...86f72d0ad9a5e3a3...5f545545bdd9010d...5e217482address/{addr}bitcoincash:qp3wjpa3tjlj042z2wv7hahsldgwhwy0rq9sywjpyyLer4HNAEfwYhBmGXcFP2Po1NpRUEiK8km2DH5yaieqoZN36fDVciNyRueRGvGLR3mr7Lbalancehistory.from150154560013183252241386474927Response examples (
Tx,AddressInfo,Block,Utxo,BalanceHistoryEntry) were captured live for each chain and inlined underresponses["200"].content."application/json".example.Validation
pnpm run validate:rest— all three new specs validate cleanly (each reports 1 warning, matching the pre-existing security-definition warning class on the originalutxo.yaml).pnpm run generate:rest— bundles each spec to its own dereferenced JSON undercontent/api-specs/alchemy/rest/utxo-{chain}.json(gitignored).pnpm run lint— clean for changed files; remaining warnings are pre-existing in unrelated files.Out of scope
utxo.yamlserver enum (still lists all 7 networks). Could be a follow-up if reviewers want Bitcoin's page to also drop non-BTC networks from its server picker.Linear
DOCS-83
Requested by
@andra-catana (via Slack thread)