pull in latest upstream#2
Open
TtheBC01 wants to merge 602 commits into
Open
Conversation
Corrected the spelling of 'convenience' in the README.
* feat: add agently to x402 ecosystem * chore: update agently url
* clean up dep * fix examples
* Update docs/sdk-features.md Generated-By: mintlify-agent * Update docs/extensions/payment-identifier.mdx Generated-By: mintlify-agent * Update docs/extensions/payment-identifier.mdx Generated-By: mintlify-agent * Update docs/extensions/payment-identifier.mdx Generated-By: mintlify-agent * Update docs/extensions/payment-identifier.mdx Generated-By: mintlify-agent * fix conflicts --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: Philippe d'Argent <p.dargent@cern.ch>
* Update docs/extensions/bazaar.mdx Generated-By: mintlify-agent * Update docs/sdk-features.md Generated-By: mintlify-agent --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
…terception (#1371) * feat(go/http): add onProtectedRequest hook for pre-payment request interception * feat(go/http/gin): add PaymentMiddlewareFromHTTPServer for pre-configured server support
* Update docs/advanced-concepts/lifecycle-hooks.mdx Generated-By: mintlify-agent * Update docs/sdk-features.md Generated-By: mintlify-agent --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
* fix(exact): enforce strict amount equality per spec The exact scheme spec states the transferred amount MUST equal PaymentRequirements.amount exactly. All four facilitators used < instead of !==, silently accepting overpayments. Changes: - SVM V2: amount !== BigInt(requirements.amount), reason: amount_mismatch - SVM V1: amount !== BigInt(requirementsV1.maxAmountRequired), reason: amount_mismatch - EVM EIP-3009: authorization.value !== requirements.amount, reason: authorization_value_mismatch - EVM Permit2: permitted.amount !== requirements.amount, reason: amount_mismatch Error reasons renamed from _insufficient to _mismatch to cover both directions (underpayment and overpayment). Closes #1378 * fix(exact): also enforce strict amount equality in v1 EVM facilitator Applies the same < to !== comparison change to the v1 EVM facilitator for consistency with the v2 EVM and SVM facilitators. * docs(spec): correct exact scheme amount validation description Two inaccuracies in x402-specification-v2.md relative to the authoritative scheme contract in specs/schemes/exact/scheme_exact.md: - §6.1.2 step 3: 'meets or exceeds' -> 'exactly matches' The exact scheme requires strict equality (scheme_exact.md L24, scheme_exact_svm.md L143). This section describes the EVM implementation of the exact scheme, not the upto scheme. - §9 error table: rename invalid_exact_evm_payload_authorization_value to invalid_exact_evm_payload_authorization_value_mismatch and update description from 'insufficient' to 'does not exactly match'. These error codes are EVM-scheme-layer codes; the table is updated to reflect the renamed code in the accompanying implementation change. * style(evm): wrap long if condition in permit2.ts for prettier compliance
Generated-By: mintlify-agent Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
…ody (#1312) All four SDK implementations (TypeScript, Go, Go legacy, Python) include x402Version as a top-level field in the facilitator /verify and /settle request bodies, but neither the v1/v2 specs nor the TypeScript types document it. This adds x402Version to: - v2 spec section 7.1 (POST /verify) request schema - v1 spec section 7.1 (POST /verify) request schema - VerifyRequest and SettleRequest types in @x402/core - VerifyRequestV1 and SettleRequestV1 types in @x402/core Closes #1176
…agents (#1381) Co-authored-by: AI Agent Economy <up2itnow0822@users.noreply.github.com>
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>
* feat(ecosystem): add Kevros AI governance gateway * ci: retrigger checks
…02 Gateway (#1403) * feat(ecosystem): Add Agoragentic - Agent-to-Agent Marketplace with x402 Gateway * feat(ecosystem): Add Agoragentic logo --------- Co-authored-by: rhein1 <rhein1@users.noreply.github.com>
* Add upto payment scheme specification for EVM Introduces the upto scheme which enables usage-based payments where clients authorize a maximum amount and servers settle for the actual amount used. This is ideal for variable-cost resources like LLM token generation, bandwidth metering, or time-based access. Key features: - Uses Permit2 exclusively (permitWitnessTransferFrom) - Client signs for max amount, server settles for actual usage - Settlement amount can be 0 to amount (inclusive) - Adds settledAmount field to SettlementResponse - Reuses existing x402Permit2Proxy contract * Link to existing x402Permit2Proxy contract instead of duplicating * Clarify error codes: standard vs scheme-specific - List standard x402 error codes that apply to upto scheme - Add scheme-specific error codes following naming convention - Add missing error codes for recipient mismatch and time validation * Simplify error codes section and add SettlementResponse link - Link to base SettlementResponse schema in main spec - Reference standard error codes instead of duplicating - Keep only the truly upto-specific error code: settlement_exceeds_amount * docs(upto): add explicit MUST requirements for cross-network properties - Add Core Properties (MUST) section with single-use, time-bound, recipient binding, and max amount enforcement requirements - Add Out of Scope section clarifying what upto does NOT support - Remove invalid use cases: streaming, time-based access, API rate metering - Clarify remaining use cases as single-request patterns Addresses PR feedback from @phdargen and @notorious-d-e-v * docs(upto): rename settledAmount to amount in SettlementResponse Rename for consistency with planned addition of amount field to base SettlementResponse schema in x402-specification-v2.md (per PR feedback) * docs(upto): clarify phase-dependent amount semantics in PaymentRequirements The amount field in PaymentRequirements has different semantics at verify vs settle time for the upto scheme. At verification, it represents the max authorized amount. At settlement, it represents the actual amount to settle. This was ambiguous in the spec and is now explicitly documented across scheme_upto.md, scheme_upto_evm.md, and the main x402 v2 spec.
* 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
* py fix for 1176 * fix settle response body * same for go/py * fix format
* fix(stellar): include feeBumpSigner in getSigners response The /facilitator/supported endpoint was not returning the feeBumpSigner address alongside regular signer addresses. This meant clients couldn't discover the fee bump signer via the supported endpoint. getSigners() now appends the feeBumpSigner address when configured, with a guard to prevent duplicates if it's also a regular signer. * refactor(stellar): unify getExtra and getSigners tests into facilitator-accessors Merge facilitator-getExtra.test.ts and facilitator-getSigners.test.ts into a single facilitator-accessors.test.ts, eliminating duplicate imports, mocks, and setup.
* 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
* fix stellar e2e config * fix stellar next e2e
* updated changeset * chore: version typescript packages * updated changelogs
* chore: version typescript packages * fix format
* Add Writing hub and batch settlement blog post * style(site): format tsconfig.json with Prettier
* add batch-settlement blog post * add img
* Create TSC.md Create TSC.md outlining the technical steering committee members as outlined by the x402 foundation charter. * Fix spelling --------- Co-authored-by: Erik <erikreppel@gmail.com>
* Add escrow scheme specification Introduces the `escrow` scheme for x402, built on Base's Commerce Payments Protocol. Supports two settlement paths: authorize (funds held in escrow) and charge (direct to receiver), both refundable post-settlement. Refs: #834, #1011 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Address review feedback on escrow scheme specs - Generalize scheme_escrow.md to be network-agnostic - Tighten verification: strict amount equality, tokenCollector recipient check, settlement simulation - Add error codes section and assetTransferMethod note - Simplify nonce derivation explanation * Rename scheme to commerce and align spec with implementation - Rename escrow → commerce per reviewer feedback - Add expiry fields to PaymentRequirements example - Align expiry field descriptions and example values Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * spec: rename escrow/commerce scheme to authCapture, add EVM payload schema Renames the scheme directory from commerce/ to authCapture/ and rewrites the EVM spec to cover both ERC-3009 and Permit2 payment-collector paths. Key spec additions: - extra field schema (captureAuthorizer, captureDeadline, refundDeadline, feeRecipient, min/maxFeeBps, autoCapture, assetTransferMethod) - Wire format + EIP-712 derivation tables for ERC-3009 and Permit2 - Spec -> on-chain PaymentInfo field mapping (preserves canonical Solidity names so EIP-712 typehash matches the AuthCaptureEscrow contract) - Universal contract addresses block (CREATE2-deterministic) - Verification step list aligned with facilitator implementation: preApprovalExpiry <= captureDeadline <= refundDeadline (>= allowed, matching contract _validatePayment) * spec: use canonical base/commerce-payments addresses Defer to the live deployment from base/commerce-payments@v1.0.0 instead of redeploying via CREATE2. Drop the now-obsolete inline address tables and salt-scheme paragraph; the Canonical Addresses annex now links to the upstream release notes (and Uniswap deployments docs for Permit2), matching scheme_exact_evm.md's third-party 'Canonical Permit2' annex pattern. --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
…2278) The Permit2 erc20-approval client was hardcoding 1_000_000_000 / 100_000_000 as gas fee fallbacks. TypeScript already exposes these as DEFAULT_MAX_FEE_PER_GAS / DEFAULT_MAX_PRIORITY_FEE_PER_GAS in evm/constants; add the matching Python constants and use them. No behavior change. Also adds the first unit tests for sign_erc20_approval_transaction covering the fallback and successful estimate paths.
* add --ignore-scripts * update to pnpm 11 and node 22 * align dep * fix axios headers * pin workflow actions * fix paywall * remove cache from publishing * add hedera publishing * remove e2e workflow * increase minminimumReleaseAge to 3days
* fix uv build * exclude-newer = 3 days
…d fix two→three typo (#2044) The exact-EVM scheme spec documented the extra object only by example, leaving readers unable to tell which fields are required vs conditional vs optional for each of the three asset transfer methods (eip3009, permit2, erc7710). Per-method classification is authoritative in the code but was not documented in the spec. Adds three field-definition blocks (one per assetTransferMethod) after each method's PAYMENT-SIGNATURE example, classifying: - extra.assetTransferMethod - extra.name - extra.version Classification per method: - eip3009: name and version are REQUIRED (needed for transferWithAuthorization signature construction). - permit2: name and version are CONDITIONAL (required when the token supports EIP-2612 for gasless Permit2 approval). - erc7710: name and version are OPTIONAL (not used by delegation- based transfers). Also fixes a stale count: 'one of two asset transfer methods' → 'one of three', since erc7710 was added without updating the summary sentence. Pure documentation. No new fields. No code changes.
…D 181228) support with USDC.e (#2309) Add USDC.e (Bridged USDC) as the default stablecoin for HPP mainnet (chain ID 190415) and HPP Sepolia (chain ID 181228) across all three SDKs: - TypeScript: DEFAULT_STABLECOINS map in @x402/evm + regenerated NETWORK_DECIMALS in @x402/paywall - Go: ChainIDHPP / ChainIDHPPSepolia constants, NetworkConfigs entries - Python: NETWORK_CONFIGS dict in x402.mechanisms.evm Contract details (verified on-chain): - Token: USDC.e (Bridged USDC, FiatTokenV2_2) - Address: 0x401eCb1D350407f13ba348573E5630B83638E30D (identical on both networks) - EIP-712 domain: name="Bridged USDC", version="2" - Decimals: 6 - EIP-3009: transferWithAuthorization supported Chain details: - HPP is an Arbitrum Orbit L2 operated by the HPP team - Mainnet (190415): https://mainnet.hpp.io | Explorer: https://explorer.hpp.io - Sepolia (181228): https://sepolia.hpp.io | Explorer: https://sepolia-explorer.hpp.io - Portal: https://portal.hpp.io USDC.e is the official bridged USDC issued by HPP, submitted by the HPP chain team (chain-endorsed asset per DEFAULT_ASSETS.md).
Generated-By: mintlify-agent Mintlify-Source: dashboard-editor Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
* Fix: invoke lifecycle hooks in payment payload creation * fix: invoke lifecycle hooks with correct context types in V1 and V2 * fix: suppress unhandled hook errors to satisfy errcheck linter * fix: handle hook errors and recovery on payment creation failure
* spec: added reference spec * feat: added x402BatchSettlement contract * feat: added tests * feat: mining 0x4020...0003 vanity & deploy to base sepolia * feat: updaded spec/contract per recommendations * feat: updated tests * feat: update x402BatchSettlement * feat: add peripheral contracts * feat: updated spec * feat: updated tests and deploy * feat: removed extra.receiver from spec * spec v1.2 (#44) * feat: added 4th deposit; renamed others * feat: updated tests * feat: add collectors model * feat: removed periphery contracts * feat: rename cooperativeWithdraw to refund * feat: added multicall to x402BatchSettlement for migration support * feat: added multichannel & migration test scenarios * feat: add deploy for peripery contracts * feat: pr feedback * feat: pr review feedback * feat: update settlement tye from address to x402BatchSettlement * feat: generate EIP3009 nonces from channelId & salt * feat: removed DOS vector for withdrawals * feat: deduplicate token/amount from permit2 call data * feat: using ReentrancyGuardTransient over ReetrancyGuard for gas efficiency * feat: added comment regarding unsupported tokens * feat: added nonces to refund signature * feat: updated CLAIM_BATCH_TYPEHASH to use full EIP-712 nested types * feat: merge Permit2DepositCollector's into one contract * feat: gate finalizeWithdraw to payer/payerAuthorizer * feat: added partial refunds * feat: updated spec * fix: unit tests & format * feat: revert settlement address from x402BatchSettlement to address type * feat: pr feedback * feat: pr feedback * chore: format * feat: deployed new contracts * feat: final PR reviews + styling doc * feat: pr feedback * feat: re-mine salts * fix: refunds could grief withdrawals * fix: a signature replay attach with refund nonces * fix: add balance check at initiateWithdraw time * fix: removed duplicate code for type hash getters * fix: avoid cross-chain channelId overlap * feat: remine & redeploy contracts to testnet * chore: move deposit events to after balance checks * feat: add nonReentrant modifier to initiateWithdraw * feat: add ChannelClosed event when balance returns to 0 with 0 claims * doc: natspec note for getClaimBatchDigest called with empty array * feat: added gas tests for x402BatchSettlement * feat: removed unused caller param from IDepositCollector.collect * feat: 100% test coverage for batch settlement across branches/functions/statemments/lines * chore: removed batch settlement spec * doc: document claim/finalizeWithdraw details and add x402-batch-settlement-implementers.md * feat: fix Permit2DepositCollector typehash * feat: documenting refund nonce behavior * feat: remine & deploy batch settlement contracts * chore: add audit reports * feat: deployed to base, polygon, arbitrum, world and world-chain * feat: removed old spec --------- Co-authored-by: phdargen <pdargent@icloud.com>
* fix paywall regen for new chains * changeset * fix format * fix paywall
* improve extension readmes * Add extension hook adapters for client and HTTP flows * Make SIWX extension self-register hooks * changeset
* bump next * changeset * fix format * fix lint * fix paywall
* Update docs/extensions/sign-in-with-x.mdx Generated-By: mintlify-agent Mintlify-Source: dashboard-editor * Update docs/extensions/sign-in-with-x.mdx Generated-By: mintlify-agent Mintlify-Source: dashboard-editor * Update docs/extensions/sign-in-with-x.mdx Generated-By: mintlify-agent Mintlify-Source: dashboard-editor * Update docs/extensions/sign-in-with-x.mdx Generated-By: mintlify-agent Mintlify-Source: dashboard-editor --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
* Update docs/advanced-concepts/lifecycle-hooks.mdx Generated-By: mintlify-agent Mintlify-Source: dashboard-editor * Update docs/sdk-features.md Generated-By: mintlify-agent Mintlify-Source: dashboard-editor --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
* add checks for 0 settle/refund amounts * same for go
* specs: add NEAR v2 exact payment scheme spec * address PR1 comment about height vs time for timeout, how we had payer being returned oddly * update PaymentRequirements removing extra field, adding max timeout, clarity on when settlement happens * add clarity about yoctoNEAR deposit and access key verification, and how it applies with delegate actions and proactively added Duplicate Settlement Mitigation section * clarify the attached deposit in metatxs for both native transfer and ft_transfer/ft_transfer_call * improve "Token Transfer Intent and Exactness" about what's prepaid by client and relayer * add section "Implementing Verification with NEAR RPC" * wrap up details on facilitator sponsorship, vulnerability and mitigation sections
…dev framing (#2160) Address forensic review-quorum findings and conform SVM paywall to upstream pattern: - Drop dead solana:TESTNET FAUCET_URLS entry (Circle faucet does not dispense USDC on Solana Testnet; Option B renders "No faucet configured." for any unmapped chain). - Revert all Solana Testnet recognition added by prior refactor pass (SOLANA_NETWORK_REFS.TESTNET constant, getNetworkDisplayName branch, isTestnetNetwork OR-branch). The paywall now recognizes one non-mainnet SVM network — Devnet — matching upstream/main. No SVM dev expects paywall Testnet support; upstream doesn't provide it. - Unify "Need {tokenName} on {chainName}?" copy in SolanaPaywall and AvmPaywall payment-required headers (were hardcoded "USDC"; matches EvmPaywall). Closes #2159
The custom client example referenced process.env.SERVER_URL (undefined in .env-local) and hardcoded /weather, silently falling back to the localhost default. Align with the canonical pattern used by the fetch and axios client examples.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
20 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Tests
Checklist