Skip to main content

ftptech-x402-canton

Take x402 payments in Canton Coin or a CIP-56 token on a FastAPI or Flask server. The plugin sits in front of the official x402 Python SDK and settles through FTP's facilitator.

It charges only when your handler answers 2xx, and it delivers each payment once.

Install

pip install "ftptech-x402-canton[fastapi,redis]"

Extras: fastapi, flask, redis. Python 3.10 or newer, x402 2.28.

Before you start

The party that receives payments needs a live Canton Coin TransferPreapproval:

npx @ftptech/canton-agent-wallet create --relay-url https://facilitator.ftptech.xyz
npx @ftptech/canton-agent-wallet address       # your party id: pay_to
# send it a few CC, then
npx @ftptech/canton-agent-wallet claim
npx @ftptech/canton-agent-wallet preapproval   # lasts 30 days, renew it

A token needs preapproval --admin <admin> --id <id> for each instrument you price.

Quickstart

FastAPI:

from fastapi import FastAPI, Request
from ftptech_x402_canton import CantonPaymentMiddleware, CantonServer, Config, Route, cc, payer_from

routes = {"GET /v1/data": Route(pay_to="<your party id>", price=cc("0.01"))}
server = CantonServer(Config(routes=routes))
app = FastAPI(lifespan=server.lifespan)
app.add_middleware(CantonPaymentMiddleware, server=server)


@app.get("/v1/data")
def data(request: Request) -> dict:
    return {"payer": payer_from(request)}

Flask:

import atexit
from flask import Flask
from ftptech_x402_canton import (
    CantonWSGIMiddleware,
    Config,
    Route,
    canton_server_sync,
    cc,
    payer_from,
)

routes = {"GET /v1/data": Route(pay_to="<your party id>", price=cc("0.01"))}
server = canton_server_sync(Config(routes=routes))
atexit.register(server.close)  # waits for paid requests in flight
app = Flask(__name__)
app.wsgi_app = CantonWSGIMiddleware(app.wsgi_app, server)


@app.get("/v1/data")
def data():
    return {"payer": payer_from()}
  • Routes are literal "METHOD /path" keys with the full path, router or mount prefix included. Register the handler with the same method. Any other path or method is served free.
  • Prices: cc("0.01"), token(admin, "USDCx", "1.5") or atomic("100000000", InstrumentId(admin, id)).
  • payer_from(request) is the payer the facilitator verified. Use it to limit calls per payer, but never refuse a retry: skip the limit when is_retry(request) is true, and answer an over-limit payer 429.

Run it (uvicorn main:app for FastAPI, gunicorn main:app for Flask), then curl -i http://localhost:8000/v1/data answers 402.

Production

One worker can run on the default memory store, but it forgets payments on every restart: a replay can be served twice and a paid retry is refused as expired. Redis also covers restarts, so use it in production. With several workers or servers it is required. Use a dedicated Redis database (a single Redis, not a Cluster endpoint) with maxmemory-policy noeviction:

from ftptech_x402_canton import Config, RedisStore

store = RedisStore.from_url("redis://cache:6379/2", prefix="x402:my-service:")
config = Config(routes=routes, store=store)

Services that share a pay_to and terms must share one prefix: a payment is then delivered once across them. With different prefixes each service would serve it once.

The plugin must see a payer who leaves during settle, or that payer is charged and gets nothing on the retry:

Server Sees a payer who left Needs
uvicorn, hypercorn, with an ASGI app (FastAPI, Starlette) yes nothing
gunicorn, werkzeug, uWSGI, with Flask yes nothing
waitress, with Flask only with a setting channel_request_lookahead=1
Flask under uvicorn or hypercorn (WSGI mode or an adapter), TLS ended in the WSGI server, Mangum no serve Flask with gunicorn, uWSGI or waitress; end TLS in a proxy; Mangum is unsupported
  • Allow a 32 KiB PAYMENT-SIGNATURE header in every proxy and server (it is about 11 KiB).
  • Set worker, proxy and shutdown timeouts to at least request_budget(config), 465 s with the defaults.
  • Stop the server gracefully: server.lifespan or close() waits for paid requests in flight.
  • The facilitator limits calls per payer: limit per payer in your handler too.

Money safety

  • 2xx from your handler: charged, the response is delivered.
  • 4xx or 5xx from your handler: not charged, passed through. On a retry of a payment that may have moved it becomes 503 (see OPERATIONS.md).
  • 3xx from your handler: becomes 502, not charged.
  • The same payment again after delivery: 402.
  • The same payment while the first is in flight: 503.
  • 503 with "do NOT pay again": retry the same signature. The retry runs your handler again, so keep paid side effects idempotent.
  • The preapproval lasts 30 days and payments to an expired one fail: run preapproval again before then (--force renews early).
  • ~/.canton-agent/wallet.json holds the key of the party you are paid to. Back it up with npx @ftptech/canton-agent-wallet export.
  • Keep paid bodies small: they are buffered, and delivery is confirmed only up to the server's buffers.

Docs

  • OPERATIONS.md: every rule, limit and caveat, by topic.
  • examples/fastapi_app.py, examples/flask_app.py: with a per-payer limiter and REDIS_URL.
  • Merchant integration on the FTP docs site.
  • License: Apache-2.0.

Metadata

Release files for ftptech-x402-canton 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ftptech-x402-canton 0.1.1
File Size Uploaded Provenance Actions
ftptech_x402_canton-0.1.1.tar.gz 149.4 kB With provenance Details for ftptech_x402_canton-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ftptech-x402-canton 0.1.1
File Interpreter ABI Platform Actions
ftptech_x402_canton-0.1.1-py3-none-any.whl Python 3 none any Details for ftptech_x402_canton-0.1.1-py3-none-any.whl

Total release size: 235.6 kB

Release files / ftptech_x402_canton-0.1.1.tar.gz

Download URL ftptech_x402_canton-0.1.1.tar.gz
Size 149.4 kB
Tags Source
SHA-256 checksum
How to use checksums
f6a185311124813301871ece00ceb69582283fbc670562d4a5a0d8bbe18d588f
BLAKE2b-256 checksum
How to use checksums
ed3f9a98666350c750b08c28704b489f2713c400652c4bd271d44fe5480d6751
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / ftptech_x402_canton-0.1.1-py3-none-any.whl

Download URL ftptech_x402_canton-0.1.1-py3-none-any.whl
Size 86.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7056a4a02320a76f562ede0afc9805656101657efdbc84ebdfaea28162cd7e4d
BLAKE2b-256 checksum
How to use checksums
613d7d99cadc0077e522751428c62a4a9343e706fac315e18de0132237b31e83
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for ftptech-x402-canton 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ftptech_x402_canton-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page