Kite x402 Wrapper for Python

Wrap an HTTP API with x402 payments settled on Kite, using Python, FastAPI, and the official x402 SDK. Every request under /v1/* is payment protected; /healthz remains free.

The wrapper preserves the critical order:

verify payment -> call upstream -> settle only when upstream status is below 400

Install

Python 3.10 or newer is required.

The 0.1.0 PyPI release is prepared but is not published yet. Until the release is published, use the repository installation below.

git clone https://github.com/Tools-touch/KiteAI-X402-Wrapper.git
cd KiteAI-X402-Wrapper
uv sync --extra dev
cp .env.example .env
kite-x402-wrapper

After the PyPI release is published, the installed-package form is:

python -m pip install kite-x402-wrapper
cp .env.example .env
kite-x402-wrapper

For development from this repository:

uv sync --extra dev
cp .env.example .env
uv run kite-x402-wrapper

Then request a paid route:

curl -i "http://localhost:8080/v1/v1/forecast?latitude=52.52&longitude=13.41&current=temperature_2m"

An unpaid request returns HTTP 402 with a PAYMENT-REQUIRED header. The wrapper strips the first /v1 prefix before proxying, so the example above reaches https://api.open-meteo.com/v1/forecast.

Configuration

Start on Kite testnet. The wrapper uses pieUSD on eip155:2368; mainnet uses USDC.e on eip155:2366. The package never needs a wallet private key.

Use as a library

from kite_x402_wrapper import Settings, create_app

settings = Settings.from_env()
app = create_app(settings)

The application factory accepts an HTTPX client and payment components as optional injected dependencies. Tests can therefore verify proxy and settlement behavior without real funds or external services.

Safety properties

• A missing or invalid payment never reaches the upstream.
• Upstream responses with status 400 or higher are not settled.
• Upstream connection failures return 502 and are not settled.
• Payment headers are removed before proxying.
• Upstream credentials replace caller-provided values and are never returned.
• The proxy target stays on the configured upstream origin.
• Amount conversion uses Decimal, never binary floating point.

Because settlement happens after the handler finishes, responses are buffered in memory by the official x402 FastAPI middleware. This template is intended for ordinary API payloads, not unbounded downloads or streaming endpoints.

Quality checks

uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest --cov=kite_x402_wrapper
uv build
uv run twine check dist/*

Public deployment and paid acceptance

Kite Passport calls services from its own servers. Real paid testing requires a public HTTPS origin; localhost and browser-gated tunnels are not sufficient. Use a small, short-lived Passport sandbox session and verify the returned PAYMENT-RESPONSE transaction reference. Never fabricate paid-call evidence.

License

Apache-2.0.