The committed @x402/paywall bundle on main was last generated against an
older viem than the lockfile currently pins. pnpm install --frozen-lockfile
resolves viem 2.47.12 (via #2013), but the bundled src/evm/gen/template.ts
(and its Python + Go siblings) were built against an earlier resolution
that pre-dated chain definitions for Mezo, MegaETH, Stable, Radius (each
with a testnet variant), and 33 others. EvmPaywall.tsx throws
"Unsupported chain ID" at init for any eip155:<id> whose chain isn't in
the bundled viem/chains.
This PR:
1. Regenerates all nine auto-generated template files (TypeScript,
Python, and Go for EVM/SVM/AVM) against the current lockfile. No
source changes on any runtime path.
2. Teaches build:paywall to emit output matching the repo's formatters
(prettier / ruff), so generated files stay clean under pnpm run
format + uvx ruff format.
3. Adds a PR-time drift check
(.github/workflows/check_paywall_template.yml) so a future lockfile
or @x402/evm change that invalidates the bundle fails loudly
instead of shipping silently.
Scope is limited to @x402/paywall because it is the only package in this
repo that bakes viem chain definitions into a built artifact.
Verified on a fork-internal test PR running on ubuntu-latest
(Node 24, pnpm 10.7.0): check_format, check_lint, check_go, check_python,
check_package_lock, and the new check_paywall_template drift check all
pass. Additional local evidence:
- Chain-presence in regenerated bundle: Mezo 31612/31611, MegaETH
4326/6343, Stable 988/2201, Radius 723487/72344, Base/Arbitrum/
Polygon all present (mainnet/testnet ordering).
- Cross-platform determinism: a clean-slate rebuild on macOS produces
byte-identical output to ubuntu-latest CI.
- Tarball install into a throwaway consumer: all expected chain IDs
present in the published dist/esm/evm/index.js.
- Browser smoke test (Chrome, served from a local HTTP server):
EvmPaywall mounts without Unsupported-chain throw for
eip155:31611 (Mezo Testnet) and eip155:723487 (Radius); DOM
renders the expected token/chain labels.
Fixes#1971.
- Add /protected to sitemap so scanners can discover the 402 endpoint
- Add X-X402-Supported header on homepage to signal x402 support
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(paywall): use dynamic token decimals instead of hardcoding 6
The EVM paywall displays incorrect amounts for any token that does not
use 6 decimal places. An 18-decimal token priced at 0.001 raw units
renders as $1,000,000,000 because the code divides by 10^6 everywhere.
Root cause: the paywall was built assuming USDC (6 decimals) is the
only payment token. This assumption appears in three places:
1. Server-side HTML generation (index.ts) divides the raw amount by
a hardcoded 10^6 to produce the display value injected into the
template.
2. Client-side balance display (EvmPaywall.tsx) calls formatUnits
with a hardcoded 6 and reads the token address from a 3-chain
USDC lookup table that returns 0 for any other chain.
3. The balance utility (utils.ts) only knows USDC addresses on
Ethereum, Base, and Base Sepolia — every other chain silently
shows a zero balance.
Fix:
Server-side (index.ts): look up the token's decimal precision from a
known-decimals map aligned with DEFAULT_STABLECOINS. Only non-6-decimal
chains need entries; everything else falls back to 6. This keeps the
server-side path simple with no RPC calls.
Client-side (EvmPaywall.tsx): read the token contract address from
the payment requirement's `asset` field (which the server already
populates) and query the standard ERC-20 decimals() function on-chain.
This works for any compliant token without maintaining a lookup table.
utils.ts: replace the USDC-specific getUSDCBalance (internal helper,
not part of the public API) with generic getTokenBalance and
getTokenDecimals functions that accept a token address parameter.
The function signature changes from 2 args to 3, but no external
consumer can import it — it is only used by the bundled React
component inside the paywall HTML template.
**Breaking change note:** the internal helper getUSDCBalance in utils.ts
is removed and replaced by getTokenBalance (different signature: takes
an explicit token address instead of looking it up by chain ID). This
function is not exported from the package's public API — it is only
consumed by the bundled EvmPaywall React component inside the paywall
HTML template. No server operator code calls it directly. However,
anyone who has forked the paywall and imports from the file path
(bypassing package exports) would need to update their import and
call site.
Regenerated Go, Python, and TS paywall templates.
**AI disclosure:** This PR was prepared with the assistance of a coding agent and
reviewed by Ryan R. Fox (an actual human) before submission.
* style: ruff format paywall templates
* fix(paywall): use DEFAULT_STABLECOINS lookup + BigInt formatUnits
Removes the parallel KNOWN_DECIMALS map in @x402/paywall/src/evm/index.ts
that mirrored DEFAULT_STABLECOINS from @x402/evm. The paywall now resolves
token decimals through the same registry that scheme implementations and
@x402/core's inline scheme dispatch already read from.
evmPaywall.generateHtml changes:
* getDefaultTokenDecimals helper looks up requirement.network directly in
@x402/evm's DEFAULT_STABLECOINS, with a 6 (USDC default) fallback when
the network is unknown.
* Atomic-to-display conversion uses Number(formatUnits(BigInt(amount),
decimals)) instead of parseFloat(amount) / 10**decimals. parseFloat
silently rounds sub-cent precision on real 18-decimal amounts before
the divide; BigInt + formatUnits preserves precision through the
conversion. BigInt also rejects non-integer atomic strings, which
matches the spec's atomic-integer contract.
@x402/paywall package.json: @x402/evm moves from devDependencies to
dependencies because the new server-side import of DEFAULT_STABLECOINS is
on the runtime path emitted into dist/.
@x402/evm now publicly re-exports DEFAULT_STABLECOINS from
./shared/defaultAssets so consumers can read the canonical default-asset
registry directly. Both @x402/evm and @x402/paywall get a minor bump
for the additive public API.
Adds 6 unit tests:
* getDefaultTokenDecimals returns 18 for Mezo Testnet (registry path)
* getDefaultTokenDecimals returns 6 for Base mainnet, asserted alongside
DEFAULT_STABLECOINS so an empty registry would fail the test
* getDefaultTokenDecimals falls back to 6 for unknown networks
* evmPaywall.generateHtml renders 1e15-atomic Mezo mUSD as
'amount: 0.001,' end-to-end (regression test for the /1e6 bug)
* evmPaywall.generateHtml renders 1e6-atomic Base USDC as 'amount: 1,'
* evmPaywall.generateHtml throws on a non-integer atomic ('1.5'),
pinning the BigInt strictness so a future revert to parseFloat fails
Closes#1979.
* refactor(paywall): generate evm decimals at build time, drop @x402/evm runtime dep
Addresses @phdargen's review: rather than promoting @x402/evm to a
runtime dependency of @x402/paywall, keep it a devDependency and
emit a codegen'd `src/evm/gen/decimals.ts` that mirrors just the
per-network `decimals` field of `DEFAULT_STABLECOINS`.
Pattern-consistent with the existing `src/evm/gen/template.ts` codegen
(HTML bundle) — same build step (`src/evm/build.ts`), same "AUTO-GENERATED
DO NOT EDIT" banner, same commit-the-generated-file workflow. The CI
drift check queued in #2054 (`check_paywall_template.yml`) will pick up
`decimals.ts` under the existing `typescript/packages/http/paywall/**`
trigger glob once that PR merges; in the meantime an in-process drift
invariant test in `network-handlers.test.ts` asserts `NETWORK_DECIMALS`
matches `DEFAULT_STABLECOINS` key-for-key.
Runtime behaviour is unchanged. `getDefaultTokenDecimals` now reads the
generated `NETWORK_DECIMALS` map instead of reading `DEFAULT_STABLECOINS`
at runtime; the same Mezo-18, Base-6, unknown→6 cases still hold, and
the existing 6 regression tests in `network-handlers.test.ts` pass
without modification. A seventh test pins the drift invariant described
above.
package.json: `@x402/evm` moved from `dependencies` to `devDependencies`.
Runtime module graph for `@x402/paywall` no longer pulls `@x402/evm`;
the only surviving `@x402/evm` references in paywall src are:
* `browserAdapter.ts` — `import type { ClientEvmSigner }` (type-only,
erased at build time)
* `EvmPaywall.tsx` — `ExactEvmScheme` (bundled into `gen/template.ts`
by esbuild, not part of the server-side runtime path)
* `build.ts` and `network-handlers.test.ts` — build-time / test-time
consumers; devDep is available in both.
Both the root `typescript/pnpm-lock.yaml` and `examples/typescript/pnpm-lock.yaml`
are updated to reflect the dep move — both workspaces reference the
paywall package manifest via `workspace:~`.
* feat: add auth-hints extension to streamline scheme-level authentication
- Described general auth scheme for x402, mainly on HTTP transports
- Initial support for two auth method types: oauth2 (Bearer/DPoP) and sign-in-with-x
- Defined scheme and acceptIndex hints.
* feat: settle on acceptIndexes, schemeAuth->authRequirements, remove references to scheme-based hints
* feat(hedera): add @x402/hedera package with exact payment scheme
- New @x402/hedera package implementing the x402 v2 exact scheme
- Uses @hiero-ledger/sdk for signing and submission
- Onchain preflight transfer check before settlement
- Settlement receipt validation (USDC + HBAR coverage)
- HEDERA_ACCOUNT_ID / HEDERA_PRIVATE_KEY / HEDERA_NETWORK env vars
- Integrated with advanced clients (axios, fetch), facilitators, and HTTP adapters (hono, fastify, next)
- E2E tests for Hono, Next.js, and Fastify servers
- Testnet faucet docs and token association notes
Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>
* refactor: use convertToAtomicAmount function from @x402/core/utils
Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>
---------
Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>
* feat(site): make x402.org agent-ready for isitagentready.com
Add all 13 isitagentready.com checks:
- robots.txt with AI crawler rules and Content Signals
- sitemap.xml via Next.js metadata API
- Link response headers (api-catalog, service-doc, payment-required)
- Markdown content negotiation (Accept: text/markdown)
- API catalog at /.well-known/api-catalog (RFC 9727)
- OAuth/OIDC discovery at /.well-known/openid-configuration
- OAuth Protected Resource at /.well-known/oauth-protected-resource
- MCP Server Card at /.well-known/mcp/server-card.json
- Agent Skills index at /.well-known/agent-skills/index.json
- WebMCP tool registration (get-x402-info, navigate-x402)
- x402 demo endpoint returning HTTP 402 with PAYMENT-REQUIRED header
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(site): add JSDoc descriptions to agent-ready route handlers
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(site): address PR review feedback
- Remove hollow OAuth stubs (openid-configuration, oauth-protected-resource)
that declared endpoints which don't exist
- Remove redundant /api/x402/demo route, point to /protected instead
- Remove non-existent /mcp endpoint from MCP server card
- Fix sitemap to use static dates instead of new Date()
- Fix SKILL.md to use CAIP-2 network identifiers (eip155:8453)
- Change WebMCP script strategy from beforeInteractive to afterInteractive
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* add mcp discovery support
* ci fixes and changelog
* rename changelog
* fix failing test
* fail in TS on transport mismatch, return extension info on settlement failure in python
* add e2e
* fix mcp payment payload parsing
* fix python parsing
* add transport to examples and docs
* docs: add npm badge with package version (Typescript + Chains)
* docs: create `README.md` under `typescript/` with full list of available packages
* docs: improve top README for installation instructions per language
* docs: separate code inputs to enable to copy / paste easily
* docs: add missing packages in installation command
* docs: break down and group package installation list for readability
* docs: add badges for packages around Algorand and Fastify
* docs: add Documentation Checklist + surface chain-contribution flow
DEFAULT_ASSETS.md's 'Adding a New Chain' numbered flow stopped at 'Update
all three SDKs' → 'Submit a PR' and did not mention the user-facing docs
surfaces that also enumerate every chain with default-asset support. As a
result, recent onboarding PRs have shipped with stale docs (e.g. the
Radius PR #2038 updated the SDKs but not the docs table or Go README).
The existing Cross-SDK Checklist at the bottom enumerates only the three
code registries, mirroring the same gap.
network-and-token-support.mdx has a parallel discoverability problem:
the pointer to DEFAULT_ASSETS.md used a repo-relative path that resolves
to a broken link on docs.x402.org, and the pointer sat inside the
'Default Assets for Dollar-String Pricing' intro rather than under
'Adding Support for New Networks' where a would-be contributor actually
looks. The 'Adding' section itself described only runtime registration
(server.register from consumer code) and did not mention the separate
upstream-contribution path, and it also contained a 'Running Your Own
Facilitator' subsection that is about facilitator infrastructure, not
about adding networks — a topical mismatch. The page also ordered the
'Facilitators' section before 'Adding Support for New Networks', which
inverts the natural read → use → extend → operate narrative.
Changes:
* DEFAULT_ASSETS.md:
- Promote 'Update user-facing documentation' to a numbered step in
'Adding a New Chain' (new step 3, between 'Update all three SDKs'
and 'Submit a PR'), with a cross-reference to the new checklist.
- Append a new 'Documentation Checklist' section below the existing
Cross-SDK Checklist, naming the two hot docs surfaces
(network-and-token-support.mdx and go/mechanisms/evm/README.md)
that must also be updated on a new chain onboarding.
* docs/core-concepts/network-and-token-support.mdx:
- Remove the oddly-placed 'See DEFAULT_ASSETS.md' link from the
Dollar-String Pricing intro; replace with an in-page anchor
pointing at the new contribution subsection.
- Split 'Adding Support for New Networks' into two subsections:
'Runtime Registration' (the existing content, unchanged) and
a new 'Contributing a New Default Asset' subsection that links
to DEFAULT_ASSETS.md via an absolute github.com URL (so the
link works on the published docs site) and explicitly names
the cross-SDK + docs checklist.
- Move 'Running Your Own Facilitator' out of 'Adding Support for
New Networks' into the existing 'Facilitators' section, where
it belongs topically.
- Swap top-level section order: 'Adding Support for New Networks'
now precedes 'Facilitators', matching the read → use → extend →
operate narrative.
No code changes. Documentation only.
* docs: revert DEFAULT_ASSETS.md, unify SDK READMEs to link docs
Address review feedback: the Mintlify agent (.github/workflows/update-docs.yml)
keeps docs/ in sync with code, so contributors should only update the three SDK
constants files. Remove the Documentation Checklist and Step 3 from
DEFAULT_ASSETS.md. Apply a consistent two-link block to all three SDK READMEs
(Go/TS/Python) pointing at the mdx default-assets list and the mdx
Adding Support for New Networks section. Soften the mdx Contributing a New
Default Asset blurb to drop manual mdx/README update instructions.
Set expectations for AI-generated contributions: require human review
before requesting PR review, remove verbosity and redundancy, verify
payment/signing correctness against specs, and disclose significant AI
usage. Include a sample system prompt for AI coding agents (Claude Code,
Codex, Cursor) that aligns agent output with x402 contribution standards.
Inspired by Neovim's AI-assisted work guidelines, adapted for x402's
security-sensitive payment infrastructure context.
Implement the spec change from PR #1682, adding optional seller-defined
memo support to the SVM exact scheme across all three SDKs.
Client changes (TypeScript, Go, Python - both v1 and v2):
- When extra.memo is present, use its UTF-8 value as memo instruction data
- When absent, fall back to existing random 16-byte nonce behavior
- Validate memo does not exceed MAX_MEMO_BYTES (256) limit
Facilitator changes (TypeScript, Go, Python - both v1 and v2):
- When extra.memo is present in requirements, verify exactly one memo
instruction exists and its data matches the expected value
- Return specific error codes: memo_count / memo_mismatch
Constants added:
- MAX_MEMO_BYTES / MaxMemoBytes (256) across all languages
- ERR_MEMO_MISMATCH, ERR_MEMO_COUNT (Python/Go)
- ErrMemoExceedsMaxSize (Go client)
Tests added:
- TypeScript: 4 memo tests in duplicateTx.test.ts
- Go: TestSellerMemo with 4 subtests in duplicate_tx_test.go
- Python: TestSellerMemo class with 4 tests in test_duplicate_tx.py
Closes#1682
All direct viem dependencies now resolve to 2.47.12, adding chain
definitions for Mezo Testnet (31611), MegaETH (4326), Stable (988/2201),
and others that were missing from earlier locked versions.
Lockfile-only change. No package.json range changes — all existing ^2.x
ranges already accept 2.47.12.
The Go EVM mechanism README (introduced in #1983) listed only 4 chains
under "Networks with default assets configured":
- Base Mainnet, Base Sepolia, MegaETH Mainnet, Monad Mainnet
But `go/mechanisms/evm/constants.go` configures 10, and the main docs
table at `docs/core-concepts/network-and-token-support.mdx` lists all
10. Restore parity with the constants and the main docs table, in the
same order as the mdx table:
- Base, Base Sepolia, Polygon, Arbitrum One, Arbitrum Sepolia,
Monad, Stable, Stable Testnet, MegaETH, Mezo Testnet
All entries verified against `NetworkConfigs` in
`go/mechanisms/evm/constants.go`.
Follow-up to #1983 which introduced this README.
The EVM paywall hardcodes "USDC" as the token label in all display
text. The payment requirements already carry the token name in
extra.name (populated by the server from the default asset registry),
but the paywall ignores it.
Read extra.name from the first payment requirement and use it for
all user-facing token text. Falls back to "USDC" when extra.name
is absent (backward compatible with EIP-3009 tokens).
5 display strings updated:
- Header: "please pay $X {tokenName}" (was "USDC")
- Testnet prompt: "Need {tokenName} on {chainName}?" (was "USDC")
- Balance: "$X {tokenName}" (was "USDC")
- Amount row: "$X {tokenName}" (was "USDC")
- Error: "Make sure you have {tokenName} on {chainName}" (was "USDC")
Regenerated Go, Python, and TS paywall templates.
* Migrate all code from branch-algorand-v2-typescript-algokit
* Update format and lint pass on core and examples
* Reformat template files
* Update: Coinbase review changes applied
* Fix Paywall builder pattern
* Update: Reverted e2e/legacy, Remove: src/exact/v1 and src/v1
* Add Faucets URLs to AVM README
* Optimizing and shrinking PR
* Remove dead import
* Add optimization changes related unit tests
* Update coinbase review changes applied
* Update avm e2e, rebased to latest, linted and formatted
* Fix avm template format
* Remove python and Go AVM templates, Made AVM optional to facilitator and Add SERVER_ADDRESS
* Lint and format
* Update: made AVM optional in proxy.ts
* Rebased and Replayed some commits
* Reset e2e pnpm-lock.yaml
* Replayed correct updated lockfiles
* Reverted accidentally overwritten files during rebase replay
* Revert accidental overwritten files in examples
* feat(bazaar): add MCP resource type support to Go SDK
Add MCP tool discovery extensions to the bazaar package, achieving
parity with the TypeScript and Python SDKs. Servers can now declare
MCP tool discovery extensions alongside HTTP resources, and facilitators
can detect and extract them from payment payloads.
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: gofmt formatting and gocritic if-else-chain lint
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(bazaar): transport enum, doc examples, inline helper, add negative tests
- Fix transport schema enum to include both valid values (streamable-http,
sse) instead of only the provided value, matching TypeScript SDK behavior
- Fix doc.go examples to use bazaar.BAZAAR.Key() instead of bazaar.BAZAAR
- Inline createMcpDiscoveryExtension into DeclareMcpDiscoveryExtension
- Add negative validation tests for wrong type and empty toolName
- Add edge case tests for whitespace-only toolName and invalid transport
Co-Authored-By: Claude <noreply@anthropic.com>
* feat(mcp): wire extensions into PaymentWrapper 402 response
Add Extensions field to PaymentWrapperConfig and pass it through to the
PaymentRequired struct in 402 responses. This brings the MCP payment
wrapper to parity with the HTTP middleware's RouteConfig.Extensions
support, enabling bazaar discovery extensions in MCP tool responses.
- Add Extensions map to PaymentWrapperConfig (types.go)
- Set extensions in paymentRequiredResult (server.go)
- Add unit tests for extensions present/absent in 402 (server_test.go)
- Declare bazaar MCP extension in E2E server (main.go)
- Add bazaar extension integration test (mcp_evm_test.go)
Co-Authored-By: Claude <noreply@anthropic.com>
* feat(mcp): wire TS extensions into 402 responses + Go integration tests
Add extensions support to the TS MCP PaymentWrapperConfig and pass it
through to createPaymentRequiredResponse so bazaar discovery metadata
appears in 402 responses. Wire the E2E server with declareDiscoveryExtension
for the get_weather tool. Add Go mocked-transport integration tests
(5 cases) covering the full client↔server payment flow to match TS
mcp-payment-flow.test.ts coverage.
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: prettier formatting in MCP test files
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(bazaar): address PR review feedback from @CarsonRoscoe
- Use strings.TrimSpace for toolName validation to reject whitespace-only names
- Allow custom transport values through schema validation (only enum for known transports)
- Fix whitespace toolName test to assert error instead of success
- Remove conditional guard in TS bazaar extension test so assertions always run
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(bazaar): allow custom transport values in TS to match Go behavior
Widen transport type from "streamable-http" | "sse" to string, and only
apply enum constraint in schema for known transport values. This matches
the Go-side fix so custom transports pass validation in both languages.
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>