* 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
* feat(python): add payment-identifier extension types and constants
- Add PaymentIdentifierInfo and PaymentIdentifierExtension Pydantic models
- Add constants: PAYMENT_IDENTIFIER, PAYMENT_ID_MIN_LENGTH, PAYMENT_ID_MAX_LENGTH, PAYMENT_ID_PATTERN
- Define PaymentIdentifierSchema type alias
* feat(python): add payment-identifier utility functions
- Add generate_payment_id() to create UUID v4-based payment IDs
- Add is_valid_payment_id() to validate ID format (16-128 chars, alphanumeric + hyphens/underscores)
* feat(python): add payment-identifier JSON Schema definition
- Add payment_identifier_schema compliant with JSON Schema Draft 2020-12
- Schema validates required boolean and optional id string field
* feat(python): add payment-identifier validation and extraction functions
- Add ValidationResult dataclass for validation results
- Add is_payment_identifier_extension() type guard
- Add validate_payment_identifier() for full extension validation
- Add extract_payment_identifier() to extract ID from PaymentPayload
- Add extract_and_validate_payment_identifier() combined function
- Add has_payment_identifier() to check extension presence
- Add is_payment_identifier_required() to check requirement flag
- Add validate_payment_identifier_requirement() for requirement compliance
* feat(python): add payment-identifier client utilities
- Add append_payment_identifier_to_extensions() to append payment ID to extensions dict
- Only appends if server declared the extension
- Generates new ID if not provided
* feat(python): add payment-identifier resource server utilities
- Add declare_payment_identifier_extension() to create extension declaration
- Add PaymentIdentifierResourceServerExtension class implementing ResourceServerExtension protocol
- Add payment_identifier_resource_server_extension singleton instance
* feat(python): add payment-identifier extension main module
- Export all public APIs from payment-identifier extension
- Add comprehensive usage documentation with examples for servers, clients, and idempotency
* feat(python): export payment-identifier extension from extensions module
- Add payment-identifier imports and exports to main extensions __init__.py
- Export all constants, types, functions, and classes for public API
* fix(python): resolve ValidationResult type mismatch in extensions module
- Export payment_identifier.ValidationResult as ValidationResult (matches payment_identifier function return types)
- Export bazaar.ValidationResult as BazaarValidationResult for explicit bazaar usage
- Both ValidationResult classes are structurally equivalent (same dataclass fields)
- Fixes type mismatch where payment_identifier functions returned payment_identifier.ValidationResult but ValidationResult imported from x402.extensions was bazaar.ValidationResult
* refactor(python): rename payment_identifier ValidationResult to PaymentIdentifierValidationResult
- Rename ValidationResult class to PaymentIdentifierValidationResult in payment_identifier/validation.py
- Update all function return types and usages throughout validation.py
- Update exports in payment_identifier/__init__.py
- Update imports/exports in extensions/__init__.py
- Keep ValidationResult from bazaar as default export for backward compatibility
- Export PaymentIdentifierValidationResult separately for explicit payment_identifier usage
- Makes naming consistent with BazaarValidationResult pattern
* test(python): add comprehensive test suite for payment_identifier extension
- Add test_types.py: Test constants and Pydantic models
- Add test_utils.py: Test ID generation and validation functions
- Add test_validation.py: Test all validation and extraction functions
- Add test_client.py: Test client-side utilities
- Add test_server.py: Test server-side utilities
- Tests cover all major functionality including edge cases and error handling
- Follows same structure as bazaar extension tests
* fix(python): fix payment_identifier test helper and assertions
- Fix create_extension_with_id helper to handle invalid IDs for testing
- Update test assertion to check for 'identifier' in error message
- All 67 tests now passing
* fix(python): add ValidationResult alias for backward compatibility
- Add ValidationResult = BazaarValidationResult alias after bazaar import
- Fixes AttributeError when importing ValidationResult from x402.extensions
- ValidationResult was imported as BazaarValidationResult but exported in __all__
- Now both ValidationResult and BazaarValidationResult are available
* test(python): add test to verify __all__ exports are importable
- Add test_exports.py to verify all items in __all__ can be imported
- Tests that ValidationResult alias works correctly
- Tests that 'import *' works as expected
- This would have caught the ValidationResult AttributeError bug
* fix(python): make jsonschema import lazy in payment_identifier validation
- Remove module-level jsonschema import that raised ImportError
- Import jsonschema lazily only when schema validation is needed
- Return validation error instead of raising ImportError at module level
- Allows payment_identifier extension to be imported without jsonschema
- Users can still use non-validation functions without optional dependency
* fix(python): fix linting errors
- Remove unused variable in test_types.py
- Fix import sorting in extensions/__init__.py
- Add noqa comment for intentional E402 (import after alias)
* Lint
* docs(python): add payment-identifier extension examples
Add client and server examples demonstrating how to use the
payment-identifier extension for idempotent payment processing.
Client example shows:
- Generating payment IDs with generate_payment_id()
- Using on_before_payment_creation hook to inject the ID
- Making duplicate requests to demonstrate cache behavior
Server example shows:
- Declaring extension support with declare_payment_identifier_extension()
- Extracting payment IDs with extract_payment_identifier()
- Caching responses after settlement for idempotency
* Lint
* Format
* Changelog