Tightens the viem floor in every package.json that lists viem (41 refs
across 40 files), refreshes all three lockfiles so every direct viem
resolution reads 2.48.11, and regenerates the paywall bundled templates
so the EVM/SVM/AVM bundles match the new viem chain database.
## Why floor-tightening matters
PR #2013 bumped lockfiles to 2.47.14, but later PRs (#2061, #2197, ...)
added sub-packages with ^2.39.x / ^2.43.x floors. pnpm re-resolved on
subsequent installs and the solver picked the lowest acceptable version
across constraints. ^-ranges with low floors do NOT preserve a bump --
lockfile refreshes erode the floor.
This PR fixes that incomplete tightening from #2013 by raising every
floor to ^2.48.11. The same regression will recur if any future PR adds
a viem-using sub-package with a lower floor. Gate criterion: new
packages must use ^2.48.11 (or tighter) for viem.
## Acceptance verification
- pnpm install --frozen-lockfile clean across typescript/,
examples/typescript/, and e2e/.
- pnpm format:check, lint:check, build, test green for typescript/.
- pnpm format:check, lint:check green for examples/typescript/.
- All direct viem resolutions read 2.48.11 in all three workspaces.
- Paywall bundled templates regenerated via
pnpm --filter @x402/paywall run build:paywall.
* feat: add TVM exact-payment mechanism to Python SDK
- add TVM exact client, server, and facilitator implementations
- add TVM signers, codecs, provider, and settlement helpers
- add unit and integration coverage for TON testnet/mainnet flows
- add Python examples and e2e wiring for TVM
* Enable TVM exact flows in Python e2e and tighten facilitator validation
Add TVM support to the Python e2e clients and servers, switch TVM usage to direct `ExactTvm*Scheme` registration after removing the old register helpers, and refresh docs/examples for testnet setup.
Also reject exact TVM settlements with excessively large attached TON amounts and cover the new validation with tests.
* fix: clarify minimum balance of the facilitator
* refactor(tvm): release settlement cache entry on confirmed settlement
On-chain seqno advances after a successful relay, so any retry of the same settlement BOC will fail at the W5 contract's seqno check regardless of the dedup reservation. Drop the entry as soon as the confirmation worker records success, so the invariant becomes "every is_duplicate=False is paired with a release" and TTL pruning is left as a crash safety-net only.
* feat(tvm): add TonAPI provider support
* feat(tvm): update e2e tests to make them compatible with new providers
* fix(tvm): update timeouts
* fix(tvm): increase http client timeout
* fix(tvm): align unit tests
* revert(e2e): remove .env-local config load
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat: add batch-settlement implementation to Go SDK
* feat: add batch-settlement examples for go sdk
* feat: updated typescript examples to match go examples
* feat: add e2e testing for batch-settlement in go
* Batch-settlement: go-ts parity (#2227)
* fix PendingRequest and refund cleanup
* fix lint
* remove duplicate payer info from storage
* fix PAYMENT-RESPONSE field ordering
* clean up comments
* consolidate ProcessSettlementWithExtensions into ProcessSettlement
---------
Co-authored-by: phdargen <p.dargent@cern.ch>
* 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>
* 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
* 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>
* fix: e2e approve bug
* feat: remove new docstring addition
* fix: update Next.js e2e server to /exact/evm/... path structure
The `feat: add upto to typescript sdk` commit reverted proxy.ts and
test.config.json from the improved `/api/exact/evm/...` path structure
back to old `protected-*` paths, without recreating the deleted route
files. Fix this properly by:
- Update proxy.ts route keys and config.matcher to /exact/evm/... paths
- Update test.config.json to /exact/evm/... paths, preserving
coldstart: true on the two permit2 endpoints
- Add missing proxy route files at new paths:
exact/evm/eip3009/proxy, exact/evm/permit2/proxy,
exact/evm/permit2-eip2612GasSponsoring/proxy,
exact/evm/permit2-erc20ApprovalGasSponsoring/proxy,
exact/svm/proxy, exact/stellar/proxy, exact/aptos/proxy
Note: route files are in directories named "proxy" which matches a
root .gitignore pattern, so they are tracked with git add -f.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: flatten non-EVM chain routes to /exact/{chain} base path
SVM, Aptos, and Stellar each have a single transfer mechanism with no
variants, so the /proxy sub-path is unnecessary. Move them to the base
level /exact/{chain} pattern, matching EVM's approach of only adding
sub-paths when there are multiple mechanisms or extensions to test.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: pr cleanup and review
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(evm): add upto payment scheme TypeScript SDK
Implement the upto payment scheme for EVM, enabling usage-based payments
where a client authorizes a maximum amount via Permit2 and the server
settles for the actual amount used (which may be less).
Covers all three roles:
- Client: creates Permit2 payloads with max authorized amount
- Server: builds payment requirements, forces permit2 transfer method
- Facilitator: verifies permitted >= required, settles actual usage,
supports zero-settlement path for no-charge responses
Key design decisions:
- Permit2 only (no EIP-3009, per spec)
- Shared Permit2 witness struct with exact scheme
- Re-exports shared utilities from exact (approval helpers, extensions, RPC)
- V2 protocol only
Resolves: CDPAI-714
* chore(evm): add JSDoc descriptions and fix lint errors in upto SDK
Add comprehensive JSDoc descriptions, @param, and @returns tags to all
upto scheme files to satisfy eslint jsdoc rules. Remove unused imports
in facilitator test file.
* refactor(evm): extract shared permit2 helpers to reduce duplication between exact and upto facilitators
* refactor(evm): consolidate client-side createPermit2Payload into shared helper
* refactor(evm): extract shared trySignEip2612Permit and trySignErc20Approval from scheme classes
* refactor(evm): split shared/permit2-helpers into permit2.ts and extensions.ts
* test(evm): add upto server, register, and types tests; expand client and facilitator coverage
Add 3 new test files (server.test.ts, register.test.ts, types.test.ts)
covering upto-specific server behaviors (permit2 forcing, facilitator
address injection, price parsing), registration helpers for all three
roles, and type guard validation. Expand existing client and facilitator
tests with additional edge cases.
Also includes in-progress source changes: shared permit2 helper
refactoring, upto facilitator hardening, spec clarifications, and
defaultAssets extraction.
* fix(evm): resolve lint errors for CI — add missing JSDoc descriptions and fix unused vars
* fix(evm): address PR review — align upto verify flow with exact, update spec, remove createEvmClient
* refactor(evm): move shared utils to shared/, remove upto register pattern
- Move validateErc20ApprovalForPayment to shared/erc20approval.ts
(was in exact/facilitator/, used by both exact and upto)
- Move RPC utilities to shared/rpc.ts, rename types to drop Exact prefix
(EvmSchemeConfig, EvmSchemeOptions, etc.) with deprecated aliases
- Remove registerUptoEvmScheme from client, facilitator, and server
(v1 legacy pattern not needed for v2-only upto scheme)
- Backward-compat re-exports preserved at original paths
* test(e2e): add upto payment scheme e2e test coverage
Add full e2e test suite for the upto payment scheme mirroring exact
permit2 coverage: direct settle, EIP-2612 gas sponsoring, and ERC-20
approval gas sponsoring endpoints.
- Add 3 upto endpoints to Express e2e server with UptoEvmScheme
- Register UptoEvmScheme in TypeScript facilitator
- Register UptoEvmClientScheme in fetch and axios e2e clients
- Add upto Permit2 approve/revoke cycle handling in test runner
- Add upto entry points to @x402/evm tsup.config.ts
- Update test.config.json files for all components
* fix(evm): harden upto type guard, add time window validation, improve settlement comments
- Add validAfter check to isUptoPermit2Payload for stricter exact/upto discrimination
- Add deadline > validAfter guard in client permit2 payload creation
- Default simulateInSettle to true for settlement re-verification
- Expand settlement re-verification comment for reviewer clarity
- Add no-register.ts comments explaining V1 compat is not needed for upto
- Clarify e2e test config description for upto endpoint
- Add tests for validAfter type guard and buildUptoPermit2SettleArgs
* feat: added SettlementOverride
* fix: examples lock
* feat: Added upto to hono/next e2e tests
* feat: update upto tests
* feat: update tests to support fallback facilitator for non-SDK parity testing
* fix: format/lint
* fix: add linting to upto example
---------
Co-authored-by: Fabrice Cheng <fabrice.cheng@coinbase.com>
* Applied monkey-patch on reply.raw write operations and buffered response to prevent content leak from direct raw writes bypassing Fastify's onSend lifecycle
* fix e2e tests
* Add Fastify framework adapter for x402 payment middleware
* fix(fastify): preserve settlement response bytes and resource URLs
* chore(fastify): regenerate lockfiles for @x402/fastify workspace package
The pnpm-lock.yaml files in typescript/ and examples/typescript/ were missing
entries for the @x402/fastify package, causing CI to fail with
ERR_PNPM_OUTDATED_LOCKFILE on every workflow.
* feat(fastify): add e2e test server
Adds a Fastify server to the e2e test suite, following the same pattern as
Express and Hono. The test framework auto-discovers it via test.config.json.
Includes all standard endpoints: /protected (EVM), /protected-svm, /protected-aptos,
/protected-permit2, /protected-permit2-erc20, /protected-stellar, /health, /close.
* ci(fastify): add npm publishing workflow
Adds workflow_dispatch publishing workflow for @x402/fastify, matching the
pattern used by @x402/express and @x402/hono.
* feat(go): add net/http standard library adapter for payment middleware
* feat(go): add PaymentMiddlewareFromHTTPServer, example server, and e2e tests
* chore: bump @stellar/stellar-sdk and remove the now unneeded fix
* Update getEstimatedLedgerCloseTimeSeconds to receive the rpc latest ledger, thus reducing by one the rpc calls needed
* Update getEstimatedLedgerCloseTimeSeconds to use horizon, which is way more efficient than rpc for this particular request
* Add changeset
* Add @x402/stellar mechanism package with exact scheme
Implement Stellar support for the x402 protocol covering:
- Types, constants (network IDs, USDC contracts), and utility functions
- Ed25519 signer with client/facilitator variants
- Soroban transaction simulation and auth entry handling
- Client: builds transfer calls, signs auth entries, serializes XDR
- Server: parses prices, enhances payment requirements
- Facilitator: verify (structure, amounts, signatures, events) and
settle (fee sponsorship, multi-signer round-robin, submission)
* Add unit tests for the Stellar mechanism
Cover signer, constants, utils, shared helpers, client/server
scheme logic, and facilitator verify/settle/getExtra flows.
150 tests across 9 test files.
* Add integration tests for Stellar exact scheme
End-to-end flows against Stellar testnet covering both the core
x402Client/Server/Facilitator and the HTTP middleware variants.
Includes resilience to testnet resets via automatic re-funding.
* Add Stellar README and cross-reference from evm/svm
Document the package API, usage examples, fee sponsorship model,
and multi-signer facilitator setup. Link back from evm and svm.
* Wire up Stellar in the advanced examples
Register Stellar client/server/facilitator schemes alongside EVM
and SVM in the all_networks examples. Guarded by env var presence
so existing setups keep working without Stellar credentials.
* Document Stellar setup in the advanced example READMEs
Add STELLAR_PRIVATE_KEY / STELLAR_ADDRESS env vars to .env-local
templates and update the example READMEs with Stellar usage notes.
* Add Stellar to the e2e test suite
Extend the test framework with Stellar network support, add
protected-stellar endpoints to express/hono/next servers, register
Stellar signers in axios/fetch clients and the TS facilitator.
Includes test configs, lockfile, and the Stellar family in the
test runner. All 8 server×client combos pass against testnet.
* Update e2e docs with Stellar setup and trustline instructions
Add STELLAR env vars to .env-local templates, document the Stellar
testnet account setup process (keypair, USDC trustline, faucet),
and update all server/client/facilitator READMEs.
* Add npm publish workflow for @x402/stellar
Manual-dispatch GitHub Actions workflow to publish the Stellar
package to npm with provenance, matching the pattern used by
the other mechanism packages.
* Add CHANGELOG for @x402/stellar v2.5.0
* chore(svm): move @solana/kit to peerDependencies for v5/v6 compatibility
* chore(svm): update examples lockfile for peerDependencies change
* chore: bump @solana/kit to ^6.1.0 across examples, e2e, and packages
Bumps all consuming packages from ^2.1.1 to ^6.1.0 to align with the
SVM mechanism's >=5.1.0 peerDependency range.
Also fixes a pre-existing type error in the e2e facilitator where
DiscoveredResource union type was accessed without narrowing.
* refactor(aptos): remove registerExactAptosScheme helpers, use builder pattern directly
Remove the backwards-compat register helpers introduced with the Aptos
package (registerExactAptosScheme for client/server/facilitator). New
packages should use the builder pattern (.register("aptos:*", new
ExactAptosScheme(...))) directly rather than wrapping it.
- Delete exact/{client,server,facilitator}/register.ts
- Simplify exact/{client,server,facilitator}/index.ts to re-export only ExactAptosScheme
- Simplify exact/index.ts to export only ExactAptosScheme from client (matching EVM/SVM)
- Update all e2e servers, clients, and facilitator to direct .register() calls
- Update test imports to use ExactAptosScheme aliases from scheme subpaths
- Update README examples to use builder pattern
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* refactor: replace registerExact{Evm,Svm}Scheme helpers with direct .register() calls
Remove all usage of the backwards-compat register helpers outside of
their source definitions. Every consumer now uses the builder pattern
directly (.register("eip155:*", new ExactEvmScheme(signer))) which
matches the Aptos pattern and is more explicit.
- e2e servers (express, hono, next): server.register("eip155:*" / "solana:*", new Exact*Scheme())
- e2e clients (fetch, axios): client.register with ExactEvmScheme / ExactSvmScheme
- e2e facilitator (typescript): facilitator.register with both EVM and SVM schemes
- examples/clients (fetch, axios, sign-in-with-x, payment-identifier, advanced/all_networks): direct register
- examples/facilitator/basic: facilitator.register preserving deployERC4337WithEIP6492 option
- examples/fullstack (next proxy, miniapp route, miniapp page): direct register
- paywall package (EvmPaywall, SolanaPaywall): direct register
The registerExact{Evm,Svm}Scheme helpers remain available in the package
for backwards compat (used only in "simple" examples for new-user DX).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: run go mod tidy on Go client examples
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: e2e tests
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* Add Aptos mechanism implementation for x402
* Revert go changes
* Fix go revert
* Fix e2e imports
* Add aptos to all server e2e tests, make optional
* Make aptos optional on site
* Fix lint / format issues
* Add workflow for x402 aptos package
* Update e2e tests
* Fix facilitator manager