Metadata-Version: 2.4
Name: xrpl-x402-middleware
Version: 0.2.0
Summary: ASGI middleware for XRPL-backed x402 API payments
Project-URL: Homepage, https://github.com/lgcarrier/xrpl-x402-stack
Project-URL: Documentation, https://lgcarrier.github.io/xrpl-x402-stack/packages/middleware/
Project-URL: Repository, https://github.com/lgcarrier/xrpl-x402-stack
Project-URL: Issues, https://github.com/lgcarrier/xrpl-x402-stack/issues
Project-URL: Changelog, https://github.com/lgcarrier/xrpl-x402-stack/blob/main/CHANGELOG.md
Author-email: Louis-Guillaume Carrier-Bedard <lgcarrier@gmail.com>
License-Expression: MIT
Keywords: fastapi,middleware,payments,x402,xrpl
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx==0.28.1
Requires-Dist: pydantic<3,>=2
Requires-Dist: redis==5.2.1
Requires-Dist: starlette<0.39,>=0.37
Requires-Dist: x402[extensions,fastapi]==2.21.0
Requires-Dist: xrpl-x402-core==0.2.0
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1; extra == 'mcp'
Requires-Dist: x402[mcp]==2.21.0; extra == 'mcp'
Description-Content-Type: text/markdown

# xrpl-x402-middleware

Canonical x402 v2 HTTP and MCP resource-server integration for XRPL.

```python
from xrpl_x402_middleware import PaymentMiddlewareASGI, require_payment

app.add_middleware(
    PaymentMiddlewareASGI,
    routes={
        "GET /premium": require_payment(
            pay_to="rMerchant",
            network="xrpl:1",
            xrp_drops=1000,
            resource="https://merchant.example/premium",
            description="Premium data",
            service_name="Example merchant",
            tags=["premium", "xrpl"],
        )
    },
    facilitator_url="http://127.0.0.1:8000",
    bearer_token="replace-with-your-token",
)
```

The middleware verifies first, buffers the successful handler response, settles,
and only then releases protected bytes. Handler errors are not settled. For a
`settlement_pending` result, the upstream x402 resource server retries the
identical settlement envelope exactly once. If it is still pending, a later
identical request resumes settlement from the cached protected response without
rerunning the handler or exposing protected bytes early.

Unsafe methods require the payment-identifier extension. Configure
`RedisResourceResponseStore` so a matching retry can recover the handler result
without repeating side effects. The store preserves exact response bytes and
retains them for at least `maxTimeoutSeconds` plus a safety margin (with a
600-second minimum by default), so a still-valid retry cannot repeat the
handler after cache expiry.

Before facilitator verification, the middleware rejects payload resource
metadata that does not match the authoritative HTTP route or MCP tool. Recovery
fingerprints also include the HTTP method, effective URL and query, and a digest
of the exact request body; MCP fingerprints include the exact tool name and a
digest of its canonical arguments. Raw request bodies and tool arguments are
not persisted in the binding record.

Use `create_xrpl_mcp_payment_wrapper` for paid MCP tools. It composes the
official x402 MCP wrapper, registers XRPL exact, preserves extension data, and
requires payment identifiers plus `RedisResourceResponseStore` for
non-idempotent tools. Install the helper with
`pip install "xrpl-x402-middleware[mcp]"`.
