Metadata-Version: 2.5
Name: kite-x402-wrapper
Version: 0.1.0
Summary: FastAPI reverse proxy with x402 payments settled on Kite
Project-URL: Homepage, https://github.com/Tools-touch/KiteAI-X402-Wrapper
Project-URL: Repository, https://github.com/Tools-touch/KiteAI-X402-Wrapper
Project-URL: Issues, https://github.com/Tools-touch/KiteAI-X402-Wrapper/issues
Author: Tools-touch
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: fastapi,kite,payments,reverse-proxy,x402
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: httpx<1,>=0.28.1
Requires-Dist: python-dotenv<2,>=1.1
Requires-Dist: uvicorn[standard]<1,>=0.40
Requires-Dist: x402[evm,fastapi]<3,>=2.23
Provides-Extra: dev
Requires-Dist: build<2,>=1.3; extra == 'dev'
Requires-Dist: mypy<2,>=1.18; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=1.2; extra == 'dev'
Requires-Dist: pytest-cov<8,>=7; extra == 'dev'
Requires-Dist: pytest<9,>=8.4; extra == 'dev'
Requires-Dist: respx<1,>=0.22; extra == 'dev'
Requires-Dist: ruff<1,>=0.13; extra == 'dev'
Requires-Dist: twine<8,>=7; extra == 'dev'
Description-Content-Type: text/markdown

# 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:

```text
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.

```bash
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:

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

For development from this repository:

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

Then request a paid route:

```bash
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

| Variable | Default | Purpose |
|---|---|---|
| `PAY_TO` | required | Public EVM address receiving payments |
| `KITE_NETWORK` | `mainnet` | `mainnet` or `testnet` |
| `UPSTREAM_URL` | required | Fixed upstream HTTP(S) origin |
| `UPSTREAM_AUTH_HEADER` | `Authorization` | Optional upstream credential header |
| `UPSTREAM_AUTH_VALUE` | empty | Optional credential value, never returned to callers |
| `PRICE_USD` | `0.001` | Positive decimal USD price, at most 6 fractional digits |
| `SERVICE_DESCRIPTION` | generic description | Text included in the 402 requirements |
| `FACILITATOR_URL` | Pieverse `/v2` endpoint | HTTPS x402 facilitator base URL |
| `PORT` | `8080` | Listening port |

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

```python
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

```bash
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.
