feat: New Python SDK with v2 support #841

CarsonRoscoe · 2025-12-22T15:48:46Z

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

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 · 2025-12-22T15:48:50Z

🟡 Heimdall Review Status

Requirement Status More Info

Reviews

🟡 0/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 · 2025-12-22T15:48:51Z

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

Project	Deployment	Review	Updated (UTC)
x402	Ready	Preview, Comment	Jan 7, 2026 5:53pm

python/x402/http/middleware/fastapi.py

phdargen · 2025-12-22T17:00:01Z

1bcMax · 2025-12-22T19:14:30Z

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 · 2025-12-23T17:14:55Z

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 · 2025-12-26T18:36:50Z

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 · 2025-12-27T07:24:25Z

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 Python middleware examples (fastapi & flask): @Ilevk adding fastapi example

Add advanced/custom Python middleware examples (fastapi or flask): @Ilevk

Fix x402HTTPAdapter retry logic: @Ilevk

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

TODO:

Add Python middleware examples (fastapi & flask): @Ilevk adding fastapi example
Add advanced/custom Python middleware examples (fastapi or flask): @Ilevk

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>

* 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 · 2025-12-27T22:51:38Z

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

* fix format * fix lint * fix build * fix pytest

phdargen · 2025-12-29T20:28:58Z

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 · 2026-01-03T06:12:56Z

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

…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

Olshansk · 2026-01-05T17:37:41Z

Thanks for pushing this along!

* 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>

…as (#901)

* 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

CarsonRoscoe added 11 commits December 15, 2025 13:09

chore: renamed python/x402 to python/legacy

9fbf113

feat: initial Python core SDK

4d34d2c

feat: added core HTTP wrappers

ef26130

feat: added core types

9425d34

feat: added evm mechanism for exact v1/v2

c6c8c41

feat: added httpx client

a05d61b

feat: added requests client

a05f3a3

feat: added fastapi middleware

9282c88

feat: added flask middleware

cc17b9c

feat: added integration tests

a179009

feat: added Python SDK to e2e tests

db54505

github-advanced-security bot found potential problems Dec 22, 2025

View reviewed changes

python/x402/http/middleware/fastapi.py Dismissed Show dismissed Hide dismissed

phdargen mentioned this pull request Dec 22, 2025

Add FastAPI Example for x402 v2 #805

Closed

phdargen self-assigned this Dec 22, 2025

This was referenced Dec 23, 2025

feat(python): V2 Migration - Strict SDK Compliance and Parity Improvements #827

Closed

feat: Implement Python V2 X402Client class #643

Closed

1bcMax mentioned this pull request Dec 24, 2025

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

Merged

This was referenced Dec 24, 2025

Add Python support for Solana x402 payments with complete client/server implementation and testing. #607

Closed

test(python): add unit tests for path matching utility #850

Closed

Ilevk mentioned this pull request Dec 29, 2025

x402 v2 Action Provider for Python coinbase/agentkit#912

Open

7 tasks

python-v2: fix workflow checks (#863)

1266867

* fix format * fix lint * fix build * fix pytest

vercel bot deployed to Preview December 29, 2025 18:25 View deployment

vercel bot deployed to Preview January 5, 2026 09:20 View deployment

vercel bot deployed to Preview January 5, 2026 15:14 View deployment

phdargen mentioned this pull request Jan 5, 2026

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

Merged

3 tasks

vercel bot deployed to Preview January 5, 2026 20:34 View deployment

feat(python): Make v2 framework and client dependencies optional extr…

348c382

…as (#901)

vercel bot deployed to Preview January 6, 2026 01:17 View deployment

python-v2: add svm mechanism (#904)

fd04ac6

* 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

github-actions bot added sdk Changes to core v2 packages examples Changes to examples python legacy Changes to legacy sdk or examples ci labels Jan 7, 2026

vercel bot deployed to Preview January 7, 2026 17:53 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: New Python SDK with v2 support #841

feat: New Python SDK with v2 support #841

Uh oh!

CarsonRoscoe commented Dec 22, 2025 •

edited

Loading

Uh oh!

cb-heimdall commented Dec 22, 2025 •

edited

Loading

Uh oh!

vercel bot commented Dec 22, 2025 •

edited

Loading

Uh oh!

Uh oh!

phdargen commented Dec 22, 2025 •

edited

Loading

Uh oh!

1bcMax commented Dec 22, 2025 •

edited

Loading

Uh oh!

phdargen commented Dec 23, 2025

Uh oh!

Cybercentry commented Dec 26, 2025

Uh oh!

Ilevk commented Dec 27, 2025 •

edited

Loading

Uh oh!

Darjiro commented Dec 27, 2025

Uh oh!

phdargen commented Dec 29, 2025

Uh oh!

vvsotnikov commented Jan 3, 2026

Uh oh!

Olshansk commented Jan 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

10 participants

feat: New Python SDK with v2 support #841

Are you sure you want to change the base?

feat: New Python SDK with v2 support #841

Uh oh!

Conversation

CarsonRoscoe commented Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Tests

Checklist

Uh oh!

cb-heimdall commented Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟡 Heimdall Review Status

Uh oh!

vercel bot commented Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

phdargen commented Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

1bcMax commented Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

phdargen commented Dec 23, 2025

Uh oh!

Cybercentry commented Dec 26, 2025

Uh oh!

Ilevk commented Dec 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Darjiro commented Dec 27, 2025

Uh oh!

phdargen commented Dec 29, 2025

Uh oh!

vvsotnikov commented Jan 3, 2026

Uh oh!

Olshansk commented Jan 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

10 participants

CarsonRoscoe commented Dec 22, 2025 •

edited

Loading

cb-heimdall commented Dec 22, 2025 •

edited

Loading

vercel bot commented Dec 22, 2025 •

edited

Loading

phdargen commented Dec 22, 2025 •

edited

Loading

1bcMax commented Dec 22, 2025 •

edited

Loading

Ilevk commented Dec 27, 2025 •

edited

Loading