@goplausible/openclaw-algorand-plugin 0.5.0

package/skills/algorand-x402-python/references/create-python-x402-server-reference.md

@@ -0,0 +1,303 @@
+# x402 Python Server Middleware Reference
+
+Detailed API reference for FastAPI and Flask payment middleware in the `x402-avm` Python package.
+
+## FastAPI Middleware API
+
+### `payment_middleware(routes, server, ...)`
+
+Creates an async middleware callable for FastAPI.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `routes` | `RoutesConfig` | required | Route configuration for protected endpoints |
+| `server` | `x402ResourceServer` | required | Pre-configured async resource server |
+| `paywall_config` | `PaywallConfig \| None` | `None` | Optional paywall UI configuration |
+| `paywall_provider` | `PaywallProvider \| None` | `None` | Optional custom paywall provider |
+| `sync_facilitator_on_start` | `bool` | `True` | Fetch facilitator support on first request |
+
+**Returns**: Async middleware callable `(Request, call_next) -> Response`
+
+**Usage**:
+```python
+x402_mw = payment_middleware(routes=routes, server=server)
+
+@app.middleware("http")
+async def x402_middleware(request: Request, call_next):
+    return await x402_mw(request, call_next)
+```
+
+### `payment_middleware_from_config(routes, facilitator_client, ...)`
+
+Creates middleware with an internally-created resource server.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `routes` | `RoutesConfig` | required | Route configuration |
+| `facilitator_client` | `Any` | `None` | Facilitator client for payment processing |
+| `schemes` | `list[dict] \| None` | `None` | Scheme registrations (`{"network": ..., "server": ...}`) |
+| `paywall_config` | `PaywallConfig \| None` | `None` | Optional paywall config |
+| `paywall_provider` | `PaywallProvider \| None` | `None` | Optional custom paywall |
+| `sync_facilitator_on_start` | `bool` | `True` | Lazy initialization flag |
+
+**Returns**: Async middleware callable `(Request, call_next) -> Response`
+
+### `PaymentMiddlewareASGI`
+
+Starlette `BaseHTTPMiddleware` subclass. Accepts same parameters as `payment_middleware` via `app.add_middleware()`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `app` | `ASGIApp` | Passed automatically by Starlette |
+| `routes` | `RoutesConfig` | Route configuration |
+| `server` | `x402ResourceServer` | Pre-configured server instance |
+| `paywall_config` | `PaywallConfig \| None` | Optional paywall UI config |
+| `paywall_provider` | `PaywallProvider \| None` | Optional custom paywall |
+
+**Usage**:
+```python
+app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)
+```
+
+### `FastAPIAdapter`
+
+Implements the `HTTPAdapter` protocol for FastAPI/Starlette requests. Used internally.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `get_header(name)` | `str \| None` | Case-insensitive header lookup |
+| `get_method()` | `str` | HTTP method (GET, POST, etc.) |
+| `get_path()` | `str` | Request path |
+| `get_url()` | `str` | Full request URL |
+| `get_accept_header()` | `str` | Accept header value |
+| `get_user_agent()` | `str` | User-Agent header value |
+| `get_query_params()` | `dict` | All query parameters |
+| `get_query_param(name)` | `str \| None` | Single query parameter |
+| `get_body()` | `None` | Returns None (body requires async access) |
+
+## Flask Middleware API
+
+### `PaymentMiddleware(app, routes, server, ...)`
+
+The main WSGI middleware class. Replaces `app.wsgi_app` on initialization.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `app` | `Flask` | required | Flask application instance |
+| `routes` | `RoutesConfig` | required | Route configuration for protected endpoints |
+| `server` | `x402ResourceServerSync` | required | Pre-configured **sync** resource server |
+| `paywall_config` | `PaywallConfig \| None` | `None` | Optional paywall UI configuration |
+| `paywall_provider` | `PaywallProvider \| None` | `None` | Optional custom paywall provider |
+| `sync_facilitator_on_start` | `bool` | `True` | Fetch facilitator support on first request |
+
+**Side effect**: Replaces `app.wsgi_app` with the payment-checking WSGI middleware.
+
+### `payment_middleware(app, routes, server, ...)`
+
+Factory function. Accepts same parameters as `PaymentMiddleware`, returns `PaymentMiddleware` instance.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `app` | `Flask` | required | Flask application instance |
+| `routes` | `RoutesConfig` | required | Route configuration |
+| `server` | `x402ResourceServerSync` | required | Pre-configured **sync** resource server |
+| `paywall_config` | `PaywallConfig \| None` | `None` | Optional paywall config |
+| `paywall_provider` | `PaywallProvider \| None` | `None` | Optional custom paywall |
+| `sync_facilitator_on_start` | `bool` | `True` | Lazy initialization flag |
+
+**Returns**: `PaymentMiddleware` instance.
+
+### `payment_middleware_from_config(app, routes, ...)`
+
+Convenience function that creates the `x402ResourceServer` internally.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `app` | `Flask` | required | Flask application instance |
+| `routes` | `RoutesConfig` | required | Route configuration |
+| `facilitator_client` | `Any` | `None` | Facilitator client for payment processing |
+| `schemes` | `list[dict] \| None` | `None` | Scheme registrations (`{"network": ..., "server": ...}`) |
+| `paywall_config` | `PaywallConfig \| None` | `None` | Optional paywall config |
+| `paywall_provider` | `PaywallProvider \| None` | `None` | Optional custom paywall |
+| `sync_facilitator_on_start` | `bool` | `True` | Lazy initialization flag |
+
+**Returns**: `PaymentMiddleware` instance.
+
+### `FlaskAdapter`
+
+Implements the `HTTPAdapter` protocol for Flask requests. Used internally.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `get_header(name)` | `str \| None` | Case-insensitive header lookup |
+| `get_method()` | `str` | HTTP method (GET, POST, etc.) |
+| `get_path()` | `str` | Request path |
+| `get_url()` | `str` | Full request URL |
+| `get_accept_header()` | `str` | Accept header value |
+| `get_user_agent()` | `str` | User-Agent header value |
+| `get_query_params()` | `dict` | All query parameters |
+| `get_query_param(name)` | `str \| None` | Single query parameter |
+| `get_body()` | `Any \| None` | Parsed JSON body (via `request.get_json(silent=True)`) |
+
+### `ResponseWrapper`
+
+Internal class that captures and buffers the WSGI response for settlement processing.
+
+| Method/Property | Description |
+|-----------------|-------------|
+| `status` | Captured HTTP status string |
+| `status_code` | Parsed integer status code |
+| `headers` | List of (name, value) header tuples |
+| `add_header(name, value)` | Add a header to the response |
+| `send_response(body_chunks)` | Send the buffered response to the client |
+
+## RouteConfig
+
+Dataclass for route configuration.
+
+```python
+from x402.http.types import RouteConfig
+
+RouteConfig(
+    accepts=PaymentOption(...),          # Required: single payment option
+    # or: accepts=[PaymentOption(...), PaymentOption(...)],  # Multiple options
+    resource="https://api.example.com/api/weather",  # Optional: resource URL
+    description="Weather data API",      # Optional: description
+    mime_type="application/json",        # Optional: response MIME type
+)
+```
+
+### Route Key Format
+
+Route keys follow the pattern `"METHOD /path"`:
+
+| Pattern | Matches |
+|---------|---------|
+| `"GET /api/weather"` | Exactly `/api/weather` |
+| `"GET /api/premium/*"` | `/api/premium/anything`, `/api/premium/a/b` |
+| `"POST /api/generate"` | Exactly `POST /api/generate` |
+| `"GET /api/data/*"` | Any GET under `/api/data/` |
+
+## PaymentOption
+
+Dataclass for payment options.
+
+```python
+from x402.http import PaymentOption
+
+PaymentOption(
+    scheme="exact",              # Payment scheme name
+    network="algorand:SGO...",   # CAIP-2 network identifier
+    pay_to="ALGO_ADDRESS",       # Recipient address
+    price="$0.01",               # Auto-converted to AssetAmount
+    # or: price=AssetAmount(amount="10000", asset="10458941"),
+)
+```
+
+## AssetAmount
+
+Explicit asset amount specification.
+
+```python
+from x402.schemas import AssetAmount
+
+AssetAmount(
+    amount="10000",                      # Atomic units (string)
+    asset="10458941",                    # Asset identifier (ASA ID as string)
+    extra={"name": "USDC", "decimals": 6},  # Optional metadata
+)
+```
+
+## Sync vs Async Comparison
+
+| Component | Flask (Sync) | FastAPI (Async) |
+|-----------|-------------|-----------------|
+| Resource server | `x402ResourceServerSync` | `x402ResourceServer` |
+| Facilitator client | `HTTPFacilitatorClientSync` | `HTTPFacilitatorClient` |
+| Middleware class | `PaymentMiddleware` (WSGI) | `PaymentMiddlewareASGI` (ASGI) |
+| Payment info storage | `flask.g.payment_payload` | `request.state.payment_payload` |
+| HTTP server wrapper | `x402HTTPResourceServerSync` | `x402HTTPResourceServer` |
+| Middleware invocation | `PaymentMiddleware(app, ...)` | `app.add_middleware(PaymentMiddlewareASGI, ...)` |
+| Settlement | Synchronous (blocking) | `await` async settlement |
+
+## Middleware Flow
+
+### FastAPI (ASGI)
+
+1. Client sends request with `Payment-Signature` header
+2. Middleware checks if the route requires payment via `requires_payment(context)`
+3. On first protected request, facilitator support is synchronized (lazy init)
+4. `process_http_request(context)` verifies the payment:
+   - `"no-payment-required"` -- route not protected, passes through
+   - `"payment-error"` -- returns 402 response (JSON or HTML paywall)
+   - `"payment-verified"` -- stores on `request.state`, calls route handler
+5. If route handler returns a successful (2xx) response, settlement is processed
+6. Settlement headers are added to the response
+
+### Flask (WSGI)
+
+1. Client sends request with `Payment-Signature` header
+2. The WSGI middleware intercepts the request within a Flask request context
+3. Middleware checks if the route requires payment via `requires_payment(context)`
+4. On first protected request, facilitator support is synchronized (lazy init)
+5. `process_http_request(context)` verifies the payment **synchronously**:
+   - `"no-payment-required"` -- passes through to `original_wsgi`
+   - `"payment-error"` -- returns 402 response
+   - `"payment-verified"` -- stores on `flask.g`, calls original WSGI app
+6. Response is captured by `ResponseWrapper`, settlement is processed synchronously
+7. Settlement headers are added to the buffered response
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AVM_ADDRESS` | Algorand address to receive payments | Required |
+| `FACILITATOR_URL` | URL of the x402 facilitator service | `https://x402.org/facilitator` |
+
+## Algorand-Specific Constants
+
+| Constant | Value | Import |
+|----------|-------|--------|
+| `ALGORAND_TESTNET_CAIP2` | `"algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="` | `x402.mechanisms.avm` |
+| `ALGORAND_MAINNET_CAIP2` | `"algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8="` | `x402.mechanisms.avm` |
+| `USDC_TESTNET_ASA_ID` | `10458941` | `x402.mechanisms.avm` |
+| `USDC_MAINNET_ASA_ID` | `31566704` | `x402.mechanisms.avm` |
+
+## CAIP-2 Network Identifiers
+
+| Network | CAIP-2 Identifier |
+|---------|-------------------|
+| Algorand Mainnet | `algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=` |
+| Algorand Testnet | `algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=` |
+| Base Sepolia (EVM) | `eip155:84532` |
+| Solana Devnet (SVM) | `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` |
+
+## Error Handling
+
+### Payment Errors (402 Responses)
+
+When a client sends a request without a valid payment, the middleware returns a 402 response containing `PaymentRequirements` the client needs to fulfill.
+
+### Settlement Failures
+
+If the route handler succeeds but settlement fails:
+
+```json
+{
+    "error": "Settlement failed",
+    "details": "reason for failure"
+}
+```
+
+### Unprotected Routes
+
+Routes not listed in the `routes` configuration are served normally without any payment check.
+
+## External Resources
+
+- [x402-avm on PyPI](https://pypi.org/project/x402-avm/)
+- [x402-avm Examples Repository](https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/examples/)
+- [x402 Algorand Documentation](https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/)
+- [FastAPI Documentation](https://fastapi.tiangolo.com/)
+- [Flask Documentation](https://flask.palletsprojects.com/)
+- [Coinbase x402 Specification](https://github.com/coinbase/x402)

package/skills/algorand-x402-python/references/create-python-x402-server.md

@@ -0,0 +1,221 @@
+# Creating x402 Payment-Protected Servers in Python
+
+Build FastAPI (async) or Flask (sync) servers that protect API endpoints behind Algorand USDC payments using x402 middleware.
+
+## Prerequisites
+
+Before using this skill, ensure:
+
+1. **Python 3.10+** is installed
+2. **An Algorand address** to receive payments (the `payTo` address)
+3. **A facilitator URL** -- use `https://x402.org/facilitator` or run your own
+4. **Understanding of FastAPI or Flask** basics
+
+## Core Workflow: Middleware-Based Payment Protection
+
+The middleware intercepts requests to protected routes, checks for payment headers, verifies payments through the facilitator, and settles on success.
+
+```
+Client Request
+      |
+      v
+x402 Middleware (checks route config)
+      |
+      +-- Not protected -> Pass through to handler
+      |
+      +-- Protected, no payment -> Return 402 with PaymentRequirements
+      |
+      +-- Protected, has payment -> Verify via Facilitator
+            |
+            +-- Invalid -> Return 402
+            |
+            +-- Valid -> Call handler, then settle payment
+```
+
+## How to Proceed
+
+### Step 1: Install Dependencies
+
+For FastAPI (async):
+```bash
+pip install "x402-avm[fastapi,avm]"
+```
+
+For Flask (sync):
+```bash
+pip install "x402-avm[flask,avm]"
+```
+
+### Step 2: Choose Your Framework Pattern
+
+**FastAPI** uses async components:
+- `x402ResourceServer` (async)
+- `HTTPFacilitatorClient` (async)
+- `PaymentMiddlewareASGI` or `payment_middleware`
+
+**Flask** uses sync components:
+- `x402ResourceServerSync` (sync)
+- `HTTPFacilitatorClientSync` (sync)
+- `PaymentMiddleware` or `payment_middleware`
+
+### Step 3: Set Up the Resource Server
+
+Create a facilitator client, resource server, and register the AVM scheme:
+
+**FastAPI:**
+```python
+from x402.server import x402ResourceServer
+from x402.http import HTTPFacilitatorClient, FacilitatorConfig
+from x402.mechanisms.avm.exact import ExactAvmServerScheme
+
+facilitator = HTTPFacilitatorClient(FacilitatorConfig(url="https://x402.org/facilitator"))
+server = x402ResourceServer(facilitator)
+server.register("algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=", ExactAvmServerScheme())
+```
+
+**Flask:**
+```python
+from x402.server import x402ResourceServerSync
+from x402.http import HTTPFacilitatorClientSync, FacilitatorConfig
+from x402.mechanisms.avm.exact import ExactAvmServerScheme
+
+facilitator = HTTPFacilitatorClientSync(FacilitatorConfig(url="https://x402.org/facilitator"))
+server = x402ResourceServerSync(facilitator)
+server.register("algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=", ExactAvmServerScheme())
+```
+
+### Step 4: Define Route Configurations
+
+Routes map HTTP method + path patterns to payment requirements:
+
+```python
+from x402.http import PaymentOption
+from x402.http.types import RouteConfig
+
+routes = {
+    "GET /api/weather": RouteConfig(
+        accepts=PaymentOption(
+            scheme="exact",
+            network="algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
+            pay_to="YOUR_ALGORAND_ADDRESS",
+            price="$0.01",
+        ),
+    ),
+}
+```
+
+### Step 5: Apply Middleware
+
+**FastAPI -- Option A (ASGI class, recommended):**
+```python
+from x402.http.middleware.fastapi import PaymentMiddlewareASGI
+app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)
+```
+
+**FastAPI -- Option B (function-based):**
+```python
+from x402.http.middleware.fastapi import payment_middleware
+x402_mw = payment_middleware(routes=routes, server=server)
+
+@app.middleware("http")
+async def x402_middleware(request, call_next):
+    return await x402_mw(request, call_next)
+```
+
+**Flask:**
+```python
+from x402.http.middleware.flask import PaymentMiddleware
+PaymentMiddleware(app, routes, server)
+```
+
+### Step 6: Define Route Handlers
+
+Routes listed in the configuration require payment. Unlisted routes pass through freely.
+
+**FastAPI:**
+```python
+@app.get("/api/weather")
+async def get_weather():
+    return {"temperature": 72, "unit": "F"}
+```
+
+**Flask:**
+```python
+@app.route("/api/weather")
+def get_weather():
+    return {"temperature": 72, "unit": "F"}
+```
+
+## Important Rules / Guidelines
+
+1. **Match async/sync variants** -- FastAPI uses `x402ResourceServer` + `HTTPFacilitatorClient`, Flask uses `x402ResourceServerSync` + `HTTPFacilitatorClientSync`
+2. **Route format** -- Keys must be `"METHOD /path"` (e.g., `"GET /api/weather"`, `"POST /api/generate/*"`)
+3. **Wildcard paths** -- Use `/*` suffix to match all sub-paths (e.g., `"GET /api/premium/*"`)
+4. **Unlisted routes pass through** -- Only routes in the config require payment
+5. **Register scheme before middleware** -- Call `server.register(...)` before adding middleware
+6. **Price format** -- Use `"$0.01"` for auto-conversion or `AssetAmount(amount="10000", asset="10458941")` for explicit control
+7. **CAIP-2 network IDs** -- Use full CAIP-2 identifiers like `"algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="`
+
+## Pricing Options
+
+### Simple String Price
+
+```python
+PaymentOption(
+    scheme="exact",
+    network="algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
+    pay_to="YOUR_ADDRESS",
+    price="$0.01",  # Auto-converts to 10000 microUSDC
+)
+```
+
+### Explicit AssetAmount
+
+```python
+from x402.schemas import AssetAmount
+
+PaymentOption(
+    scheme="exact",
+    network="algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
+    pay_to="YOUR_ADDRESS",
+    price=AssetAmount(
+        amount="50000",       # 50000 microUSDC = $0.05
+        asset="10458941",     # USDC ASA ID on testnet
+        extra={"name": "USDC", "decimals": 6},
+    ),
+)
+```
+
+### Multi-Network (AVM + EVM + SVM)
+
+```python
+routes = {
+    "GET /api/data/*": RouteConfig(
+        accepts=[
+            PaymentOption(scheme="exact", pay_to=AVM_ADDRESS, price="$0.01",
+                         network="algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="),
+            PaymentOption(scheme="exact", pay_to=EVM_ADDRESS, price="$0.01",
+                         network="eip155:84532"),
+            PaymentOption(scheme="exact", pay_to=SVM_ADDRESS, price="$0.01",
+                         network="solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"),
+        ],
+    ),
+}
+```
+
+## Common Errors / Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `TypeError: async` errors in Flask | Using async variants with Flask | Use `x402ResourceServerSync` and `HTTPFacilitatorClientSync` |
+| 402 returned to all requests | Middleware applied but facilitator unreachable | Check `FACILITATOR_URL` and network connectivity |
+| Route not protected | Path pattern mismatch | Verify route key format matches: `"GET /exact/path"` or `"GET /prefix/*"` |
+| Settlement fails | Facilitator cannot reach Algorand network | Check facilitator logs and algod endpoint |
+| `ImportError` on middleware | Missing extras | `pip install "x402-avm[fastapi,avm]"` or `"x402-avm[flask,avm]"` |
+
+## References / Further Reading
+
+- [create-python-x402-server-reference.md](./create-python-x402-server-reference.md) - Detailed API reference for middleware
+- [create-python-x402-server-examples.md](./create-python-x402-server-examples.md) - Complete code examples for FastAPI and Flask
+- [x402-avm Examples Repository](https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/examples/)
+- [x402 Algorand Documentation](https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/)