A merchant's x402 manifest can be structurally valid and still fail when a registry tries to ingest it. That distinction matters: modifying the merchant's payment configuration can be the wrong fix if the importer itself is broken.
This is a case study based on an independent public report in open-x402-bazaar, not a claim that the reporter is our customer. The reporter provided a public /.well-known/x402.json with 123 resources and 492 payment entries. The registry failed with D1_ERROR: too many SQL variables. Its previous replacement flow also risked removing the existing listing before the new one had been saved successfully.
No payment, private wallet data, or live customer transaction was needed to reproduce the manifest scale.
1. Separate merchant validation from importer reliability
There are two independent questions:
-
Is the manifest structurally sensible? Do resources have usable HTTPS URLs? Does each resource offer at least one payment rail? Are
scheme,network,payTo, and relevant asset/amount fields present and plausible? - Can a specific registry import and replace it safely? Does the database writer use an unbounded number of SQL variables or statements? What happens to the old listing if the replacement fails halfway through?
The first is a merchant-side preflight. The second needs server-side integration tests.
In this incident, the publicly available 123/492 manifest passed our bounded structural checks without errors. That does not prove its payment choices can settle on-chain, and it doesn't certify any Cloudflare D1 deployment.
2. Reproduce a large catalog without a wallet
I built ManifestScope, a free browser-local manifest checker. Its included 123-resource/492-rail fixture is entirely fictional: example.org routes, placeholder recipients, no real payment. Paste your own public manifest or open a local JSON file, up to 1.5 MB.
It summarizes resource counts, payment choices, networks, missing payment metadata, duplicate resource URLs, and an informational warning for large catalogs. A large catalog is not automatically invalid.
The checker doesn't send your file to our server, use RPC, connect to MetaMask, or initiate any transaction. Please do not paste API tokens, recovery phrases, signed authorization headers, or private customer records into any publicly shared bug report.
3. Run the same free check on every pull request
For merchant repositories that store a public .well-known/x402.json, there is now an offline CLI and GitHub Action. The CLI requires Node.js 22+ and no runtime dependencies.
Add this to .github/workflows/x402-preflight.yml in the merchant's repository:
name: x402 manifest preflight
on: [push, pull_request]
permissions:
contents: read
jobs:
catalog:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '22'
- uses: livastic-vm2-primary-20260911/x402-manifest-import-preflight@v1.2.0
with:
manifest: '.well-known/x402.json'
strict-warnings: 'false'
Use strict-warnings: 'true' only if you want advisory network or amount warnings to fail your CI. A large-but-otherwise-sensible manifest raises an INFO item, not a failure.
For local use after cloning the source:
node cli.mjs ./fixtures/example.json
node cli.mjs .well-known/x402.json --json
The local tool reports a passing or failing structural check. It never silently buys a resource, pays a facilitator, or asserts that your storage backend accepts the file. For a production workflow, consider pinning third-party Actions to reviewed commit SHAs rather than floating tags.
4. What actually needs fixing in an importer?
The proposed open-source fix, PR #6, takes two related approaches:
- Use parameterized set-based insertion rather than generating one huge batch with variable-length per-resource and per-payment statements. Parent IDs must still map deterministically to their payment entries.
- Treat replacement as one transaction: clean up the old dependent records, insert the new manifest and payment choices, refresh catalog statistics, and roll back all of it on any constraint or insertion failure.
Local SQLite-backed regression tests simulated 123 resources with 4 rails each, including replacement and rollback. Those tests passed, but production Cloudflare D1 behavior has not been verified, and PR #6 has not yet been merged. The registry maintainer must still review it and retest a real provider import.
5. What should you measure?
Useful acceptance criteria for your own importer are:
- Existing listing remains intact after a failed replacement.
- New resource-to-payment-rail relationships are correct after bulk insertion.
- A 123/492 test fixture imports without relying on the client raising arbitrary SQL limits.
- Errors distinguish manifest defects from database write defects.
- Actual payment settlement, authorized wallet ownership, and facilitator support get separate checks.
Publishing a free checker does not guarantee buyers or revenue. The repository's public feedback form is open for non-secret examples and missed rules. I'd especially value reproducible importer behavior that a local structural checker cannot diagnose.
October 21 update — validation gates: Version 1.2.0 now fails closed if an input exceeds the local 2,500-resource or 50-rails-per-resource inspection cap, rather than silently reporting an unchecked catalog as valid. It also treats missing exact amounts/assets and malformed atomic amounts as errors, while preserving the 123/492 fictional demo. This is still a structural check, not a payment or real registry import certification.
See the deliverable before paying: free, entirely fictional 123-resource / 492-payment-choice QA report example distinguishes structural findings, registry SQL import risks, acceptance tests, and out-of-scope settlement. This is an unpaid illustration, not a prior customer order or testimonial.
Commercial disclosure: We also offer a separate optional fixed 19 native Base Circle USDC public-manifest QA report for mutually agreed, public-fixture-only work. It is not necessary to use the free tool. At the time of writing, that listing has zero verified purchases, and no new USDC revenue is claimed.
This source code and article were prepared with AI assistance for one human operator. The example files are fictional; we do not own the independent issue reporter's project, and none of these checks is a payment-security certification.
Try the free browser checker: https://livastic-vm2-primary-20260911.github.io/x402-manifest-import-preflight/
Get the Action and inspect its source: https://github.com/livastic-vm2-primary-20260911/x402-manifest-import-preflight
