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

Ilevk · 2025-12-29T15:25:03Z

Description

Add FastAPI and Flask example servers demonstrating x402 payment middleware integration.

FastAPI (examples/python/servers/fastapi/)

Payment-gated API server with PaymentMiddlewareASGI
Test client using x402HttpxClient
Comprehensive README with setup and usage guide

Flask (examples/python/servers/flask/)

Payment-gated API server with PaymentMiddleware
Test client using x402HttpxClient
Comprehensive README with setup and usage guide

Both examples include three endpoints:

Endpoint	Payment Required	Price
GET /health	No	-
GET /weather	Yes	$0.01 USDC
GET /premium/content	Yes	$0.01 USDC

Tests

Manually tested both servers with the included test clients:

  cd examples/python/servers/fastapi
  uv sync && uv run python main.py

  # In another terminal
  uv run python test_client.py

  Output:
  Wallet address: 0x...

  --- Testing /health (no payment) ---
  Status: 200

  --- Testing /weather (requires payment) ---
  Status: 200

  --- Testing /premium/content (requires payment) ---
  Status: 200

Flask example tested with identical results.

Linting passed for both:

  uv run ruff check .
  # All checks passed!

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

vercel · 2025-12-29T15:25:09Z

@Ilevk is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

Ilevk · 2025-12-29T15:27:28Z

@phdargen Hi, I hope you're doing well.
I've just create a PR for FastAPI / Flask examples. please take a look when you're available. many thanks!

Note: The examples require removing the following line from python/x402/pyproject.toml:
"extensions" = "x402/extensions"
Otherwise the uv sync fails because the extensions directory doesn't exist.

by the way I found an issue while testing with the example servers: x402HTTPAdapter doesn't retry correctly when calling multiple different paid endpoints sequentially in the same session. The first paid endpoint works (402 → retry → 200), but subsequent different endpoints return 402 without retry.

  Example:
  session.get("/weather")        # 200 ✅
  session.get("/premium/content") # 402 ❌ (no retry)

That's the reason why I've used x402HttpxClient for the test client code, which works correctly in the same scenario.
Let me know if you'd like me to take a look at fixing this.

Ilevk · 2025-12-29T15:44:56Z

I forgot to add transactions that I tested.

Transaction for FastAPI /weather
- https://sepolia.basescan.org/tx/0x04ed017f7feec6612cdd45f572b9acd719769a9db3dfb9e249257b752a8cce23
Transaction for FastAPI /premium/content
- https://sepolia.basescan.org/tx/0x26772699cfc02cd5808c1b9b0ee8e1439e8657693c2b1f6bea84e8569ad51e11
Transaction for Flask /weather
- https://sepolia.basescan.org/tx/0x055bdd5fbb039453295ec322737ae676563b5780b3b8e43178c17ed5d701cf5c
Transaction for Flask /premium/content
- https://sepolia.basescan.org/tx/0xa9f4c66a0090acacce66da588685d30a92cd21a74610a2e7d28275bea4d9cb47

phdargen · 2025-12-29T22:41:01Z

Hi @Ilevk, thanks a lot for your contribution! Could you please rebase against coinbase:feat/python-v2-sdk? This should fix the failing workflow checks and the problem with the extensions in python/x402/pyproject.toml

examples/python/servers/fastapi/.python-version

phdargen · 2025-12-29T23:01:56Z

It's great that you created the test_client.py scripts to test your own implementation but these should not be committed.

Each server example should only include server related code. The servers can then be tested by running any of the client examples (including typescript/go)

phdargen · 2025-12-29T23:08:24Z

by the way I found an issue while testing with the example servers: x402HTTPAdapter doesn't retry correctly when calling multiple different paid endpoints sequentially in the same session. The first paid endpoint works (402 → retry → 200), but subsequent different endpoints return 402 without retry.
  Example:
  session.get("/weather")        # 200 ✅
  session.get("/premium/content") # 402 ❌ (no retry)
That's the reason why I've used x402HttpxClient for the test client code, which works correctly in the same scenario. Let me know if you'd like me to take a look at fixing this.

Good catch, this seems to be the same issue reported here #399. So this bug was already in v1.

Yes, would be great if you could look into it! When you have a fix ready, please open a new PR for this targeting coinbase:feat/python-v2-sdk

Ilevk · 2025-12-30T14:53:18Z

@phdargen I've just done rebase and removing .python-version, test_client.py

And could you set me as an assignee for this PR?

Ilevk · 2025-12-30T14:56:31Z

Good catch, this seems to be the same issue reported here #399. So this bug was already in v1.
Yes, would be great if you could look into it! When you have a fix ready, please open a new PR for this targeting coinbase:feat/python-v2-sdk

You mean that PR 399 would be closed soon?, I'd love to take a look that issue.

Should I create a new Issue about that with referencing original issue or do you want me to just continue with this Issue(#398)?

phdargen · 2025-12-30T17:24:54Z

examples/python/servers/fastapi/.env-local

@@ -0,0 +1 @@
+ADDRESS=


Suggest renaming to EVM_ADDRESS in anticipation of svm mechanism to be added soon and adding facilitator URL

Suggested change

ADDRESS=

EVM_ADDRESS=

FACILITATOR_URL=https://x402.org/facilitator

I've updated files here 7e1f56a

phdargen · 2025-12-30T17:36:07Z

examples/python/servers/flask/pyproject.toml

+name = "x402-v2-flask-example"
+version = "0.1.0"


Not sure what name and version convention we should use here, will check with @CarsonRoscoe once he is back

phdargen · 2025-12-30T17:37:01Z

examples/python/servers/flask/pyproject.toml

+version = "0.1.0"
+description = "Example of using a Flask server with x402 middleware"
+readme = "README.md"
+license = { text = "MIT" }


x402 uses Apache-2.0, not MIT. We don't have license in other examples, maybe better to just remove

I've removed it here 0ff914c

phdargen · 2025-12-30T17:37:27Z

examples/python/servers/flask/pyproject.toml

+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]


I think classifiers is not needed

I've removed it here 0ff914c

phdargen · 2025-12-30T17:43:09Z

examples/python/servers/fastapi/main.py

+        accepts=[
+            PaymentOption(
+                scheme="exact",
+                pay_to=ADDRESS,
+                price="$0.01",
+                network=NETWORK,
+            )
+        ]


Suggest to add description and mime_type to each endpoint

Suggested change

accepts=[

PaymentOption(

scheme="exact",

pay_to=ADDRESS,

price="$0.01",

network=NETWORK,

)

]

accepts=[

PaymentOption(

scheme="exact",

pay_to=ADDRESS,

price="$0.01",

network=NETWORK,

)

]

description="Weather report",

mime_type="application/json",

I've added descriptions and mime_type, here d905e0b

phdargen · 2025-12-30T17:53:36Z

Thanks @Ilevk, the examples look good! Just a few minor comments, see above

phdargen · 2025-12-30T17:53:44Z

Once the svm mechanism is ready, we might want to add a solana PaymentOption as well

phdargen · 2025-12-30T17:59:18Z

For typescript v2 we also have advanced examples that show usage of bazaar (not yet implemented for python), hooks, dynamic price/payTo and custom money definition.

Would be nice to add this for python as well (as much as currently possible), you can pick either fastapi or flask to implement this as you prefer

phdargen · 2025-12-30T18:01:49Z

Another thing would be a custom example that demonstrates how to implement x402 payment handling manually without using pre-built middleware packages

phdargen · 2025-12-30T18:15:48Z

Good catch, this seems to be the same issue reported here #399. So this bug was already in v1.
Yes, would be great if you could look into it! When you have a fix ready, please open a new PR for this targeting coinbase:feat/python-v2-sdk

You mean that PR 399 would be closed soon?, I'd love to take a look that issue.

Should I create a new Issue about that with referencing original issue or do you want me to just continue with this Issue(#398)?

PR 399 is quite old and seems inactive, so likely we will have to close it. In any case, PR 399 targets the legacy implementation. The most important thing is that we fix it for the new v2 implementation.

So as a first step, I would suggest you open a new PR targeting the coinbase:feat/python-v2-sdk branch with the fix for the v2 implementation only.
No need to open a new issue or reference an existing one as python v2 in not live yet, just in development.

We can then decide later if and how we fix the legacy implementation as well

Ilevk · 2025-12-31T11:28:37Z

Let me check the other comments tomorrow. thanks for comments Happy new year!

For typescript v2 we also have [advanced examples (https://github.com/coinbase/x402/tree/main/examples/typescript/servers/advanced) that show usage of bazaar (not yet implemented for python), hooks, dynamic price/payTo and custom money definition.
Would be nice to add this for python as well (as much as currently possible), you can pick either fastapi or flask to implement this as you prefer

Ilevk · 2026-01-05T14:33:03Z

Hi @phdargen, I've been thinking about an advanced example. I'd be nice to contribute. but should I put together same PR?, actually I wouldn't like to keep this PR in review.

so why don't we finish this PR first, after that I'll create a new PR for advanced examples with new issue.
or you would think put together same PR, just let me know. I'm going to take a look advanced examples you mentioned.

phdargen · 2026-01-05T15:09:39Z

Agreed @Ilevk, let's get this in first. Would also be useful for me to have the basic server example in the feat/python-v2-sdk branch to do some manual testing

Please open a new PR for the advanced and/or custom examples when you are ready, no need to open new issues.
I will update the TODO list accordingly

phdargen · 2026-01-05T15:28:32Z

Merged and updated the TODO list @Ilevk: #841 (comment)

Note that I also added a new TODO item for fixing the x402HTTPAdapter retry logic (as discussed above) and assigned it to you. No problem at all if you are too busy or would rather take on something else, just let me know and I am happy to assign myself

Ilevk · 2026-01-05T15:31:48Z

@phdargen I’ll first take a look at the advanced example, and then I’ll check the x402HTTPAdapter case. and I've updated my TODO list as well in 841 PR

I really appreciate it.

phdargen self-assigned this Dec 29, 2025

phdargen mentioned this pull request Dec 29, 2025

feat: New Python SDK with v2 support #841

Draft

3 tasks

phdargen reviewed Dec 29, 2025

View reviewed changes

examples/python/servers/fastapi/.python-version Outdated Show resolved Hide resolved

Ilevk added 8 commits December 30, 2025 23:49

feat: add fastapi example project configuration

c12b310

feat: add fastapi example with x402 payment middleware

c8ae5ab

docs: add comprehensive README for fastapi example

cf57c7b

feat: add flask example project configuration

e3e1709

feat: add flask example with x402 payment middleware

d95086a

docs: add comprehensive README for flask example

4da9443

feat: add test clients for fastapi and flask examples

f3ff737

docs: add test client usage to READMEs

a348d65

Ilevk force-pushed the feat/python-v2-sdk-middleware branch from 7d6bb50 to a348d65 Compare December 30, 2025 14:49

Ilevk added 2 commits December 30, 2025 23:50

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

cfc7a17

docs - remove test client guide from README.md

8275135

Ilevk requested a review from phdargen December 30, 2025 14:59

phdargen reviewed Dec 30, 2025

View reviewed changes

0xsarawut mentioned this pull request Dec 30, 2025

Suggest renaming to EVM_ADDRESS in anticipation of svm mechanism to be added soon and adding facilitator URL ethereum/ethereum-org-website#17006

Closed

This comment was marked as spam.

Sign in to view

phdargen reviewed Dec 30, 2025

View reviewed changes

coinbase deleted a comment from 0xsarawut Dec 30, 2025

phdargen assigned Ilevk Dec 30, 2025

Ilevk added 2 commits December 31, 2025 20:20

chore - remove license and classifier

0ff914c

feat - add description and mime type

d905e0b

Ilevk force-pushed the feat/python-v2-sdk-middleware branch from 738726b to c26875c Compare December 31, 2025 11:26

feat - update .env-local

7e1f56a

Ilevk force-pushed the feat/python-v2-sdk-middleware branch from c26875c to 7e1f56a Compare December 31, 2025 11:27

phdargen approved these changes Jan 5, 2026

View reviewed changes

phdargen merged commit 167ee41 into coinbase:feat/python-v2-sdk Jan 5, 2026
12 of 13 checks passed

logan-d-able mentioned this pull request Jan 7, 2026

Add FastAPI Example for x402 v2 #805

Closed

	ADDRESS=
	EVM_ADDRESS=
	FACILITATOR_URL=https://x402.org/facilitator

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

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

Uh oh!

Conversation

Ilevk commented Dec 29, 2025

Description

Tests

Checklist

Uh oh!

vercel bot commented Dec 29, 2025

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

phdargen commented Dec 29, 2025

Uh oh!

phdargen commented Dec 29, 2025

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as spam.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

phdargen commented Dec 30, 2025

Uh oh!

phdargen commented Dec 30, 2025

Uh oh!

phdargen commented Dec 30, 2025

Uh oh!

phdargen commented Dec 30, 2025

Uh oh!

phdargen commented Dec 30, 2025

Uh oh!

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

Uh oh!

Uh oh!

Ilevk commented Jan 5, 2026

Uh oh!

phdargen commented Jan 5, 2026

Uh oh!

Uh oh!

phdargen commented Jan 5, 2026

Uh oh!

Ilevk commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Ilevk commented Dec 29, 2025 •

edited

Loading

Ilevk commented Dec 29, 2025 •

edited

Loading

phdargen commented Dec 29, 2025 •

edited

Loading

Ilevk commented Dec 30, 2025 •

edited

Loading

Ilevk commented Dec 30, 2025 •

edited

Loading

Ilevk Dec 31, 2025 •

edited

Loading

Ilevk commented Dec 31, 2025 •

edited

Loading

Ilevk commented Jan 5, 2026 •

edited

Loading