Skip to content

Conversation

@CarsonRoscoe
Copy link
Contributor

@CarsonRoscoe CarsonRoscoe commented Dec 22, 2025

Description

  • Moved the original Python SDK to /python/legacy
  • Added a new Python SDK under /python/x402
  • Implemented the EVM mechanism
  • Implement fastapi & flask middleware
  • Implemented httpx and request clients
  • Added to e2e tests

TODO for Typescript/Go Parity:

  • Add Solana mechanism
  • Add extensions & implement bazaar
  • Add e2e Python facilitator
  • Add Python facilitator example
  • Add Python middleware examples (fastapi & flask)
  • Add Python client examples (httpx & requests)
  • Code reviews (this is just the initial draft)

Tests

📊 Test Summary
==============
✅ Passed: 27
❌ Failed: 0
📈 Total: 27

📋 Detailed Test Results
========================

✅ PASSED TESTS:

  # 1: axios → express → /protected
      Facilitator: go | Network: eip155:84532 | Tx: 0x0534ec75...
  # 2: axios → express → /protected-svm
      Facilitator: go | Network: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 | Tx: 5kARofdupH...
  # 3: go-http → express → /protected
      Facilitator: go | Network: eip155:84532 | Tx: 0x1053f3c6...
  # 4: go-http → express → /protected-svm
      Facilitator: go | Network: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 | Tx: 36i42qEXFG...
  # 5: httpx → express → /protected
      Facilitator: go | Network: eip155:84532 | Tx: 0x4918546e...
  # 6: httpx → express → /protected-svm
      Facilitator: go | Network: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 | Tx: 25j365qnm5...
  # 7: requests → express → /protected
      Facilitator: go | Network: eip155:84532 | Tx: 0x1669a426...
  # 8: requests → express → /protected-svm
      Facilitator: go | Network: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 | Tx: 2JwdEtn5k2...
  # 9: axios → express → /protected
      Facilitator: python | Network: eip155:84532 | Tx: e4a31a3de2...
  #10: axios → express → /protected-svm
      Facilitator: python | Network: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 | Tx: 4mN3qAjRGi...
  #11: axios → express → /protected
      Facilitator: typescript | Network: eip155:84532 | Tx: 0x431b8928...
  #12: axios → express → /protected-svm
      Facilitator: typescript | Network: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 | Tx: ToxyPsu1Ba...
  #13: axios → fastapi → /protected
      Facilitator: go | Network: eip155:84532 | Tx: 0x297549a8...
  #14: axios → fastapi → /protected-2
      Facilitator: go | Network: eip155:84532 | Tx: 0xf01a5f87...
  #15: axios → fastapi → /protected-svm
      Facilitator: go | Network: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 | Tx: QafX7Va53P...
  #16: axios → flask → /protected
      Facilitator: go | Network: eip155:84532 | Tx: 0x64ff53ac...
  #17: axios → flask → /protected-svm
      Facilitator: go | Network: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 | Tx: 2qY3vghP4y...
  #18: axios → gin → /protected
      Facilitator: go | Network: eip155:84532 | Tx: 0x9380bb4f...
  #19: axios → gin → /protected-svm
      Facilitator: go | Network: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 | Tx: 4ue6XGsSJb...
  #20: axios → legacy-fastapi → /protected
      Facilitator: go | Network: base-sepolia | Tx: 0x0b0b1a1f...
  #21: axios → legacy-fastapi → /protected-2
      Facilitator: go | Network: base-sepolia | Tx: 0x8f6f2bd1...
  #22: go-http → legacy-fastapi → /protected
      Facilitator: go | Network: base-sepolia | Tx: 0x3cd54af0...
  #23: legacy-httpx → legacy-fastapi → /protected
      Facilitator: go | Network: base-sepolia | Tx: 0x5f359b48...
  #24: legacy-requests → legacy-fastapi → /protected
      Facilitator: go | Network: base-sepolia | Tx: 0xc5372eaa...
  #25: axios → legacy-fastapi → /protected
      Facilitator: python | Network: base-sepolia | Tx: 140035466e...
  #26: axios → legacy-fastapi → /protected
      Facilitator: typescript | Network: base-sepolia | Tx: 0x3f3fee7f...
  #27: axios → legacy-flask → /protected
      Facilitator: go | Network: base-sepolia | Tx: 0x39d037e4...

📊 Breakdown by Facilitator:
   go              ✅ 21 / ❌ 0 (100%)
   python          ✅ 3 / ❌ 0 (100%)
   typescript      ✅ 3 / ❌ 0 (100%)

📊 Breakdown by Server:
   express              ✅ 12 / ❌ 0 (100%)
   fastapi              ✅ 3 / ❌ 0 (100%)
   flask                ✅ 2 / ❌ 0 (100%)
   gin                  ✅ 2 / ❌ 0 (100%)
   legacy-fastapi       ✅ 7 / ❌ 0 (100%)
   legacy-flask         ✅ 1 / ❌ 0 (100%)

📊 Breakdown by Client:
   axios                ✅ 18 / ❌ 0 (100%)
   go-http              ✅ 3 / ❌ 0 (100%)
   httpx                ✅ 2 / ❌ 0 (100%)
   requests             ✅ 2 / ❌ 0 (100%)
   legacy-httpx         ✅ 1 / ❌ 0 (100%)
   legacy-requests      ✅ 1 / ❌ 0 (100%)

📊 Protocol Family Breakdown:
   EVM: ✅ 18 / ❌ 0 / 📈 18 total
   SVM: ✅ 9 / ❌ 0 / 📈 9 total

Checklist

  • I have formatted and linted my code
  • All new and existing tests pass
  • My commits are signed (required for merge) -- you may need to rebase if you initially pushed unsigned commits

@cb-heimdall
Copy link

cb-heimdall commented Dec 22, 2025

✅ Heimdall Review Status

Requirement Status More Info
Reviews 1/1
Denominator calculation
Show calculation
1 if user is bot 0
1 if user is external 0
2 if repo is sensitive 0
From .codeflow.yml 1
Additional review requirements
Show calculation
Max 0
0
From CODEOWNERS 0
Global minimum 0
Max 1
1
1 if commit is unverified 0
Sum 1

@vercel
Copy link

vercel bot commented Dec 22, 2025

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Review Updated (UTC)
x402 Ready Ready Preview, Comment Jan 21, 2026 10:43pm

Request Review

@phdargen
Copy link
Contributor

phdargen commented Dec 22, 2025

Awesome, thanks a lot for putting this out @CarsonRoscoe!

To everyone interested in contributing, please FIRST write a comment here with what you'd like to work on in order to avoid any duplicate work. I will coordinate and update the TODO below with who is working on what.

To simplify review, please open one PR per TODO item and try to keep changes strictly related to that to avoid merge conflicts.

TODO:

@phdargen phdargen self-assigned this Dec 22, 2025
@1bcMax
Copy link
Contributor

1bcMax commented Dec 22, 2025

TODO:

-[ ] Add Solana mechanism -[ ] Add extensions & implement bazaar -[ ] Add e2e Python facilitator -[ ] Update e2e tests for Solana support in clients, servers, & facilitators -[ ] Add Python facilitator example -[ ] Add Python middleware examples (fastapi & flask): @Ilevk adding fastapi example -[ ] Add Python client examples (httpx & requests)

Awesome, thanks a lot for putting this out @CarsonRoscoe!

To everyone interested in contributing, please FIRST write a comment here with what you'd like to work on in order to avoid any duplicate work. I will coordinate and update the TODO below with who is working on what.

To simplify review, please open one PR per TODO item and try to keep changes strictly related to that to avoid merge conflicts.

TODO:

-[ ] Add Solana mechanism
-[ ] Add extensions & implement bazaar
-[ ] Add e2e Python facilitator
-[ ] Update e2e tests for Solana support in clients, servers, & facilitators
-[X] Add Python facilitator example (@bc1max adding facilitator example)
-[ ] Add Python middleware examples (fastapi & flask): @Ilevk adding fastapi example
-[X ] Add Python client examples (httpx & requests)(@bc1max adding Python client example)

I will work on Python facilitator example and Python client examples (httpx & requests)

Please let me know if you are okay with it @CarsonRoscoe

@phdargen
Copy link
Contributor

Hi @1bcMax, thanks a lot for for offering your help! Let's start with one python client example (httpx) and then go from there. Updated the TODO list accordingly

@Cybercentry
Copy link
Contributor

Happy to review the code and examples for security issues, including both manual checks and static analysis. Please let me know if you’d like me to take a look!

@Ilevk
Copy link
Contributor

Ilevk commented Dec 27, 2025

Awesome, thanks a lot for putting this out @CarsonRoscoe!

To everyone interested in contributing, please FIRST write a comment here with what you'd like to work on in order to avoid > any duplicate work. I will coordinate and update the TODO below with who is working on what.

To simplify review, please open one PR per TODO item and try to keep changes strictly related to that to avoid merge conflicts.

Thanks @phdargen I'd love to contribute the examples.

TODO:

  • Add Python middleware examples (fastapi & flask): @Ilevk adding fastapi example
  • Add advanced/custom Python middleware examples (fastapi or flask): @Ilevk
  • Fix x402HTTPAdapter retry logic: @Ilevk

Ilevk added a commit to Daehan-Base/awesome-x402-on-base that referenced this pull request Dec 27, 2025
Add link to in-progress Python v2 SDK work (coinbase/x402#841)
in Python documentation files.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Ilevk added a commit to Daehan-Base/awesome-x402-on-base that referenced this pull request Dec 27, 2025
* refactor: reorganize directory structure to language-first pattern

Reorganize examples/ and docs/korean/ directories to match
the official x402 repository structure (language/version/type).

Changes:
- examples/v1/ → examples/python/v1/
- examples/v2/ → examples/python/v2/
- docs/korean/v1/ → docs/korean/python/v1/
- docs/korean/v2/ → docs/korean/python/v2/
- Remove python- prefix from example doc filenames
- Update all README path references
- Update CLAUDE.md directory structure section

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: convert external paths to official GitHub links

- Replace local external/x402/ paths with GitHub repository links
- Updated files:
  - examples/README.md, README.en.md
  - examples/python/v2/README.md, README.en.md
  - docs/korean/python/v1/README.md, README.en.md
  - docs/korean/python/v2/README.md, README.en.md
  - docs/korean/getting_started.ko.md
  - docs/korean/python/v1/examples/*.ko.md (4 files)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: docs language-first structure with TypeScript versioning

- Move docs/korean/ to docs/ (language-agnostic root)
- Add TypeScript v1/v2 versioning structure
- Create TypeScript index README and v1 placeholder
- Convert external paths to GitHub links in TypeScript docs
- Fix Python v1 internal links (remove python- prefix)
- Fix Python v1 examples relative paths for new structure
- Add TypeScript documentation links to docs/README.md

Directory structure:
docs/
├── python/v1/examples/  (Python v1 Legacy)
├── python/v2/           (Python v2)
├── typescript/v1/       (placeholder)
├── typescript/v2/       (TypeScript v2 examples)
└── getting_started.ko.md, x402-v2-specification.ko.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: update broken links in getting_started.ko.md after restructure

- Update Python example paths: ./v1/examples/python-* → ./python/v1/examples/*
- Fix resources relative path: ../../resources/ → ../resources/

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* style: add footer navigation to TypeScript v2 docs and update README structure

- Add footer navigation to all TypeScript v2 example README files
- Update main README directory structure diagram to reflect current layout
- Fix broken links in README.md and README.en.md (docs/korean/ → docs/)
- Update example links to new language-first structure

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: resolve 4-persona review issues (Phase 1-3)

Critical fixes:
- Fix 4 broken links in x402-v2-specification.ko.md (wrong path + filename)
- Add TypeScript v2 Quick Start section to root README

High priority fixes:
- Create docs/python/README.md and README.en.md
- Create docs/typescript/v2/fullstack/README.md and README.en.md
- Fix docs/README.md relative path (../../README.md → ../README.md)
- Fix korean-community broken link in getting_started.ko.md

Medium priority fixes:
- Fix Python v1 examples v2-spec links (4 files)
- Add English footer navigation to TypeScript v2 docs (15 files)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: resolve broken links from final review

- Fix LICENSE links in x402-v2-specification.ko.md and getting_started.ko.md
  (../../LICENSE → ../LICENSE)
- Fix v2-spec links in python/v2/README.md and README.en.md
  (../x402-v2-specification.ko.md → ../../x402-v2-specification.ko.md)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: restructure Python v1 docs from examples/ to feature-based dirs

- Move examples/*.ko.md to clients/, servers/, discovery/ directories
- Rename all files to README.md for consistency
- Update all internal links across 14 files to match new structure
- Fix broken links in root READMEs, docs/, and external/ directories

New structure:
  docs/python/v1/
  ├── clients/requests/README.md
  ├── clients/httpx/README.md
  ├── servers/fastapi/README.md
  └── discovery/README.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* style: add language toggle linking to official x402 examples

Add language toggle at the top of Python v1 docs with English links
pointing to official coinbase/x402 repository examples instead of
maintaining separate English translations.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: update repository structure to reflect Python v1 reorganization

Update docs/python/v1/ structure in both README files to show
new feature-based directory layout (clients/, servers/, discovery/).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: reorganize external/ README with language versions

- Update README.md as Korean default
- Add README.en.md for English version
- Remove redundant README.ko.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: simplify docs paths and rename getting_started

- Remove 'korean' from docs path (docs/korean/ → docs/)
- Rename getting_started.ko.md to getting_started.md
- Update all references across 14 files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: add official code links to TypeScript examples table

Add links to official coinbase/x402 repository for all TypeScript v2
examples (axios, fetch, express, hono, next, miniapp, mcp).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: rename x402-v2-specification.ko.md to .md

Remove '.ko' suffix from v2 specification filename and update
all references across 15 files for consistency.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: update v1/examples/ references to new v1/ structure

Update paths across 8 files to reflect the new directory structure:
- docs/python/v1/examples/ → docs/python/v1/ (clients/, servers/, discovery/)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: add English README.en.md for Python v1 examples

- Create English versions for 4 Python v1 docs:
  - clients/requests/README.en.md
  - clients/httpx/README.en.md
  - servers/fastapi/README.en.md
  - discovery/README.en.md
- Update Korean READMEs with correct language toggle links
- Fix footer navigation paths (../ → ../../ for nested dirs)
- Fix v2-spec relative paths

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: add Python v2 SDK PR #841 reference

Add link to in-progress Python v2 SDK work (coinbase/x402#841)
in Python documentation files.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
@Darjiro
Copy link

Darjiro commented Dec 27, 2025

Hi guys, I just opened a PR. It's just a specific example for the CDP facilitator on Mainnet to serve as a workaround until cdp-sdk is updated. #874

@phdargen
Copy link
Contributor

Happy to review the code and examples for security issues, including both manual checks and static analysis. Please let me know if you’d like me to take a look!

Sure @Cybercentry, testing the code and reviewing the code would be appreciated

@vvsotnikov
Copy link
Contributor

Hello, I opened #901 to make framework/client deps optional extras (more scalable, avoids dep conflicts)

@Olshansk
Copy link
Contributor

Olshansk commented Jan 5, 2026

Thanks for pushing this along!

CarsonRoscoe and others added 7 commits January 21, 2026 14:15
* fix format

* fix lint

* fix build

* fix pytest
…902)

- Add missing imports (base64, json, Response, JSONResponse, PaymentPayload, FacilitatorClient)
- Fix function signature syntax error
- Fix dict initialization syntax (colon to equals)
- Add missing return statement after successful payment
- Remove trailing whitespace
* feat: add fastapi example project configuration

* feat: add fastapi example with x402 payment middleware

* docs: add comprehensive README for fastapi example

* feat: add flask example project configuration

* feat: add flask example with x402 payment middleware

* docs: add comprehensive README for flask example

* feat: add test clients for fastapi and flask examples

* docs: add test client usage to READMEs

* chore - remove python-version and test-client.py

* docs - remove test client guide from README.md

* chore - remove license and classifier

* feat - add description and mime type

* feat - update .env-local
* feat: add Python v2 client examples (httpx & requests)

Add simple client examples demonstrating httpx (async) and requests (sync) usage with the x402 Python v2 SDK.

- examples/python/clients/example.py - Simple example showing both httpx and requests
- Uses EthAccountSigner with register_exact_evm_client helper
- Minimal configuration required

* refactor: split Python client examples into separate directories

Address PR review feedback:
- Separate httpx/ and requests/ directories
- Add pyproject.toml for uv sync support
- Add environment variable validation
- Add payment response header extraction
- Use context manager for requests session cleanup

Tested on Base Sepolia testnet:
- httpx: tx 0xce49f668aba01c4b0b1af2eb0d9a381f4c62295506a91f20af479e0e834ef350
- requests: tx 0xb83b6feefa5a744b7779ba5b37df33f9c7241f58119454d66102acd97a92f024

* Update examples/python/clients/httpx/main.py

Co-authored-by: phdargen <pdargent@icloud.com>

* Update examples/python/clients/requests/main.py

Co-authored-by: phdargen <pdargent@icloud.com>

---------

Co-authored-by: phdargen <pdargent@icloud.com>
phdargen and others added 13 commits January 21, 2026 14:17
* add svm mechanism

* add unit tests

* add integration tests

* update server examples

* add e2e tests

* update clients

* make EVM/SVM dependencies optional extras

* fix legacy uv paths
* add bazaar extension

* strip query params for discovery

* fix 862

* updated e2e tests
* Add advanced Python client examples

Implements 5 advanced patterns demonstrating x402 SDK v2 features:
- hooks.py: Payment lifecycle hooks (before, after, failure)
- preferred_network.py: Custom network preference selector
- builder_pattern.py: Network-specific registration with wildcards
- error_recovery.py: Error classification and recovery strategies
- custom_transport.py: Custom httpx transport with retry/timing

Includes:
- CLI entry point (index.py) for running examples
- Comprehensive test suite (40 unit tests)
- E2E integration tests
- README documentation

All tests passing.

* Remove tests and examples beyond TypeScript SDK parity

Address PR review feedback:
- Remove tests directory (tests belong in SDK, not examples)
- Remove custom_transport.py (runtime error, beyond TS parity)
- Remove error_recovery.py (duplicate of hooks.py, beyond TS parity)
- Update index.py, README.md, pyproject.toml accordingly

* Address PR feedback: add SVM support and use optional deps

- Update pyproject.toml to use x402[evm,svm,httpx] instead of
  listing dependencies separately
- Add Solana/SVM network examples to preferred_network.py
- Support both EVM and SVM signers for cross-chain flexibility
- Update .env-local with SOLANA_PRIVATE_KEY option
* add facilitator example

* improve svm signer

* add description to DiscoveredResource

* add facilitator e2e
Demonstrates manual x402 v2 payment flow without convenience wrappers.

Shows the 6-step process:
1. Initialize client and register payment schemes
2. Make initial request, receive 402
3. Decode PAYMENT-REQUIRED header
4. Create signed payment payload
5. Retry with PAYMENT-SIGNATURE header
6. Handle success/failure response

Useful for integrating with non-standard HTTP libraries or implementing
custom retry logic.
* feat(http): implement dual class design for sync/async support

- Add x402HTTPResourceServer (async) for FastAPI/Starlette
- Add x402HTTPResourceServerSync (sync) for Flask/Django
- Share common logic via _x402HTTPServerBase
- Remove dynamic description/resource (keep only dynamic price/payTo)
- Update Flask middleware to use sync server directly
- Integrate with enrich_extensions for bazaar support
- Add per-route hook_timeout_seconds configuration

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(types): add missing Awaitable import and fix test import sorting

- Add Awaitable import to types.py for DynamicPayTo/DynamicPrice type hints
- Fix import block sorting in test_async_hooks.py and test_core.py

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: simplify API by removing unused types and making timeout opt-in

Address reviewer feedback from @phdargen:
- Remove SyncDynamicPayTo/SyncDynamicPrice (unused types that would require SyncPaymentOption to be useful)
- Change hook_timeout_seconds default to None (opt-in, matching TS/Go parity)
- Export x402HTTPResourceServerSync from http/__init__.py

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
)

* make create_facilitator_config work with both V1 and V2

* fix lint
* feat - add pyproject.toml, uv.lock for advanced example

* feat - add bazaar extension

* feat - add hooks

* feat - add x402 extensions to pyproject.toml

* feat - add dynamic pricing feature

* feat - add dynamic pay-to and custom money parser features

* docs - add README for advanced server example

* style - apply lint

* chore - add comments for bazaar extension code
* fix: fix consecutive payment bug in x402HTTPAdapter

- Replace instance-level _is_retry flag with per-request header
  to prevent state leakage between consecutive 402 requests.

* tests - add test case for consecutive payment with x402HTTPAdapter

* style - apply lint
* add dual sync/async classes for server/client/facilitator

* update integration/e2e tests

* add unit tests for core, http and implement wrapHttpxWithPaymentFromConfig/wrapRequestsWithPayment

* refactor core server/client/facilitator

* refactor x402_http_server/facilitator_client/x402_http_client

* update exmamples

* add utility function that takes care of html-safe escaping

* add sdk readmes

* add retry unit tests to httpx client
* Porting docs and updating for v2 changes (#813)

* porting docs and updating for v2 changes

* update quickstart for sellers

* update quickstarts, miniapps, and mcp docs

* update doc links

* update FAQs

* fix getting started docs

* update core concepts

* remove miniapps guide

* update extensions

* fix bazaar code examples

* fix broken links and yaml file

* remove unnecessary protocol layer doc

* add migration guide

* update documentation for python v2 sdk

* testing pr preview

* docs(python): remove unused os imports and align with TS tab patterns

- Remove unused 'import os' from FastAPI and Flask examples in quickstart-for-sellers
- Update bazaar-discovery-layer Python example to use hardcoded '0xYourPrivateKey' to match TypeScript tab consistency

* update migration doc

* cleanup comments

* cleanup readme
Copy link
Contributor

@apmcdermott apmcdermott left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚀 🐍

@CarsonRoscoe CarsonRoscoe merged commit 30a847d into main Jan 22, 2026
26 checks passed
arditti pushed a commit to arditti/x402 that referenced this pull request Jan 22, 2026
* chore: renamed python/x402 to python/legacy

* feat: initial Python core SDK

* feat: added core HTTP wrappers

* feat: added core types

* feat: added evm mechanism for exact v1/v2

* feat: added httpx client

* feat: added requests client

* feat: added fastapi middleware

* feat: added flask middleware

* feat: added integration tests

* feat: added Python SDK to e2e tests

* python-v2: fix workflow checks (coinbase#863)

* fix format

* fix lint

* fix build

* fix pytest

* Fix syntax errors and missing imports in manual integration example (coinbase#902)

- Add missing imports (base64, json, Response, JSONResponse, PaymentPayload, FacilitatorClient)
- Fix function signature syntax error
- Fix dict initialization syntax (colon to equals)
- Add missing return statement after successful payment
- Remove trailing whitespace

* feat: add Python SDK v2 server examples (FastAPI, Flask)  (coinbase#879)

* feat: add fastapi example project configuration

* feat: add fastapi example with x402 payment middleware

* docs: add comprehensive README for fastapi example

* feat: add flask example project configuration

* feat: add flask example with x402 payment middleware

* docs: add comprehensive README for flask example

* feat: add test clients for fastapi and flask examples

* docs: add test client usage to READMEs

* chore - remove python-version and test-client.py

* docs - remove test client guide from README.md

* chore - remove license and classifier

* feat - add description and mime type

* feat - update .env-local

* feat: add Python v2 client examples (httpx & requests) (coinbase#857)

* feat: add Python v2 client examples (httpx & requests)

Add simple client examples demonstrating httpx (async) and requests (sync) usage with the x402 Python v2 SDK.

- examples/python/clients/example.py - Simple example showing both httpx and requests
- Uses EthAccountSigner with register_exact_evm_client helper
- Minimal configuration required

* refactor: split Python client examples into separate directories

Address PR review feedback:
- Separate httpx/ and requests/ directories
- Add pyproject.toml for uv sync support
- Add environment variable validation
- Add payment response header extraction
- Use context manager for requests session cleanup

Tested on Base Sepolia testnet:
- httpx: tx 0xce49f668aba01c4b0b1af2eb0d9a381f4c62295506a91f20af479e0e834ef350
- requests: tx 0xb83b6feefa5a744b7779ba5b37df33f9c7241f58119454d66102acd97a92f024

* Update examples/python/clients/httpx/main.py

Co-authored-by: phdargen <pdargent@icloud.com>

* Update examples/python/clients/requests/main.py

Co-authored-by: phdargen <pdargent@icloud.com>

---------

Co-authored-by: phdargen <pdargent@icloud.com>

* feat(python): Make v2 framework and client dependencies optional extras (coinbase#901)

* python-v2: add svm mechanism (coinbase#904)

* add svm mechanism

* add unit tests

* add integration tests

* update server examples

* add e2e tests

* update clients

* make EVM/SVM dependencies optional extras

* fix legacy uv paths

* V2 python bazaar (coinbase#929)

* add bazaar extension

* strip query params for discovery

* fix 862

* updated e2e tests

* Add advanced Python client examples (coinbase#947)

* Add advanced Python client examples

Implements 5 advanced patterns demonstrating x402 SDK v2 features:
- hooks.py: Payment lifecycle hooks (before, after, failure)
- preferred_network.py: Custom network preference selector
- builder_pattern.py: Network-specific registration with wildcards
- error_recovery.py: Error classification and recovery strategies
- custom_transport.py: Custom httpx transport with retry/timing

Includes:
- CLI entry point (index.py) for running examples
- Comprehensive test suite (40 unit tests)
- E2E integration tests
- README documentation

All tests passing.

* Remove tests and examples beyond TypeScript SDK parity

Address PR review feedback:
- Remove tests directory (tests belong in SDK, not examples)
- Remove custom_transport.py (runtime error, beyond TS parity)
- Remove error_recovery.py (duplicate of hooks.py, beyond TS parity)
- Update index.py, README.md, pyproject.toml accordingly

* Address PR feedback: add SVM support and use optional deps

- Update pyproject.toml to use x402[evm,svm,httpx] instead of
  listing dependencies separately
- Add Solana/SVM network examples to preferred_network.py
- Support both EVM and SVM signers for cross-chain flexibility
- Update .env-local with SOLANA_PRIVATE_KEY option

* Python-v2: facilitator example + e2e (coinbase#950)

* add facilitator example

* improve svm signer

* add description to DiscoveredResource

* add facilitator e2e

* add paywall builder (coinbase#953)

* Add Python custom client example (coinbase#954)

Demonstrates manual x402 v2 payment flow without convenience wrappers.

Shows the 6-step process:
1. Initialize client and register payment schemes
2. Make initial request, receive 402
3. Decode PAYMENT-REQUIRED header
4. Create signed payment payload
5. Retry with PAYMENT-SIGNATURE header
6. Handle success/failure response

Useful for integrating with non-standard HTTP libraries or implementing
custom retry logic.

* feat(v2-sdk): support async dynamic hooks for price and metadata (coinbase#900)

* feat(http): implement dual class design for sync/async support

- Add x402HTTPResourceServer (async) for FastAPI/Starlette
- Add x402HTTPResourceServerSync (sync) for Flask/Django
- Share common logic via _x402HTTPServerBase
- Remove dynamic description/resource (keep only dynamic price/payTo)
- Update Flask middleware to use sync server directly
- Integrate with enrich_extensions for bazaar support
- Add per-route hook_timeout_seconds configuration

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(types): add missing Awaitable import and fix test import sorting

- Add Awaitable import to types.py for DynamicPayTo/DynamicPrice type hints
- Fix import block sorting in test_async_hooks.py and test_core.py

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: simplify API by removing unused types and making timeout opt-in

Address reviewer feedback from @phdargen:
- Remove SyncDynamicPayTo/SyncDynamicPrice (unused types that would require SyncPaymentOption to be useful)
- Change hook_timeout_seconds default to None (opt-in, matching TS/Go parity)
- Export x402HTTPResourceServerSync from http/__init__.py

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

* python-v2: make create_facilitator_config work with both V1 and V2 (coinbase#968)

* make create_facilitator_config work with both V1 and V2

* fix lint

* feat: add Python SDK v2 server advanced example (FastAPI) (coinbase#952)

* feat - add pyproject.toml, uv.lock for advanced example

* feat - add bazaar extension

* feat - add hooks

* feat - add x402 extensions to pyproject.toml

* feat - add dynamic pricing feature

* feat - add dynamic pay-to and custom money parser features

* docs - add README for advanced server example

* style - apply lint

* chore - add comments for bazaar extension code

* fix: python v2 x402HTTPAdapter retry logic (coinbase#978)

* fix: fix consecutive payment bug in x402HTTPAdapter

- Replace instance-level _is_retry flag with per-request header
  to prevent state leakage between consecutive 402 requests.

* tests - add test case for consecutive payment with x402HTTPAdapter

* style - apply lint

* Python-v2: async lifecycle hooks (coinbase#975)

* add dual sync/async classes for server/client/facilitator

* update integration/e2e tests

* add unit tests for core, http and implement wrapHttpxWithPaymentFromConfig/wrapRequestsWithPayment

* refactor core server/client/facilitator

* refactor x402_http_server/facilitator_client/x402_http_client

* update exmamples

* add utility function that takes care of html-safe escaping

* add sdk readmes

* add retry unit tests to httpx client

* Update Python SDK Docs for v2 (coinbase#976)

* Porting docs and updating for v2 changes (coinbase#813)

* porting docs and updating for v2 changes

* update quickstart for sellers

* update quickstarts, miniapps, and mcp docs

* update doc links

* update FAQs

* fix getting started docs

* update core concepts

* remove miniapps guide

* update extensions

* fix bazaar code examples

* fix broken links and yaml file

* remove unnecessary protocol layer doc

* add migration guide

* update documentation for python v2 sdk

* testing pr preview

* docs(python): remove unused os imports and align with TS tab patterns

- Remove unused 'import os' from FastAPI and Flask examples in quickstart-for-sellers
- Update bazaar-discovery-layer Python example to use hardcoded '0xYourPrivateKey' to match TypeScript tab consistency

* update migration doc

* cleanup comments

* cleanup readme

* fix: Python facilitator e2e code

* fix: lint

---------

Co-authored-by: phdargen <p.dargent@cern.ch>
Co-authored-by: somesome <57699892+sohw400@users.noreply.github.com>
Co-authored-by: Logan Kang <kcs93023@gmail.com>
Co-authored-by: 1bcMax <viewitter@gmail.com>
Co-authored-by: phdargen <pdargent@icloud.com>
Co-authored-by: Vladimir Sotnikov <bubert9@gmail.com>
Co-authored-by: Shuhei <shuhei0866@gmail.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Faris Habib <faris.habib@coinbase.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci examples Changes to examples go legacy Changes to legacy sdk or examples python sdk Changes to core v2 packages typescript

Development

Successfully merging this pull request may close these issues.