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
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.
* 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>
Add native USDC (0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359) as the
default stablecoin for Polygon mainnet across all three SDKs:
- Go: ChainIDPolygon constant, v2 NetworkConfigs, v1 NetworkConfigs
- TypeScript: v2 stablecoins map in ExactEvmScheme
- Python: v2 NETWORK_CONFIGS with supported_assets
Update Go v1 unit tests that previously used "polygon" as a network
without a default asset config. Replace with "iotex" and add positive
test coverage for Polygon config and asset resolution.
Contract details (verified on-chain via PolygonScan):
- Token: Circle native USDC (FiatTokenV2_2)
- EIP-712 domain: name="USD Coin", version="2"
- EIP-3009: transferWithAuthorization supported
- x402 proxy deployed at canonical CREATE2 address
* 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>
* fix(go): add omitempty to QueryInput/BodyInput.Method to prevent spurious enum validation failure
When external JSON omits info.input.method (valid when method is not in the schema's
required list), Go zero-initializes the Method field to "" and re-marshaling produces
"method":"", which fails the enum constraint in ValidateDiscoveryExtension.
Adding omitempty ensures absent method fields remain absent after round-trip serialization.
Fixes#1830
Made-with: Cursor
* enforce method is required in TS and Python discovery extension schemas
Per spec, the method field must always be present in a discovery extension's
info.input. Add "method" to the required array in schemas built by the TS
and Python resource service builders, so ValidateDiscoveryExtension rejects
extensions missing method with a clear error.
Also reverts the Go omitempty workaround from the prior commit; the Go SDK
was already producing a validation error for absent method (via the enum
constraint), and the schema-level required enforcement is the correct fix.
Closes#1830
Made-with: Cursor
* style: format resourceService.ts type union per Prettier
Made-with: Cursor
* fix: auto-populate HTTP method from adapter in all SDKs
The SDK entry points (processHTTPRequest, requiresPayment,
processSettlement) now derive the HTTP method from the adapter
when it is not explicitly set on the request context. This ensures
direct x402HTTPResourceServer users do not need to manually assign
the method field — the SDK computes it at runtime, matching the
behavior middleware users already get.
Made-with: Cursor
* test: add declare → enrich → validate flow tests for bazaar extension
Verify the real middleware path: extensions are declared without method,
enrichDeclaration injects method from the HTTP context at request time,
and the enriched extension passes schema validation. Covers GET and
POST in all three SDKs (TypeScript, Go, Python).
Made-with: Cursor
* 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>
* feat(evm): add Stable mainnet (chain ID 988) network support
* chore: add changelog fragments for Stable mainnet support
* feat(evm): add Stable mainnet to Go v1 legacy network config
* feat(go): add net/http standard library adapter for payment middleware
* feat(go): add PaymentMiddlewareFromHTTPServer, example server, and e2e tests
When Verify or Settle fails to find a matching facilitator for a
scheme/network pair, the error now lists all registered scheme/network
combinations. This helps users quickly identify misconfiguration
(e.g., wrong network name, missing registration) without having to
inspect the facilitator setup code.
Before: no facilitator for scheme exact on network eip155:1
After: no facilitator for scheme "exact" on network "eip155:1"; registered: exact@eip155:8453, exact@eip155:84532
Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
The comment on line 26-27 stated hooks were "not fully integrated"
and had a TODO to integrate them into Verify execution. All 7 hook
tests (BeforeVerify, AfterVerify, OnVerifyFailure, BeforeSettle,
AfterSettle, OnSettleFailure, MultipleHooks) already exercise hooks
through the full Verify/Settle execution paths, confirming hooks
are fully integrated.
Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
* fix: add duplicate settlement mitigation for SVM across all SDKs
Introduce an in-memory SettlementCache to prevent a race condition on
Solana where the same payment transaction could be settled multiple
times before on-chain confirmation. The cache is shared across V1 and
V2 facilitator schemes so that cross-version duplicates are caught.
- Add SettlementCache with 120s TTL in TypeScript, Python, and Go
- Integrate cache check into facilitator settle paths (V1 and V2)
- Add unit tests for duplicate detection in all three languages
- Share cache across V1/V2 in Go facilitator example
- Add duplicate settlement spec to scheme_exact_svm.md
- Document SettlementCache in SVM READMEs for all three SDKs
- Document the race condition in go/FACILITATOR.md Security section
- Add merchant-facing guidance in docs/core-concepts/client-server.md
and docs/core-concepts/facilitator.md for self-settling servers
- Fix JSDoc lint errors in TypeScript settlement-cache.ts
* refactor: optimize SettlementCache prune with early break on ordered entries
Leverage insertion-order guarantees of Map (TS) and dict (Python) to
break early once a non-expired entry is encountered, avoiding a full
scan of the cache on every isDuplicate call. Go is left unchanged since
map iteration order is not guaranteed.
Also adds prune-specific unit tests for all three SDKs covering:
- mixed expired/fresh entries
- all expired
- none expired
- insertion-order early-break correctness (Python)
* docs: add changelog entries for SVM duplicate settlement fix
* feat(go/http): add onProtectedRequest hook for pre-payment request interception
* feat(go/http/gin): add PaymentMiddlewareFromHTTPServer for pre-configured server support