Fix the four things that break a stranger's first ten minutes

[jaykomarraju]

A cold pass against the published product — docs.tx402.io, npm, PyPI — found the guardrails trustworthy and the front door not. Four issues, none in the SDK. All four are reproduced below and their fixes verified rather than reasoned about.

The quickstart's merchant step could not work on a fresh clone

Step 2 cloned the repo and ran the test merchant, calling it "a single command". It fails:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@x402/core'

The obvious repair makes it worse. npm install exits 0 and prints added 151 packages — and installs none of the workspace's dependencies, because the workspace layout lives in pnpm-workspace.yaml, which npm does not read, and package.json carries no workspaces field. The success message is the trap.

pnpm install is now an explicit step, with a caution naming npm's silent no-op, a corepack enable hint, and the reassurance that this applies only to running this repo's merchant — installing tx402 into your own project is an ordinary package install that works with any client.

The quickstart promised a key format both SDKs reject

Step 3 offered the solana-keygen JSON array "or its base58 form". Neither language accepts base58:

keypairToSolanaSigner expects a JSON array of 64 keypair bytes, as written by
`solana-keygen` — it could not be parsed as JSON

Wallets such as Phantom export base58, so a reader following the page hits a wall while holding a perfectly valid key. The claim is removed and replaced with a pointer to tools/b58-keypair.js — the dependency-free converter that already existed for this exact mismatch, and which takes the key from the environment rather than argv so it never reaches shell history or ps. Verified end to end with a real ed25519 keypair: base58 in, JSON array out, accepted by both SDKs.

Both TypeScript examples failed with the exact commands their README gave

They import the workspace tx402, which resolves through a compiled dist/ that a clone does not contain, so both die on ERR_MODULE_NOT_FOUND without a prior pnpm build. That step is now in the README with its reason — and with why the three Python examples need no equivalent: they import the source directly.

The documented Worker gateway could not boot

No such module "node:crypto"

and nodejs_compat appeared zero times in the published docs. tx402/gateway/worker reaches core/ledger, which imports node:crypto.

Both wrangler.jsonc examples now carry compatibility_flags: ["nodejs_compat"], plus the name, main and compatibility_date they were missing — so the block is one a reader can copy and deploy. A table records which entry point needs the flag, traced through the published bundle rather than assumed:

Import	Needs nodejs_compat
tx402	Yes
tx402/durable-object	Yes — durableObjectSpendStore reaches core/ledger
tx402/gateway/worker	Yes
tx402/gateway	No — the Node server reaches no Node built-in

That distinction is easy to get wrong, and the docs previously invited the wrong answer: the Durable Object class deliberately avoids node:crypto, but importing the module that exports it does not, so a Worker deploying the DO needs the flag too.

Verified against a real Workers runtime with the published tx402@0.2.0:

	Result
without the flag	wrangler warns: "node:crypto" wasn't found … enable the "nodejs_compat" flag
with the flag	clean bundle, Worker boots
data token → /v1/capabilities	200 {"result":{"atomicGlobalFreeze":false}}
bad token	401

Scope

Documentation only. No package, source or behaviour changes, so there is nothing to re-release. docs.tx402.io already serves these fixes.