payclaw 0.1.0__tar.gz

payclaw-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: payclaw
+Version: 0.1.0
+Summary: Drop-in x402 payment middleware for MCP servers — charge AI agents per tool call with USDC
+License: MIT
+Project-URL: Homepage, https://github.com/TeaBay/payclaw
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == "fastapi"
+Provides-Extra: flask
+Requires-Dist: flask>=2.3; extra == "flask"
+
+# payclaw
+
+Drop-in x402 payment middleware for MCP servers. Charge AI agents per tool call using USDC on Base chain — 10 lines of code, no payment processor, no KYC.
+
+```
+pip install payclaw
+```
+
+## How it works
+
+1. Agent calls your tool endpoint
+2. No valid payment → server returns **HTTP 402** with price and wallet address
+3. Agent pays USDC on Base chain, gets tx hash
+4. Agent retries with `X-Payment: <tx_hash>` header
+5. payclaw verifies on-chain → executes your tool
+
+Money flows directly: **agent wallet → your wallet**. payclaw never holds funds.
+
+---
+
+## FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from payclaw import require_payment, PayclawConfig
+
+app = FastAPI()
+
+config = PayclawConfig(
+    price_usdc=0.001,
+    wallet_address="0xYourWalletAddress",
+)
+
+@app.post("/search")
+@require_payment(config)
+async def search(request: Request, q: str):
+    return {"results": ["result1", "result2"]}
+```
+
+## Flask
+
+```python
+from flask import Flask, jsonify
+from payclaw import require_payment, PayclawConfig
+
+app = Flask(__name__)
+
+config = PayclawConfig(
+    price_usdc=0.001,
+    wallet_address="0xYourWalletAddress",
+)
+
+@app.route("/search", methods=["POST"])
+@require_payment(config)
+def search():
+    return jsonify({"results": ["result1", "result2"]})
+```
+
+## Custom framework
+
+```python
+from payclaw import PayclawMiddleware, PayclawConfig
+
+config = PayclawConfig(price_usdc=0.001, wallet_address="0xYourWallet")
+middleware = PayclawMiddleware(config)
+
+# In your request handler:
+allowed, reason = middleware.check(dict(request.headers))
+if not allowed:
+    status, body = middleware.payment_required(reason)
+    # return 402 response with body
+```
+
+---
+
+## 402 Response format
+
+```json
+{
+  "x402": true,
+  "price": "0.001",
+  "currency": "USDC",
+  "network": "base-sepolia",
+  "recipient": "0xYourWallet",
+  "chain_id": 84532,
+  "reason": "missing X-Payment header"
+}
+```
+
+When rate limit is exceeded, the response is HTTP **429** with the same body format and `"reason": "rate limit exceeded"`.
+
+---
+
+## Base Mainnet
+
+```python
+from payclaw import mainnet_config, require_payment
+
+config = mainnet_config(
+    price_usdc=0.001,
+    wallet_address="0xYourWallet",
+)
+
+@app.post("/tool")
+@require_payment(config)
+async def my_tool(request: Request):
+    return {"result": "..."}
+```
+
+---
+
+## Config options
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `price_usdc` | required | Price per call in USDC |
+| `wallet_address` | required | Your wallet (0x...) |
+| `network` | `base-sepolia` | Network name |
+| `chain_id` | `84532` | Chain ID |
+| `usdc_address` | Base Sepolia USDC | USDC contract address |
+| `rpc_url` | `https://sepolia.base.org` | JSON-RPC endpoint |
+| `freshness_seconds` | `300` | Max tx age in seconds |
+| `nonce_cache_ttl` | `600` | Nonce cache TTL in seconds |
+| `nonce_db_path` | `.payclaw_nonces.db` | SQLite file for replay protection |
+| `rate_limit_requests` | `10` | Max requests per IP per window (0 = disabled) |
+| `rate_limit_window_seconds` | `60` | Rate limit window in seconds |
+| `trust_proxy` | `False` | Trust X-Forwarded-For for per-IP rate limiting. Set `True` only when behind a trusted reverse proxy. When `False`, all traffic shares one rate limit bucket. |
+
+---
+
+## Getting testnet USDC
+
+Get free testnet USDC from the [Circle faucet](https://faucet.circle.com) — select **Base Sepolia** and paste your wallet address.
+
+---
+
+## Containerized deployments
+
+The nonce cache is a SQLite file (default: `.payclaw_nonces.db`). In Docker or serverless environments where the filesystem is ephemeral, **mount a persistent volume** or point `nonce_db_path` to a mounted path:
+
+```python
+config = PayclawConfig(
+    price_usdc=0.001,
+    wallet_address="0xYourWallet",
+    nonce_db_path="/data/payclaw_nonces.db",  # mounted volume
+)
+```
+
+Without persistence, a container restart clears the nonce cache and allows replay attacks within the `freshness_seconds` window.
+
+---
+
+## Async frameworks (FastAPI)
+
+The `verify_payment` function uses synchronous HTTP (`requests`). In an async FastAPI app, this blocks the event loop during RPC calls. For high-throughput deployments, wrap with `asyncio.to_thread`:
+
+```python
+import asyncio
+from payclaw import PayclawMiddleware, PayclawConfig
+
+middleware = PayclawMiddleware(config)
+
+@app.post("/tool")
+async def my_tool(request: Request):
+    headers = dict(request.headers)
+    allowed, reason = await asyncio.to_thread(middleware.check, headers)
+    if not allowed:
+        _, body = middleware.payment_required(reason)
+        return JSONResponse(status_code=402, content=body)
+    return {"result": "..."}
+```
+
+---
+
+## Security
+
+- **Replay protection**: SQLite nonce cache survives process restarts. Atomic INSERT OR IGNORE prevents race conditions.
+- **ERC-20 verification**: Reads Transfer event logs from `eth_getTransactionReceipt` — not `tx.value` (which is always 0 for USDC).
+- **Integer math**: USDC amounts compared as integer units (1 USDC = 1,000,000 units). No floating point.
+- **Block timestamp**: Uses on-chain block timestamp for freshness check, not local clock.
+- **Address matching**: Case-insensitive comparison (EIP-55 safe).
+
+---
+
+## Legal
+
+MIT License. payclaw is infrastructure software. Compliance with sanctions (OFAC) and applicable regulations is the responsibility of the deploying party.

payclaw-0.1.0/README.md

@@ -0,0 +1,187 @@
+# payclaw
+
+Drop-in x402 payment middleware for MCP servers. Charge AI agents per tool call using USDC on Base chain — 10 lines of code, no payment processor, no KYC.
+
+```
+pip install payclaw
+```
+
+## How it works
+
+1. Agent calls your tool endpoint
+2. No valid payment → server returns **HTTP 402** with price and wallet address
+3. Agent pays USDC on Base chain, gets tx hash
+4. Agent retries with `X-Payment: <tx_hash>` header
+5. payclaw verifies on-chain → executes your tool
+
+Money flows directly: **agent wallet → your wallet**. payclaw never holds funds.
+
+---
+
+## FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from payclaw import require_payment, PayclawConfig
+
+app = FastAPI()
+
+config = PayclawConfig(
+    price_usdc=0.001,
+    wallet_address="0xYourWalletAddress",
+)
+
+@app.post("/search")
+@require_payment(config)
+async def search(request: Request, q: str):
+    return {"results": ["result1", "result2"]}
+```
+
+## Flask
+
+```python
+from flask import Flask, jsonify
+from payclaw import require_payment, PayclawConfig
+
+app = Flask(__name__)
+
+config = PayclawConfig(
+    price_usdc=0.001,
+    wallet_address="0xYourWalletAddress",
+)
+
+@app.route("/search", methods=["POST"])
+@require_payment(config)
+def search():
+    return jsonify({"results": ["result1", "result2"]})
+```
+
+## Custom framework
+
+```python
+from payclaw import PayclawMiddleware, PayclawConfig
+
+config = PayclawConfig(price_usdc=0.001, wallet_address="0xYourWallet")
+middleware = PayclawMiddleware(config)
+
+# In your request handler:
+allowed, reason = middleware.check(dict(request.headers))
+if not allowed:
+    status, body = middleware.payment_required(reason)
+    # return 402 response with body
+```
+
+---
+
+## 402 Response format
+
+```json
+{
+  "x402": true,
+  "price": "0.001",
+  "currency": "USDC",
+  "network": "base-sepolia",
+  "recipient": "0xYourWallet",
+  "chain_id": 84532,
+  "reason": "missing X-Payment header"
+}
+```
+
+When rate limit is exceeded, the response is HTTP **429** with the same body format and `"reason": "rate limit exceeded"`.
+
+---
+
+## Base Mainnet
+
+```python
+from payclaw import mainnet_config, require_payment
+
+config = mainnet_config(
+    price_usdc=0.001,
+    wallet_address="0xYourWallet",
+)
+
+@app.post("/tool")
+@require_payment(config)
+async def my_tool(request: Request):
+    return {"result": "..."}
+```
+
+---
+
+## Config options
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `price_usdc` | required | Price per call in USDC |
+| `wallet_address` | required | Your wallet (0x...) |
+| `network` | `base-sepolia` | Network name |
+| `chain_id` | `84532` | Chain ID |
+| `usdc_address` | Base Sepolia USDC | USDC contract address |
+| `rpc_url` | `https://sepolia.base.org` | JSON-RPC endpoint |
+| `freshness_seconds` | `300` | Max tx age in seconds |
+| `nonce_cache_ttl` | `600` | Nonce cache TTL in seconds |
+| `nonce_db_path` | `.payclaw_nonces.db` | SQLite file for replay protection |
+| `rate_limit_requests` | `10` | Max requests per IP per window (0 = disabled) |
+| `rate_limit_window_seconds` | `60` | Rate limit window in seconds |
+| `trust_proxy` | `False` | Trust X-Forwarded-For for per-IP rate limiting. Set `True` only when behind a trusted reverse proxy. When `False`, all traffic shares one rate limit bucket. |
+
+---
+
+## Getting testnet USDC
+
+Get free testnet USDC from the [Circle faucet](https://faucet.circle.com) — select **Base Sepolia** and paste your wallet address.
+
+---
+
+## Containerized deployments
+
+The nonce cache is a SQLite file (default: `.payclaw_nonces.db`). In Docker or serverless environments where the filesystem is ephemeral, **mount a persistent volume** or point `nonce_db_path` to a mounted path:
+
+```python
+config = PayclawConfig(
+    price_usdc=0.001,
+    wallet_address="0xYourWallet",
+    nonce_db_path="/data/payclaw_nonces.db",  # mounted volume
+)
+```
+
+Without persistence, a container restart clears the nonce cache and allows replay attacks within the `freshness_seconds` window.
+
+---
+
+## Async frameworks (FastAPI)
+
+The `verify_payment` function uses synchronous HTTP (`requests`). In an async FastAPI app, this blocks the event loop during RPC calls. For high-throughput deployments, wrap with `asyncio.to_thread`:
+
+```python
+import asyncio
+from payclaw import PayclawMiddleware, PayclawConfig
+
+middleware = PayclawMiddleware(config)
+
+@app.post("/tool")
+async def my_tool(request: Request):
+    headers = dict(request.headers)
+    allowed, reason = await asyncio.to_thread(middleware.check, headers)
+    if not allowed:
+        _, body = middleware.payment_required(reason)
+        return JSONResponse(status_code=402, content=body)
+    return {"result": "..."}
+```
+
+---
+
+## Security
+
+- **Replay protection**: SQLite nonce cache survives process restarts. Atomic INSERT OR IGNORE prevents race conditions.
+- **ERC-20 verification**: Reads Transfer event logs from `eth_getTransactionReceipt` — not `tx.value` (which is always 0 for USDC).
+- **Integer math**: USDC amounts compared as integer units (1 USDC = 1,000,000 units). No floating point.
+- **Block timestamp**: Uses on-chain block timestamp for freshness check, not local clock.
+- **Address matching**: Case-insensitive comparison (EIP-55 safe).
+
+---
+
+## Legal
+
+MIT License. payclaw is infrastructure software. Compliance with sanctions (OFAC) and applicable regulations is the responsibility of the deploying party.

payclaw-0.1.0/payclaw/__init__.py

@@ -0,0 +1,23 @@
+"""
+payclaw - Drop-in payment middleware for MCP servers using x402 protocol.
+
+Usage:
+    from payclaw import require_payment, PayclawConfig
+
+    config = PayclawConfig(
+        price_usdc=0.001,
+        wallet_address="0xYourWalletAddress",
+    )
+
+    @require_payment(config)
+    async def my_mcp_tool(request: Request):
+        return {"result": "tool output"}
+"""
+
+from payclaw.config import PayclawConfig, mainnet_config
+from payclaw.middleware import PayclawMiddleware, require_payment
+from payclaw.nonce_cache import NonceCache
+from payclaw.verify import verify_payment
+
+__all__ = ["require_payment", "PayclawMiddleware", "PayclawConfig", "mainnet_config", "NonceCache", "verify_payment"]
+__version__ = "0.1.0"

payclaw-0.1.0/payclaw/config.py

@@ -0,0 +1,55 @@
+from dataclasses import dataclass
+from decimal import Decimal
+
+USDC_BASE_SEPOLIA = "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+RPC_BASE_SEPOLIA = "https://sepolia.base.org"
+
+USDC_BASE_MAINNET = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+RPC_BASE_MAINNET = "https://mainnet.base.org"
+
+
+@dataclass
+class PayclawConfig:
+    price_usdc: float
+    wallet_address: str
+    network: str = "base-sepolia"
+    chain_id: int = 84532
+    usdc_address: str = USDC_BASE_SEPOLIA
+    rpc_url: str = RPC_BASE_SEPOLIA
+    freshness_seconds: int = 300
+    nonce_cache_ttl: int = 600
+    nonce_db_path: str = ".payclaw_nonces.db"
+    rate_limit_requests: int = 10
+    rate_limit_window_seconds: int = 60
+    trust_proxy: bool = False  # set True only when behind a trusted reverse proxy
+
+    def __post_init__(self):
+        if (
+            not isinstance(self.wallet_address, str)
+            or not self.wallet_address.startswith("0x")
+            or len(self.wallet_address) != 42
+        ):
+            raise ValueError(f"Invalid wallet_address: {self.wallet_address!r}")
+        if self.price_usdc <= 0:
+            raise ValueError("price_usdc must be > 0")
+        if self.nonce_cache_ttl < self.freshness_seconds:
+            raise ValueError("nonce_cache_ttl must be >= freshness_seconds")
+        if not self.rpc_url.startswith("https://"):
+            raise ValueError("rpc_url must use HTTPS")
+
+    @property
+    def price_units(self) -> int:
+        return int(Decimal(str(self.price_usdc)) * 1_000_000)
+
+
+def mainnet_config(price_usdc: float, wallet_address: str, **kwargs) -> "PayclawConfig":
+    """Convenience factory for Base mainnet."""
+    return PayclawConfig(
+        price_usdc=price_usdc,
+        wallet_address=wallet_address,
+        network="base",
+        chain_id=8453,
+        usdc_address=USDC_BASE_MAINNET,
+        rpc_url=RPC_BASE_MAINNET,
+        **kwargs,
+    )

payclaw-0.1.0/payclaw/middleware.py

@@ -0,0 +1,195 @@
+import asyncio
+import functools
+import threading
+import time
+from collections import defaultdict
+
+from payclaw.config import PayclawConfig
+from payclaw.nonce_cache import NonceCache
+from payclaw.verify import verify_payment
+
+
+_RATE_LIMIT_REASON = "rate limit exceeded"
+
+
+class _RateLimiter:
+    """Per-key sliding window rate limiter."""
+
+    def __init__(self, max_requests: int, window_seconds: int):
+        self._max = max_requests
+        self._window = window_seconds
+        self._lock = threading.Lock()
+        self._log: dict[str, list[float]] = defaultdict(list)
+        self._calls = 0
+
+    def is_allowed(self, key: str) -> bool:
+        now = time.monotonic()
+        cutoff = now - self._window
+        with self._lock:
+            self._calls += 1
+            if self._calls % 500 == 0:
+                stale = [k for k, ts in self._log.items() if not any(t > cutoff for t in ts)]
+                for k in stale:
+                    del self._log[k]
+            fresh = [t for t in self._log.get(key, []) if t > cutoff]
+            if len(fresh) >= self._max:
+                self._log[key] = fresh
+                return False
+            fresh.append(now)
+            self._log[key] = fresh
+            return True
+
+    def evict(self):
+        """Remove keys with no recent requests. Call periodically if needed."""
+        now = time.monotonic()
+        cutoff = now - self._window
+        with self._lock:
+            stale = [k for k, ts in self._log.items() if not any(t > cutoff for t in ts)]
+            for k in stale:
+                del self._log[k]
+
+
+def _build_402(config: PayclawConfig, reason: str = "") -> dict:
+    body = {
+        "x402": True,
+        "price": str(config.price_usdc),
+        "currency": "USDC",
+        "network": config.network,
+        "recipient": config.wallet_address,
+        "chain_id": config.chain_id,
+    }
+    if reason:
+        body["reason"] = reason
+    return body
+
+
+class PayclawMiddleware:
+    """Framework-agnostic payment gate. Use .check(headers) directly for custom integrations."""
+
+    def __init__(self, config: PayclawConfig):
+        self.config = config
+        self._nonce_cache = NonceCache(config.nonce_db_path, config.nonce_cache_ttl)
+        self._rate_limiter = (
+            _RateLimiter(config.rate_limit_requests, config.rate_limit_window_seconds)
+            if config.rate_limit_requests > 0
+            else None
+        )
+
+    def check(self, headers: dict) -> tuple[bool, str]:
+        """
+        Returns (allowed, reason).
+        headers: any dict-like with HTTP headers (case-insensitive lookup attempted).
+        """
+        if self._rate_limiter:
+            ip = self._client_ip(headers)
+            if not self._rate_limiter.is_allowed(ip):
+                return False, _RATE_LIMIT_REASON
+
+        tx_hash = headers.get("X-Payment") or headers.get("x-payment")
+        if not tx_hash:
+            return False, "missing X-Payment header"
+        tx_hash = tx_hash.strip()
+        if not tx_hash.startswith("0x") or len(tx_hash) != 66:
+            return False, "invalid tx hash format (must be 0x + 64 hex chars)"
+        try:
+            int(tx_hash, 16)
+        except ValueError:
+            return False, "invalid tx hash format (non-hex characters)"
+        return verify_payment(tx_hash, self.config, self._nonce_cache)
+
+    def payment_required(self, reason: str = "") -> tuple[int, dict]:
+        return 402, _build_402(self.config, reason)
+
+    def response_for(self, reason: str) -> tuple[int, dict]:
+        if reason == _RATE_LIMIT_REASON:
+            return 429, {"error": "Too Many Requests", "reason": reason}
+        return self.payment_required(reason)
+
+    def _client_ip(self, headers: dict) -> str:
+        if self.config.trust_proxy:
+            forwarded = headers.get("X-Forwarded-For") or headers.get("x-forwarded-for", "")
+            if forwarded:
+                return forwarded.split(",")[0].strip()
+        return "unknown"
+
+
+def require_payment(config: PayclawConfig):
+    """
+    Decorator that gates any FastAPI or Flask handler behind x402 payment.
+
+    FastAPI: the decorated function must accept `request: Request` as a parameter.
+    Flask: uses flask.request context automatically.
+
+    For other frameworks, use PayclawMiddleware.check(headers) directly.
+
+    Example (FastAPI):
+        @app.post("/tool")
+        @require_payment(config)
+        async def my_tool(request: Request):
+            return {"result": "..."}
+
+    Example (Flask):
+        @app.route("/tool", methods=["POST"])
+        @require_payment(config)
+        def my_tool():
+            return jsonify({"result": "..."})
+    """
+    middleware = PayclawMiddleware(config)
+
+    def decorator(func):
+        if asyncio.iscoroutinefunction(func):
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                headers = _extract_headers(args, kwargs)
+                allowed, reason = middleware.check(headers)
+                if not allowed:
+                    status, body = middleware.response_for(reason)
+                    return _fastapi_response(status, body)
+                return await func(*args, **kwargs)
+            return async_wrapper
+        else:
+            @functools.wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                headers = _flask_headers()
+                allowed, reason = middleware.check(headers)
+                if not allowed:
+                    status, body = middleware.response_for(reason)
+                    return _flask_response(status, body)
+                return func(*args, **kwargs)
+            return sync_wrapper
+
+    return decorator
+
+
+def _extract_headers(args, kwargs) -> dict:
+    """Pull headers from a FastAPI Request object in args or kwargs."""
+    request = kwargs.get("request")
+    if request is None:
+        for a in args:
+            if hasattr(a, "headers"):
+                request = a
+                break
+    if request and hasattr(request, "headers"):
+        return dict(request.headers)
+    return {}
+
+
+def _flask_headers() -> dict:
+    try:
+        from flask import request
+        return dict(request.headers)
+    except (ImportError, RuntimeError):
+        return {}
+
+
+def _fastapi_response(status: int, body: dict):
+    from fastapi.responses import JSONResponse
+    return JSONResponse(status_code=status, content=body)
+
+
+def _flask_response(status: int, body: dict):
+    try:
+        from flask import jsonify, make_response
+        return make_response(jsonify(body), status)
+    except ImportError:
+        return body, status

payclaw-0.1.0/payclaw/nonce_cache.py

@@ -0,0 +1,43 @@
+import sqlite3
+import threading
+import time
+
+
+class NonceCache:
+    def __init__(self, db_path: str, ttl: int = 600):
+        self._ttl = ttl
+        self._lock = threading.Lock()
+        self._conn = sqlite3.connect(db_path, check_same_thread=False)
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute("""
+            CREATE TABLE IF NOT EXISTS used_nonces (
+                tx_hash TEXT PRIMARY KEY,
+                used_at INTEGER NOT NULL
+            )
+        """)
+        self._conn.commit()
+
+    def is_used(self, tx_hash: str) -> bool:
+        row = self._conn.execute(
+            "SELECT 1 FROM used_nonces WHERE tx_hash = ?", (tx_hash.lower(),)
+        ).fetchone()
+        return row is not None
+
+    def mark_used(self, tx_hash: str) -> bool:
+        """Atomically mark a tx hash as used. Returns True only on first use."""
+        tx_hash = tx_hash.lower()
+        now = int(time.time())
+        with self._lock:
+            self._cleanup(now)
+            cursor = self._conn.execute(
+                "INSERT OR IGNORE INTO used_nonces (tx_hash, used_at) VALUES (?, ?)",
+                (tx_hash, now),
+            )
+            self._conn.commit()
+            return cursor.rowcount == 1
+
+    def _cleanup(self, now: int):
+        self._conn.execute(
+            "DELETE FROM used_nonces WHERE used_at < ?",
+            (now - self._ttl,),
+        )