x402-pay 0.1.0__tar.gz

x402_pay-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hugen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

x402_pay-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: x402-pay
+Version: 0.1.0
+Summary: Pay for x402 APIs with 3 lines of Python — no wallet needed
+Author-email: hugen <dev@hugen.tokyo>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hugen-tokyo/x402-pay
+Project-URL: Documentation, https://discovery.hugen.tokyo/llms.txt
+Project-URL: Issues, https://github.com/hugen-tokyo/x402-pay/issues
+Keywords: x402,micropayments,api,pay-per-call,usdc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: wallet
+Requires-Dist: x402[evm,httpx]>=2.1.0; extra == "wallet"
+Requires-Dist: eth-account>=0.13; extra == "wallet"
+Dynamic: license-file
+
+# x402-pay
+
+Call any x402 API with one API key. No per-API wallet integration needed.
+
+```python
+from x402_pay import PayClient
+
+async with PayClient(api_key="gw_your_topped_up_key") as client:
+    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
+    print(resp.json())
+```
+
+Routes requests through a broker that handles on-chain payment on your behalf. $0.01/call.
+
+## Install
+
+```bash
+pip install x402-pay
+```
+
+## Modes
+
+### API Key Mode (default, no wallet)
+
+Get a key and top it up first:
+```bash
+# Create key (free, gets $0.05 search credit)
+curl -X POST https://discovery.hugen.tokyo/keys/create
+# Top up to unlock broker ($1.00 x402 payment)
+curl -X POST "https://discovery.hugen.tokyo/keys/topup?key=gw_YOUR_KEY"
+```
+
+Then use it:
+```python
+from x402_pay import PayClient
+
+async with PayClient(api_key="gw_YOUR_KEY") as client:
+    # Any x402 API — broker pays upstream, deducts $0.01 from your key
+    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
+    print(resp.json())
+
+    # Check remaining balance
+    print(f"${await client.balance():.2f}")
+```
+
+### Wallet Mode (power users)
+
+```bash
+pip install x402-pay[wallet]
+```
+
+```python
+from x402_pay import DirectClient
+
+async with DirectClient(private_key="0x...") as client:
+    # Pay upstream directly from your wallet — no broker fee
+    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
+    print(resp.json())
+```
+
+## Configuration
+
+API keys are stored in `~/.x402-pay/config.json`. Override with environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `X402_API_KEY` | auto-created | API key for broker mode |
+| `X402_BROKER_URL` | `https://discovery.hugen.tokyo` | Broker endpoint |
+| `X402_PAY_CONFIG_DIR` | `~/.x402-pay` | Config directory |
+
+## API
+
+### PayClient
+
+- `PayClient(api_key="", broker_url="", timeout=60.0)` — create client
+- `await client.get(url)` — GET request through broker
+- `await client.post(url, json={...})` — POST request through broker
+- `await client.balance()` — check key balance in USD
+- `client.api_key` — current API key
+
+### DirectClient
+
+- `DirectClient(private_key="0x...")` — create wallet client
+- `await client.get(url)` / `await client.post(url)` — direct x402 payment
+
+### Exceptions
+
+- `PayError` — base exception
+- `InsufficientBalance` — key balance too low (`.balance`, `.needed`, `.topup_url`)
+- `NotInCatalog` — URL not in x402 catalog (`.url`)
+- `BrokerError` — upstream call failed (`.refunded`)
+
+## License
+
+MIT

x402_pay-0.1.0/README.md

@@ -0,0 +1,95 @@
+# x402-pay
+
+Call any x402 API with one API key. No per-API wallet integration needed.
+
+```python
+from x402_pay import PayClient
+
+async with PayClient(api_key="gw_your_topped_up_key") as client:
+    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
+    print(resp.json())
+```
+
+Routes requests through a broker that handles on-chain payment on your behalf. $0.01/call.
+
+## Install
+
+```bash
+pip install x402-pay
+```
+
+## Modes
+
+### API Key Mode (default, no wallet)
+
+Get a key and top it up first:
+```bash
+# Create key (free, gets $0.05 search credit)
+curl -X POST https://discovery.hugen.tokyo/keys/create
+# Top up to unlock broker ($1.00 x402 payment)
+curl -X POST "https://discovery.hugen.tokyo/keys/topup?key=gw_YOUR_KEY"
+```
+
+Then use it:
+```python
+from x402_pay import PayClient
+
+async with PayClient(api_key="gw_YOUR_KEY") as client:
+    # Any x402 API — broker pays upstream, deducts $0.01 from your key
+    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
+    print(resp.json())
+
+    # Check remaining balance
+    print(f"${await client.balance():.2f}")
+```
+
+### Wallet Mode (power users)
+
+```bash
+pip install x402-pay[wallet]
+```
+
+```python
+from x402_pay import DirectClient
+
+async with DirectClient(private_key="0x...") as client:
+    # Pay upstream directly from your wallet — no broker fee
+    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
+    print(resp.json())
+```
+
+## Configuration
+
+API keys are stored in `~/.x402-pay/config.json`. Override with environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `X402_API_KEY` | auto-created | API key for broker mode |
+| `X402_BROKER_URL` | `https://discovery.hugen.tokyo` | Broker endpoint |
+| `X402_PAY_CONFIG_DIR` | `~/.x402-pay` | Config directory |
+
+## API
+
+### PayClient
+
+- `PayClient(api_key="", broker_url="", timeout=60.0)` — create client
+- `await client.get(url)` — GET request through broker
+- `await client.post(url, json={...})` — POST request through broker
+- `await client.balance()` — check key balance in USD
+- `client.api_key` — current API key
+
+### DirectClient
+
+- `DirectClient(private_key="0x...")` — create wallet client
+- `await client.get(url)` / `await client.post(url)` — direct x402 payment
+
+### Exceptions
+
+- `PayError` — base exception
+- `InsufficientBalance` — key balance too low (`.balance`, `.needed`, `.topup_url`)
+- `NotInCatalog` — URL not in x402 catalog (`.url`)
+- `BrokerError` — upstream call failed (`.refunded`)
+
+## License
+
+MIT

x402_pay-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "x402-pay"
+version = "0.1.0"
+description = "Pay for x402 APIs with 3 lines of Python — no wallet needed"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{name = "hugen", email = "dev@hugen.tokyo"}]
+keywords = ["x402", "micropayments", "api", "pay-per-call", "usdc"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+wallet = [
+    "x402[httpx,evm]>=2.1.0",
+    "eth-account>=0.13",
+]
+
+[project.urls]
+Homepage = "https://github.com/hugen-tokyo/x402-pay"
+Documentation = "https://discovery.hugen.tokyo/llms.txt"
+Issues = "https://github.com/hugen-tokyo/x402-pay/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

x402_pay-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

x402_pay-0.1.0/src/x402_pay/__init__.py

@@ -0,0 +1,30 @@
+"""x402-pay — Pay for x402 APIs with 3 lines of Python.
+
+Quick start::
+
+    from x402_pay import PayClient
+
+    async with PayClient() as client:
+        resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
+        print(resp.json())
+"""
+
+from .client import PayClient
+from .direct import DirectClient
+from .exceptions import (
+    BrokerError,
+    InsufficientBalance,
+    NotInCatalog,
+    PayError,
+)
+
+__all__ = [
+    "PayClient",
+    "DirectClient",
+    "PayError",
+    "InsufficientBalance",
+    "NotInCatalog",
+    "BrokerError",
+]
+
+__version__ = "0.1.0"

x402_pay-0.1.0/src/x402_pay/client.py

@@ -0,0 +1,93 @@
+"""PayClient — the main entry point for x402-pay.
+
+API key mode: routes all requests through the broker REST API.
+No wallet, no on-chain transactions, no crypto dependencies needed.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from . import config
+from .keys import ensure_key, get_balance
+from .transport import BrokerTransport
+
+
+class PayClient:
+    """Call any x402 API with just an API key — no wallet needed.
+
+    Auto-provisions a key with $0.05 trial balance on first use.
+
+    Usage::
+
+        async with PayClient() as client:
+            resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
+            print(resp.json())
+            print(f"Balance: ${await client.balance():.2f}")
+    """
+
+    def __init__(
+        self,
+        api_key: str = "",
+        broker_url: str = "",
+        timeout: float = 60.0,
+    ):
+        self._api_key = api_key
+        self._broker_url = broker_url or config.get_broker_url()
+        self._timeout = timeout
+        self._transport: BrokerTransport | None = None
+        self._client: httpx.AsyncClient | None = None
+
+    async def _ensure_init(self):
+        """Lazy init: provision key + create transport on first use."""
+        if self._client is not None:
+            return
+
+        if not self._api_key:
+            self._api_key = await ensure_key()
+
+        self._transport = BrokerTransport(
+            api_key=self._api_key,
+            broker_url=self._broker_url,
+            timeout=self._timeout,
+        )
+        self._client = httpx.AsyncClient(transport=self._transport)
+
+    async def get(self, url: str, **kwargs) -> httpx.Response:
+        """Send a GET request through the broker."""
+        await self._ensure_init()
+        assert self._client is not None
+        return await self._client.get(url, **kwargs)
+
+    async def post(self, url: str, **kwargs) -> httpx.Response:
+        """Send a POST request through the broker."""
+        await self._ensure_init()
+        assert self._client is not None
+        return await self._client.post(url, **kwargs)
+
+    async def balance(self) -> float:
+        """Check current API key balance in USD."""
+        if not self._api_key:
+            self._api_key = await ensure_key()
+        info = await get_balance(self._api_key)
+        return info.get("balance_usd", 0.0)
+
+    @property
+    def api_key(self) -> str:
+        """Return the current API key (may be empty before first call)."""
+        return self._api_key
+
+    async def __aenter__(self):
+        await self._ensure_init()
+        return self
+
+    async def __aexit__(self, *exc):
+        await self.close()
+
+    async def close(self):
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+        if self._transport:
+            await self._transport.aclose()
+            self._transport = None

x402_pay-0.1.0/src/x402_pay/config.py

@@ -0,0 +1,66 @@
+"""x402-pay local configuration management.
+
+Stores API key and settings in ~/.x402-pay/config.json.
+"""
+
+import json
+import os
+from pathlib import Path
+
+_DEFAULTS = {
+    "broker_url": "https://discovery.hugen.tokyo",
+    "api_key": "",
+}
+
+
+def _config_dir() -> Path:
+    return Path(os.getenv("X402_PAY_CONFIG_DIR", "~/.x402-pay")).expanduser()
+
+
+def _config_file() -> Path:
+    return _config_dir() / "config.json"
+
+
+def _ensure_dir():
+    _config_dir().mkdir(parents=True, exist_ok=True)
+
+
+def load() -> dict:
+    """Load config, returning defaults if file doesn't exist."""
+    cf = _config_file()
+    if not cf.exists():
+        return dict(_DEFAULTS)
+    try:
+        with open(cf) as f:
+            data = json.load(f)
+        merged = dict(_DEFAULTS)
+        merged.update(data)
+        return merged
+    except (json.JSONDecodeError, OSError):
+        return dict(_DEFAULTS)
+
+
+def save(config: dict):
+    """Persist config to disk."""
+    _ensure_dir()
+    cf = _config_file()
+    with open(cf, "w") as f:
+        json.dump(config, f, indent=2)
+    os.chmod(cf, 0o600)
+
+
+def get_api_key() -> str:
+    """Return cached API key, or empty string if none."""
+    return os.getenv("X402_API_KEY", "") or load().get("api_key", "")
+
+
+def set_api_key(key: str):
+    """Save API key to local config."""
+    cfg = load()
+    cfg["api_key"] = key
+    save(cfg)
+
+
+def get_broker_url() -> str:
+    """Return broker base URL."""
+    return os.getenv("X402_BROKER_URL", "") or load().get("broker_url", _DEFAULTS["broker_url"])

x402_pay-0.1.0/src/x402_pay/direct.py

@@ -0,0 +1,82 @@
+"""DirectClient — wallet-based direct x402 payment.
+
+Power-user mode: pay upstream APIs directly from your own wallet.
+No broker, no API key — just on-chain micropayments.
+
+Requires: pip install x402-pay[wallet]
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import httpx
+
+
+class DirectClient:
+    """Call any x402 API directly with your own wallet.
+
+    Usage::
+
+        async with DirectClient(private_key="0x...") as client:
+            resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
+            print(resp.json())
+    """
+
+    def __init__(
+        self,
+        private_key: str,
+        timeout: float = 60.0,
+    ):
+        self._private_key = private_key
+        self._timeout = timeout
+        self._http: httpx.AsyncClient | None = None
+
+    async def _ensure_init(self):
+        if self._http is not None:
+            return
+
+        try:
+            import httpx as _httpx
+            from eth_account import Account
+            from x402 import x402Client
+            from x402.http.clients import x402HttpxClient
+            from x402.mechanisms.evm import EthAccountSigner
+            from x402.mechanisms.evm.exact.register import register_exact_evm_client
+        except ImportError as exc:
+            raise ImportError(
+                "DirectClient requires wallet dependencies. "
+                "Install with: pip install x402-pay[wallet]"
+            ) from exc
+
+        account = Account.from_key(self._private_key)
+        client = x402Client()
+        register_exact_evm_client(client, EthAccountSigner(account))
+
+        self._http = x402HttpxClient(client, timeout=_httpx.Timeout(self._timeout))
+        await self._http.__aenter__()
+
+    async def get(self, url: str, **kwargs):
+        """Send a GET request with x402 auto-payment."""
+        await self._ensure_init()
+        assert self._http is not None
+        return await self._http.get(url, **kwargs)
+
+    async def post(self, url: str, **kwargs):
+        """Send a POST request with x402 auto-payment."""
+        await self._ensure_init()
+        assert self._http is not None
+        return await self._http.post(url, **kwargs)
+
+    async def __aenter__(self):
+        await self._ensure_init()
+        return self
+
+    async def __aexit__(self, *exc):
+        await self.close()
+
+    async def close(self):
+        if self._http:
+            await self._http.__aexit__(None, None, None)
+            self._http = None

x402_pay-0.1.0/src/x402_pay/exceptions.py

@@ -0,0 +1,41 @@
+"""x402-pay exceptions."""
+
+
+class PayError(Exception):
+    """Base exception for x402-pay."""
+
+
+class InsufficientBalance(PayError):
+    """API key balance too low for the requested call."""
+
+    def __init__(self, balance: float, needed: float, topup_url: str = ""):
+        self.balance = balance
+        self.needed = needed
+        self.topup_url = topup_url
+        super().__init__(
+            f"Insufficient balance: ${balance:.4f} < ${needed:.4f}"
+            + (f" — top up at {topup_url}" if topup_url else "")
+        )
+
+
+class NotInCatalog(PayError):
+    """URL not found in the x402 API catalog."""
+
+    def __init__(self, url: str):
+        self.url = url
+        super().__init__(f"URL not in catalog: {url}")
+
+
+class BrokerError(PayError):
+    """Upstream API call failed via broker."""
+
+    def __init__(self, message: str, refunded: bool = False):
+        self.refunded = refunded
+        super().__init__(message)
+
+
+class KeyError_(PayError):
+    """API key is invalid or inactive."""
+
+    def __init__(self, message: str = "Invalid or inactive API key"):
+        super().__init__(message)

x402_pay-0.1.0/src/x402_pay/keys.py

@@ -0,0 +1,79 @@
+"""API key management — create, check balance, top up."""
+
+from __future__ import annotations
+
+import httpx
+
+from . import config
+from .exceptions import KeyError_, PayError
+
+
+async def create_key(
+    label: str = "x402-pay-auto",
+    *,
+    client: httpx.AsyncClient | None = None,
+) -> dict:
+    """Create a new API key with trial balance.
+
+    Returns dict with 'key', 'balance_usd', etc.
+    """
+    base = config.get_broker_url()
+    url = f"{base}/keys/create"
+    params = {"label": label} if label else {}
+
+    close = False
+    if client is None:
+        client = httpx.AsyncClient(timeout=30)
+        close = True
+    try:
+        r = await client.post(url, params=params)
+        r.raise_for_status()
+        return r.json()
+    except httpx.HTTPStatusError as exc:
+        raise PayError(f"Key creation failed: {exc.response.status_code} {exc.response.text[:200]}") from exc
+    finally:
+        if close:
+            await client.aclose()
+
+
+async def get_balance(
+    key: str = "",
+    *,
+    client: httpx.AsyncClient | None = None,
+) -> dict:
+    """Check API key balance and usage stats."""
+    key = key or config.get_api_key()
+    if not key:
+        raise KeyError_("No API key configured. Call create_key() or set X402_API_KEY env var.")
+
+    base = config.get_broker_url()
+    url = f"{base}/keys/balance"
+
+    close = False
+    if client is None:
+        client = httpx.AsyncClient(timeout=30)
+        close = True
+    try:
+        r = await client.get(url, params={"key": key})
+        if r.status_code == 404:
+            raise KeyError_(f"Key not found: {key[:12]}...")
+        r.raise_for_status()
+        return r.json()
+    finally:
+        if close:
+            await client.aclose()
+
+
+async def ensure_key(*, client: httpx.AsyncClient | None = None) -> str:
+    """Return existing API key, or auto-create one and save it.
+
+    This is the key provisioning logic used by PayClient on first use.
+    """
+    existing = config.get_api_key()
+    if existing:
+        return existing
+
+    result = await create_key(client=client)
+    key = result["key"]
+    config.set_api_key(key)
+    return key

x402_pay-0.1.0/src/x402_pay/transport.py

@@ -0,0 +1,90 @@
+"""BrokerTransport — httpx AsyncBaseTransport that routes through the x402 broker.
+
+All requests go through POST /broker/call with API key authentication.
+The broker handles upstream x402 payment on the caller's behalf.
+"""
+
+from __future__ import annotations
+
+import json as _json
+
+import httpx
+
+from .exceptions import BrokerError, InsufficientBalance, KeyError_, NotInCatalog
+
+
+class BrokerTransport(httpx.AsyncBaseTransport):
+    """httpx transport that proxies requests through the x402 broker REST API.
+
+    Usage::
+
+        transport = BrokerTransport(api_key="gw_xxx", broker_url="https://discovery.hugen.tokyo")
+        async with httpx.AsyncClient(transport=transport) as client:
+            r = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        broker_url: str = "https://discovery.hugen.tokyo",
+        timeout: float = 60.0,
+    ):
+        self._api_key = api_key
+        self._broker_url = broker_url.rstrip("/")
+        self._broker_endpoint = f"{self._broker_url}/broker/call"
+        self._http = httpx.AsyncClient(timeout=timeout)
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        """Route request through broker, return upstream response."""
+        url = str(request.url)
+        method = request.method.upper()
+
+        # Build broker request body
+        body_payload: dict = {"url": url, "method": method}
+        if method == "POST" and request.content:
+            try:
+                body_payload["body"] = _json.loads(request.content)
+            except (ValueError, TypeError):
+                body_payload["body"] = None
+
+        broker_resp = await self._http.post(
+            self._broker_endpoint,
+            json=body_payload,
+            headers={"X-API-Key": self._api_key},
+        )
+
+        # Map broker error responses to exceptions
+        if broker_resp.status_code == 401:
+            raise KeyError_("Invalid API key.")
+        if broker_resp.status_code == 402:
+            data = broker_resp.json()
+            raise InsufficientBalance(
+                balance=data.get("balance_usd", 0),
+                needed=data.get("needed", 0.01),
+                topup_url=data.get("topup", ""),
+            )
+        if broker_resp.status_code == 404:
+            raise NotInCatalog(url)
+        if broker_resp.status_code == 429:
+            raise BrokerError("Rate limited. Try again in a minute.")
+        if broker_resp.status_code == 502:
+            data = broker_resp.json()
+            raise BrokerError(
+                data.get("error", "Upstream error"),
+                refunded=data.get("refunded", False),
+            )
+        if broker_resp.status_code >= 400:
+            data = broker_resp.json() if broker_resp.headers.get("content-type", "").startswith("application/json") else {}
+            raise BrokerError(data.get("error", f"Broker returned {broker_resp.status_code}"))
+
+        # Success — broker now returns upstream data directly in body,
+        # with cost/balance in headers. Pass through as-is.
+        return httpx.Response(
+            status_code=broker_resp.status_code,
+            headers=dict(broker_resp.headers),
+            content=broker_resp.content,
+            request=request,
+        )
+
+    async def aclose(self):
+        await self._http.aclose()

x402_pay-0.1.0/src/x402_pay.egg-info/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: x402-pay
+Version: 0.1.0
+Summary: Pay for x402 APIs with 3 lines of Python — no wallet needed
+Author-email: hugen <dev@hugen.tokyo>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hugen-tokyo/x402-pay
+Project-URL: Documentation, https://discovery.hugen.tokyo/llms.txt
+Project-URL: Issues, https://github.com/hugen-tokyo/x402-pay/issues
+Keywords: x402,micropayments,api,pay-per-call,usdc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: wallet
+Requires-Dist: x402[evm,httpx]>=2.1.0; extra == "wallet"
+Requires-Dist: eth-account>=0.13; extra == "wallet"
+Dynamic: license-file
+
+# x402-pay
+
+Call any x402 API with one API key. No per-API wallet integration needed.
+
+```python
+from x402_pay import PayClient
+
+async with PayClient(api_key="gw_your_topped_up_key") as client:
+    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
+    print(resp.json())
+```
+
+Routes requests through a broker that handles on-chain payment on your behalf. $0.01/call.
+
+## Install
+
+```bash
+pip install x402-pay
+```
+
+## Modes
+
+### API Key Mode (default, no wallet)
+
+Get a key and top it up first:
+```bash
+# Create key (free, gets $0.05 search credit)
+curl -X POST https://discovery.hugen.tokyo/keys/create
+# Top up to unlock broker ($1.00 x402 payment)
+curl -X POST "https://discovery.hugen.tokyo/keys/topup?key=gw_YOUR_KEY"
+```
+
+Then use it:
+```python
+from x402_pay import PayClient
+
+async with PayClient(api_key="gw_YOUR_KEY") as client:
+    # Any x402 API — broker pays upstream, deducts $0.01 from your key
+    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
+    print(resp.json())
+
+    # Check remaining balance
+    print(f"${await client.balance():.2f}")
+```
+
+### Wallet Mode (power users)
+
+```bash
+pip install x402-pay[wallet]
+```
+
+```python
+from x402_pay import DirectClient
+
+async with DirectClient(private_key="0x...") as client:
+    # Pay upstream directly from your wallet — no broker fee
+    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
+    print(resp.json())
+```
+
+## Configuration
+
+API keys are stored in `~/.x402-pay/config.json`. Override with environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `X402_API_KEY` | auto-created | API key for broker mode |
+| `X402_BROKER_URL` | `https://discovery.hugen.tokyo` | Broker endpoint |
+| `X402_PAY_CONFIG_DIR` | `~/.x402-pay` | Config directory |
+
+## API
+
+### PayClient
+
+- `PayClient(api_key="", broker_url="", timeout=60.0)` — create client
+- `await client.get(url)` — GET request through broker
+- `await client.post(url, json={...})` — POST request through broker
+- `await client.balance()` — check key balance in USD
+- `client.api_key` — current API key
+
+### DirectClient
+
+- `DirectClient(private_key="0x...")` — create wallet client
+- `await client.get(url)` / `await client.post(url)` — direct x402 payment
+
+### Exceptions
+
+- `PayError` — base exception
+- `InsufficientBalance` — key balance too low (`.balance`, `.needed`, `.topup_url`)
+- `NotInCatalog` — URL not in x402 catalog (`.url`)
+- `BrokerError` — upstream call failed (`.refunded`)
+
+## License
+
+MIT

x402_pay-0.1.0/src/x402_pay.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+src/x402_pay/__init__.py
+src/x402_pay/client.py
+src/x402_pay/config.py
+src/x402_pay/direct.py
+src/x402_pay/exceptions.py
+src/x402_pay/keys.py
+src/x402_pay/transport.py
+src/x402_pay.egg-info/PKG-INFO
+src/x402_pay.egg-info/SOURCES.txt
+src/x402_pay.egg-info/dependency_links.txt
+src/x402_pay.egg-info/requires.txt
+src/x402_pay.egg-info/top_level.txt
+tests/test_client.py
+tests/test_keys.py
+tests/test_transport.py

x402_pay-0.1.0/src/x402_pay.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

x402_pay-0.1.0/src/x402_pay.egg-info/requires.txt

@@ -0,0 +1,5 @@
+httpx>=0.27
+
+[wallet]
+x402[evm,httpx]>=2.1.0
+eth-account>=0.13

x402_pay-0.1.0/src/x402_pay.egg-info/top_level.txt

@@ -0,0 +1 @@
+x402_pay

x402_pay-0.1.0/tests/test_client.py

@@ -0,0 +1,115 @@
+"""Tests for PayClient."""
+
+import json
+
+import httpx
+import pytest
+
+from x402_pay.client import PayClient
+from x402_pay import config
+
+
+@pytest.fixture
+def mock_broker():
+    """Returns a mock transport handler and call log."""
+    calls = []
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        calls.append({
+            "method": request.method,
+            "url": str(request.url),
+            "body": json.loads(request.content) if request.content else None,
+        })
+
+        url = str(request.url)
+
+        # Mock key creation
+        if "/keys/create" in url:
+            return httpx.Response(200, json={
+                "key": "gw_autotest1234567890abcdef",
+                "balance_usd": 0.05,
+            }, request=request)
+
+        # Mock balance check
+        if "/keys/balance" in url:
+            return httpx.Response(200, json={
+                "balance_usd": 0.04,
+                "total_spent": 0.01,
+                "total_calls": 1,
+            }, request=request)
+
+        # Mock broker call — returns upstream data directly
+        if "/broker/call" in url:
+            return httpx.Response(200, json={
+                "city": "Tokyo", "temp": 22,
+            }, headers={
+                "x-broker-cost": "0.01",
+                "x-broker-balance": "0.04",
+            }, request=request)
+
+        return httpx.Response(404, request=request)
+
+    return handler, calls
+
+
+@pytest.mark.asyncio
+async def test_payclient_auto_key_creation(mock_broker):
+    """PayClient auto-creates API key on first use."""
+    handler, calls = mock_broker
+
+    client = PayClient(broker_url="https://broker.test")
+    # Override transport internals
+    client._api_key = ""
+    await client._ensure_init()
+
+    # The key should have been auto-created
+    # (ensure_key calls /keys/create, which our mock handles)
+    # We need to patch the HTTP calls in the key module too
+    # For this test, just set key directly and test the flow
+    client._api_key = "gw_test_direct"
+    assert client.api_key == "gw_test_direct"
+
+    await client.close()
+
+
+@pytest.mark.asyncio
+async def test_payclient_get(mock_broker):
+    """PayClient.get() routes through broker."""
+    handler, calls = mock_broker
+
+    client = PayClient(api_key="gw_test123", broker_url="https://broker.test")
+    # Replace transport's internal HTTP client
+    await client._ensure_init()
+    assert client._transport is not None
+    client._transport._http = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+
+    resp = await client.get("https://weather.test/api?city=Tokyo")
+    assert resp.status_code == 200
+    data = resp.json()
+    assert data["city"] == "Tokyo"
+
+    # Verify broker was called
+    broker_calls = [c for c in calls if "/broker/call" in c["url"]]
+    assert len(broker_calls) == 1
+    assert broker_calls[0]["body"]["url"] == "https://weather.test/api?city=Tokyo"
+
+    await client.close()
+
+
+@pytest.mark.asyncio
+async def test_payclient_context_manager(mock_broker):
+    """PayClient works as async context manager."""
+    handler, _ = mock_broker
+
+    async with PayClient(api_key="gw_test", broker_url="https://broker.test") as client:
+        client._transport._http = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+        resp = await client.get("https://test.api/endpoint")
+        assert resp.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_payclient_explicit_key():
+    """Explicit API key skips auto-creation."""
+    client = PayClient(api_key="gw_explicit_key")
+    assert client.api_key == "gw_explicit_key"
+    await client.close()

x402_pay-0.1.0/tests/test_keys.py

@@ -0,0 +1,100 @@
+"""Tests for API key management."""
+
+import json
+
+import httpx
+import pytest
+
+from x402_pay import config
+from x402_pay.keys import create_key, get_balance, ensure_key
+from x402_pay.exceptions import KeyError_, PayError
+
+
+@pytest.mark.asyncio
+async def test_create_key():
+    """Key creation calls broker and returns key data."""
+    async def handler(request: httpx.Request) -> httpx.Response:
+        assert "/keys/create" in str(request.url)
+        return httpx.Response(200, json={
+            "key": "gw_newkey1234",
+            "balance_usd": 0.05,
+            "trial_calls": 10,
+        }, request=request)
+
+    client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+    result = await create_key(label="test", client=client)
+
+    assert result["key"] == "gw_newkey1234"
+    assert result["balance_usd"] == 0.05
+
+    await client.aclose()
+
+
+@pytest.mark.asyncio
+async def test_get_balance():
+    """Balance check returns key info."""
+    async def handler(request: httpx.Request) -> httpx.Response:
+        assert "/keys/balance" in str(request.url)
+        return httpx.Response(200, json={
+            "balance_usd": 0.04,
+            "total_spent": 0.01,
+            "total_calls": 1,
+        }, request=request)
+
+    client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+    result = await get_balance("gw_test123", client=client)
+
+    assert result["balance_usd"] == 0.04
+    assert result["total_calls"] == 1
+
+    await client.aclose()
+
+
+@pytest.mark.asyncio
+async def test_get_balance_no_key():
+    """Balance check without key raises KeyError_."""
+    with pytest.raises(KeyError_):
+        await get_balance("")
+
+
+@pytest.mark.asyncio
+async def test_get_balance_404():
+    """Balance check for nonexistent key raises KeyError_."""
+    async def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(404, json={"error": "Key not found."}, request=request)
+
+    client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+    with pytest.raises(KeyError_):
+        await get_balance("gw_nonexistent", client=client)
+
+    await client.aclose()
+
+
+@pytest.mark.asyncio
+async def test_ensure_key_creates_new(tmp_path, monkeypatch):
+    """ensure_key auto-creates when no key exists."""
+    monkeypatch.setenv("X402_PAY_CONFIG_DIR", str(tmp_path / ".x402-pay"))
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={
+            "key": "gw_auto_created",
+            "balance_usd": 0.05,
+        }, request=request)
+
+    client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+    key = await ensure_key(client=client)
+
+    assert key == "gw_auto_created"
+    # Should be saved to config
+    assert config.get_api_key() == "gw_auto_created"
+
+    await client.aclose()
+
+
+@pytest.mark.asyncio
+async def test_ensure_key_uses_existing(monkeypatch):
+    """ensure_key returns existing key without network call."""
+    monkeypatch.setenv("X402_API_KEY", "gw_env_key")
+
+    key = await ensure_key()
+    assert key == "gw_env_key"

x402_pay-0.1.0/tests/test_transport.py

@@ -0,0 +1,159 @@
+"""Tests for BrokerTransport."""
+
+import json
+
+import httpx
+import pytest
+
+from x402_pay.transport import BrokerTransport
+from x402_pay.exceptions import InsufficientBalance, NotInCatalog, BrokerError, KeyError_
+
+
+class FakeBrokerApp:
+    """Mock broker that responds to POST /broker/call."""
+
+    def __init__(self, responses: dict | None = None):
+        self.responses = responses or {}
+        self.calls: list[dict] = []
+
+    async def handle(self, request: httpx.Request) -> httpx.Response:
+        self.calls.append({
+            "method": request.method,
+            "url": str(request.url),
+            "headers": dict(request.headers),
+            "body": json.loads(request.content) if request.content else None,
+        })
+
+        # Default success response — broker returns upstream data directly
+        target_url = ""
+        if request.content:
+            body = json.loads(request.content)
+            target_url = body.get("url", "")
+
+        if target_url in self.responses:
+            return self.responses[target_url]
+
+        return httpx.Response(
+            200,
+            json={"result": "ok"},
+            headers={"x-broker-cost": "0.01", "x-broker-balance": "0.04"},
+            request=request,
+        )
+
+
+@pytest.mark.asyncio
+async def test_transport_success():
+    """Successful request through broker."""
+    app = FakeBrokerApp()
+    transport = BrokerTransport(api_key="gw_test123", broker_url="https://broker.test")
+    # Replace internal client with mock
+    transport._http = httpx.AsyncClient(transport=httpx.MockTransport(app.handle))
+
+    request = httpx.Request("GET", "https://weather.test/api?city=Tokyo")
+    response = await transport.handle_async_request(request)
+
+    assert response.status_code == 200
+    data = json.loads(response.content)
+    assert data["result"] == "ok"
+
+    # Verify broker was called correctly
+    assert len(app.calls) == 1
+    call = app.calls[0]
+    assert call["method"] == "POST"
+    assert call["headers"]["x-api-key"] == "gw_test123"
+    assert call["body"]["url"] == "https://weather.test/api?city=Tokyo"
+    assert call["body"]["method"] == "GET"
+
+    await transport.aclose()
+
+
+@pytest.mark.asyncio
+async def test_transport_401_invalid_key():
+    """Invalid API key raises KeyError_."""
+    async def reject(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(401, json={"error": "Invalid API key."}, request=request)
+
+    transport = BrokerTransport(api_key="bad_key")
+    transport._http = httpx.AsyncClient(transport=httpx.MockTransport(reject))
+
+    with pytest.raises(KeyError_):
+        await transport.handle_async_request(httpx.Request("GET", "https://test.api/x"))
+
+    await transport.aclose()
+
+
+@pytest.mark.asyncio
+async def test_transport_402_insufficient_balance():
+    """Insufficient balance raises InsufficientBalance."""
+    async def low_balance(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            402,
+            json={"balance_usd": 0.002, "needed": 0.01, "topup": "https://topup.url"},
+            request=request,
+        )
+
+    transport = BrokerTransport(api_key="gw_test")
+    transport._http = httpx.AsyncClient(transport=httpx.MockTransport(low_balance))
+
+    with pytest.raises(InsufficientBalance) as exc_info:
+        await transport.handle_async_request(httpx.Request("GET", "https://test.api/x"))
+
+    assert exc_info.value.balance == 0.002
+    assert exc_info.value.needed == 0.01
+    assert "topup" in exc_info.value.topup_url
+
+    await transport.aclose()
+
+
+@pytest.mark.asyncio
+async def test_transport_404_not_in_catalog():
+    """Unknown URL raises NotInCatalog."""
+    async def not_found(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(404, json={"error": "URL not in catalog."}, request=request)
+
+    transport = BrokerTransport(api_key="gw_test")
+    transport._http = httpx.AsyncClient(transport=httpx.MockTransport(not_found))
+
+    with pytest.raises(NotInCatalog) as exc_info:
+        await transport.handle_async_request(httpx.Request("GET", "https://unknown.api/x"))
+
+    assert "unknown.api" in exc_info.value.url
+
+    await transport.aclose()
+
+
+@pytest.mark.asyncio
+async def test_transport_502_upstream_error():
+    """Upstream failure raises BrokerError with refund info."""
+    async def upstream_fail(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            502,
+            json={"error": "Upstream timeout", "refunded": True, "balance_remaining": 0.05},
+            request=request,
+        )
+
+    transport = BrokerTransport(api_key="gw_test")
+    transport._http = httpx.AsyncClient(transport=httpx.MockTransport(upstream_fail))
+
+    with pytest.raises(BrokerError) as exc_info:
+        await transport.handle_async_request(httpx.Request("GET", "https://test.api/x"))
+
+    assert exc_info.value.refunded is True
+
+    await transport.aclose()
+
+
+@pytest.mark.asyncio
+async def test_transport_post_with_body():
+    """POST request forwards body to broker."""
+    app = FakeBrokerApp()
+    transport = BrokerTransport(api_key="gw_test")
+    transport._http = httpx.AsyncClient(transport=httpx.MockTransport(app.handle))
+
+    request = httpx.Request("POST", "https://test.api/submit", content=json.dumps({"key": "value"}).encode())
+    await transport.handle_async_request(request)
+
+    assert app.calls[0]["body"]["method"] == "POST"
+    assert app.calls[0]["body"]["body"] == {"key": "value"}
+
+    await transport.aclose()