Integrate deliberately.
Reconcile the result.
Testnet action routes, managed wallets, and failure handling.
Access and environment
These are managed-wallet demo routes, not a production API. The local operator validates Host and Origin and requires authorized POST access with JSON. Hosted access has its own gateway policy; availability of a public page does not grant operator access. The demo wallet is shared by the scene, not a private wallet assigned to each visitor.
Read GET /__demo/state for the scene and GET /__demo/health for runtime health. Health is not proof of a complete production deployment. Do not expose operator tokens or wallet keys in a browser build.
Collector actions
Send an authorized JSON POST /__demo/action. IDs below are examples and must be selected from fresh scene data.
{"action":"mint","collectionId":"COLLECTION_ID","amount":1}
{"action":"vault-buy","collectionId":"COLLECTION_ID","nftId":1}
{"action":"vault-swap","collectionId":"COLLECTION_ID","nftId":1,"sourceNftId":2}Check scene vaultAtomic and vaultRouterAddress before enabling vault actions. The runtime advertises atomic vault availability only after verifying its router; it does not fall back to the former multi-transaction vault path.
vault-buy uses existing FLOOR and acquires a shortfall with a 25 dUSD quote cap, then redeems one selected NFT. vault-swap deposits one owned same-collection NFT and redeems the selected target. Conversion must be open for the deposit. Neither redemption pays a primary mint fee.
Other supported actions include buy/sell for collection FLOOR, deposit/redeem for direct conversion, and swap-buy/swap-sell for demo tokens. Consult scripts/demo/runtime.mjs and scripts/demo/amounts.mjs for current identifiers, amount units, and limits.
Read the atomic transaction result
Vault success returns ok: true, atomic: true, target nftId, sourceNftId for swaps, the economic transaction hash, and refreshed state. Purchases report actual quoteSpent as a decimal dUSD string when the receipt event is decoded. A failure response includes ok: false, atomic: true, partial: false, failedStep, and writesBlocked. Check the body as well as the HTTP status.
failedStep is check, approval, or execute. Any NFT/FLOOR movements and the selected redemption share one economic transaction. If that transaction reverts, they all revert together. Preceding approvals can remain granted and gas can still be spent. An unknown receipt remains an unknown outcome even when partial is false: stop on writesBlocked and reconcile the journal before retrying.
If a write outcome is unknown, stop and reconcile the persisted journal and canonical receipts before retrying. Never delete the journal to make an uncertain action appear failed. See scripts/demo/vault-actions.mjs for the execution sequence.
Creator and bot routes
POST /__demo/creator/prepare accepts the guided form’s files and terms and produces a demo-hosted draft. POST /__demo/creator/launch submits the prepared draft through the managed test wallet. These are distinct from the canonical no-broadcast preparation CLI.
POST /__demo/bots controls the synthetic participants. For local operation, use node scripts/demo.mjs status|pause|resume|step and the appropriate network/state directory. Bots use seeded showcase collections; creator uploads are explored manually.