feat: New Python SDK with v2 support

[CarsonRoscoe]

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]

🟡 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]

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

Project	Deployment	Review	Updated (UTC)
x402	Ready	Preview, Comment	Jan 16, 2026 4:30pm

[phdargen]

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: 904 by @phdargen
• Add extensions & implement bazaar: 929 by @phdargen
• Add e2e Python facilitator: 950 by @phdargen
• Update e2e tests for Solana support in clients, servers, & facilitators: 904 by @phdargen
• Add Python facilitator example: 950 by @phdargen
• Add basic Python middleware examples (fastapi & flask): 879 by @Ilevk
• Add advanced/custom Python middleware examples (fastapi or flask): 952 by @Ilevk
• Add basic Python client examples (httpx & requests): 857 by @1bcMax
• Add advanced/custom Python client examples: 947 and 954 by @1bcMax
• Fix x402HTTPAdapter retry logic: 978 by @Ilevk
• Async support for dynamic route config: 900 by @shuhei0866
• Make framework/client deps optional extras: 901 by @vvsotnikov
• Add v2 paywall support: 953 by @phdargen
• Async lifecycle hooks: 975 by @phdargen
• Update gitdocs: 976 by @manifoldfrs

[1bcMax]

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]

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]

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]

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

[Darjiro]

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

[1bcMax]

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: 904 by @phdargen
• Add extensions & implement bazaar: 929 by @phdargen
• Add e2e Python facilitator
• Update e2e tests for Solana support in clients, servers, & facilitators: 904 by @phdargen
• Add Python facilitator example
• Add basic Python middleware examples (fastapi & flask): 879 by @Ilevk
• Add advanced/custom Python middleware examples (fastapi or flask): @Ilevk
• Add basic Python client examples (httpx & requests): 857 by @1bcMax
• Add advanced/custom Python client examples (httpx or requests) @1bcMax
• Fix x402HTTPAdapter retry logic: @Ilevk
• Async support for dynamic route config: 900 by @shuhei0866
• Make framework/client deps optional extras: 901 by @vvsotnikov
• Add v2 paywall support

@phdargen Since I had finished "Add basic Python client examples (httpx & requests)"[857], I will finish "Add advanced/custom Python client examples (httpx or requests)" later today.

[shuhei0866]

Quick update on my TODO item:

Async support for dynamic route config — PR #900 has been updated with the dual class design (x402HTTPResourceServer / x402HTTPResourceServerSync) based on @CarsonRoscoe's feedback. Ready for review!

General fix: avoid returning raw exception messages to the client. Log the detailed error (including stack trace) on the server, and send back a generic, user-safe message. When you do want to expose a reason, derive it from a controlled source (e.g., well-defined error codes/messages), not from str(e).

Best concrete fix here:

• In the /settle handler, keep logging the full exception for diagnostics, but:
  • For the "aborted" hook path, do not use str(e) directly. Return a generic error message like "Settlement aborted" (or a controlled message), optionally stripping the prefix only if you are sure it’s safe. Given the CodeQL warning, the simplest safe approach is to avoid using the exception text entirely in the response.
  • For the generic error path (raise HTTPException(...)), replace detail=str(e) with a generic message like "Internal server error during settlement".
• To improve server-side debugging, we can add stack-trace logging via traceback.format_exc() in the except block.
• All changes are confined to e2e/facilitators/python/main.py inside the shown code region. We can add a standard-library import (traceback) at the top of the file.

Concretely:

1. Add import traceback alongside the other imports.
2. In the except Exception as e: in settle:
   • Replace print(f"Settle error: {e}") with something like print(f"Settle error: {e}\n{traceback.format_exc()}") to log more detail but keep it server-side.
   • In the "aborted" branch, stop passing through str(e); instead, use a generic, controlled message (e.g., "Settlement aborted").
   • In the final HTTPException, replace detail=str(e) with a generic message (e.g., "Internal server error during settlement").
3. The /supported endpoint is already only sending a generic HTTP 500 message, but it currently uses detail=str(e) as well; however, CodeQL’s highlighted flow is about the /settle response body. To keep the fix focused on the reported issue, we will not alter /supported unless required.

In general, to fix information exposure through exceptions, avoid returning raw exception messages or stack traces to clients. Instead, log the full exception server-side (optionally with stack trace) and return a generic, user-safe error message. For business-logic errors where the client needs specific feedback, define controlled, sanitized messages or error codes rather than using arbitrary exception text.

For this file, the best minimal fix without changing functionality structure is:

• In the settle endpoint:
  • Keep logging the error server-side.
  • For the “aborted” case, return a response with success: False and the same network/transaction fields, but replace errorReason: str(e) with a generic or at least non-technical message such as "Payment aborted" or "Payment aborted due to a client-side condition.".
  • For non-aborted errors, keep raising HTTPException(status_code=500, ...) but change detail=str(e) to a generic string such as "Internal server error" so exception details are not leaked.
• In the supported endpoint:
  • Keep logging the error.
  • Change HTTPException(status_code=500, detail=str(e)) to use a generic message like "Internal server error".

No new imports are strictly necessary beyond what is already present; we can continue to use print for minimal logging as in the existing code. If this project later adopts a logging framework, these print calls can be replaced, but we won’t assume that here.

Concretely:

• Edit the except block in settle (lines 185–197) to:
  • Use a generic errorReason string in the aborted branch.
  • Use a generic detail in HTTPException.
• Edit the except block in supported (lines 223–225) to use a generic detail.

In general, the fix is to avoid returning raw exception details to the client. Instead, log the exception on the server (ideally with stack trace) and return a generic, non-sensitive error message in the HTTP response body.

For this specific code, the best minimal fix without changing existing functionality is:

• Keep catching Exception to avoid breaking behavior.
• Add server-side logging of the exception (including stack trace), using the standard library logging module.
• Replace the "message": str(e) field in the JSON response with a generic, stable string that does not depend on the exception content (for example, "An internal error occurred while processing payment.").
• Optionally, keep the existing "error": "Payment Processing Error" field for clients that expect it.

Concretely:

1. At the top of examples/python/servers/custom/main.py, add import logging and configure a module-level logger (e.g., logger = logging.getLogger(__name__)). If you want more explicit logs without altering global configuration, you can rely on default logging setup; this change does not break existing behavior.

2. In the except Exception as e: block starting at line 233, replace the print(f"❌ Payment processing error: {e}") call with a logging call like logger.exception("Payment processing error"), which logs the message and stack trace.

3. In the same block, change the JSONResponse content to not include str(e). For example:

content={
    "error": "Payment Processing Error",
    "message": "An internal error occurred while processing payment.",
}

This preserves the external API shape (error and message fields) while eliminating exposure of exception details.