feeless402 0.2.2__tar.gz → 0.2.4__tar.gz

{feeless402-0.2.2 → feeless402-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feeless402
-Version: 0.2.2
+Version: 0.2.4
 Summary: Feeless x402 micropayments for AI agents — self-custodied XNO wallet, pay-per-call client, merchant server with railHint, faucet, and MCP server
 License: MIT
 Project-URL: Homepage, https://feeless402.com
@@ -103,13 +103,23 @@ but don't fire concurrent payments from one wallet).
 
 ## Status
 
-Beta (v0.2.2). Proven on mainnet with real funds: live paid calls to
+Beta (v0.2.4). Proven on mainnet with real funds: live paid calls to
 NanoGPT ($0.0000096/call, confirmed on-ledger), full merchant loop
 (verify → settle → confirm, no facilitator), PoW-gated faucet claims,
 and a complete stranger-agent lifecycle (fresh wallet → PoW claim →
 paid API call → confirmed) in under 3 minutes. 13-test suite covers the
 payment path offline. Not audited — keep only working capital in it.
 
+## Listings
+
+- [gold-402](https://github.com/Haustorium12/gold-402) — curated x402
+  directory; the `/premium` reference endpoint is shelved under APIs and
+  this Python client under SDKs.
+- [Official MCP registry](https://registry.modelcontextprotocol.io) —
+  `com.feeless402/nano-pay`.
+- [agent-tools.cloud](https://agent-tools.cloud) — x402, MCP, and A2A
+  entries.
+
 ## Security notes (read before holding real funds)
 
 - **Self-custody**: the seed lives only in `~/.nano-pay/*.json` (0600).

{feeless402-0.2.2 → feeless402-0.2.4}/README.md

@@ -70,13 +70,23 @@ but don't fire concurrent payments from one wallet).
 
 ## Status
 
-Beta (v0.2.2). Proven on mainnet with real funds: live paid calls to
+Beta (v0.2.4). Proven on mainnet with real funds: live paid calls to
 NanoGPT ($0.0000096/call, confirmed on-ledger), full merchant loop
 (verify → settle → confirm, no facilitator), PoW-gated faucet claims,
 and a complete stranger-agent lifecycle (fresh wallet → PoW claim →
 paid API call → confirmed) in under 3 minutes. 13-test suite covers the
 payment path offline. Not audited — keep only working capital in it.
 
+## Listings
+
+- [gold-402](https://github.com/Haustorium12/gold-402) — curated x402
+  directory; the `/premium` reference endpoint is shelved under APIs and
+  this Python client under SDKs.
+- [Official MCP registry](https://registry.modelcontextprotocol.io) —
+  `com.feeless402/nano-pay`.
+- [agent-tools.cloud](https://agent-tools.cloud) — x402, MCP, and A2A
+  entries.
+
 ## Security notes (read before holding real funds)
 
 - **Self-custody**: the seed lives only in `~/.nano-pay/*.json` (0600).

{feeless402-0.2.2 → feeless402-0.2.4}/feeless402.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feeless402
-Version: 0.2.2
+Version: 0.2.4
 Summary: Feeless x402 micropayments for AI agents — self-custodied XNO wallet, pay-per-call client, merchant server with railHint, faucet, and MCP server
 License: MIT
 Project-URL: Homepage, https://feeless402.com
@@ -103,13 +103,23 @@ but don't fire concurrent payments from one wallet).
 
 ## Status
 
-Beta (v0.2.2). Proven on mainnet with real funds: live paid calls to
+Beta (v0.2.4). Proven on mainnet with real funds: live paid calls to
 NanoGPT ($0.0000096/call, confirmed on-ledger), full merchant loop
 (verify → settle → confirm, no facilitator), PoW-gated faucet claims,
 and a complete stranger-agent lifecycle (fresh wallet → PoW claim →
 paid API call → confirmed) in under 3 minutes. 13-test suite covers the
 payment path offline. Not audited — keep only working capital in it.
 
+## Listings
+
+- [gold-402](https://github.com/Haustorium12/gold-402) — curated x402
+  directory; the `/premium` reference endpoint is shelved under APIs and
+  this Python client under SDKs.
+- [Official MCP registry](https://registry.modelcontextprotocol.io) —
+  `com.feeless402/nano-pay`.
+- [agent-tools.cloud](https://agent-tools.cloud) — x402, MCP, and A2A
+  entries.
+
 ## Security notes (read before holding real funds)
 
 - **Self-custody**: the seed lives only in `~/.nano-pay/*.json` (0600).

{feeless402-0.2.2 → feeless402-0.2.4}/feeless402.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ feeless402.egg-info/entry_points.txt
 feeless402.egg-info/requires.txt
 feeless402.egg-info/top_level.txt
 nano_pay/__init__.py
+nano_pay/a2a_remote.py
 nano_pay/cli.py
 nano_pay/mcp_remote.py
 nano_pay/mcp_server.py

{feeless402-0.2.2 → feeless402-0.2.4}/nano_pay/__init__.py

@@ -1,6 +1,6 @@
 """nano-pay: self-custodied Nano (XNO) wallet + x402 payment client for AI agents."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"
 
 RAW_PER_XNO = 10**30
 

feeless402-0.2.4/nano_pay/a2a_remote.py

@@ -0,0 +1,230 @@
+"""Feeless402 A2A agent — READ-ONLY, no wallet.
+
+Public Agent2Agent (A2A protocol 0.3.0) endpoint at https://feeless402.com/a2a
+so any A2A client can ask, in one delegated message, what an x402 call costs
+on every rail its server offers. Same read-only tools as the remote MCP
+endpoint (mcp_remote.py); it holds no keys and can spend nothing. The agent
+replies instantly with a Message — it never creates long-running tasks.
+
+Agent card: https://feeless402.com/.well-known/agent-card.json (static copy
+in the site root; also served here at GET /.well-known/agent-card.json).
+
+Run:  python -m nano_pay.a2a_remote   (127.0.0.1:8404, JSON-RPC at POST /a2a)
+"""
+
+import json
+import re
+import uuid
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from . import __version__, raw_to_xno
+from .mcp_remote import FAUCET_ADDR, FAUCET_CLAIM_XNO, _fetch_402
+from .rpc import RPC
+from .x402 import collect_offers, compare_rails, offer_amount_raw, parse_quote, pick_nano_offer
+
+AGENT_URL = "https://feeless402.com/a2a"
+URL_RE = re.compile(r"https?://[^\s\"'<>]+")
+
+CARD = {
+    "protocolVersion": "0.3.0",
+    "name": "Feeless402 Rail Quote",
+    "description": (
+        "Read-only x402 pricing agent: send it any x402 (HTTP 402 Payment "
+        "Required) API URL and it fetches the live payment quote without "
+        "paying, then prices the same call on every rail the server offers — "
+        "gas rails floor micro-prices; the feeless Nano (XNO) rail quotes the "
+        "true metered amount. Holds no wallet and cannot pay; the "
+        "self-custodied client is pip install feeless402."
+    ),
+    "url": AGENT_URL,
+    "preferredTransport": "JSONRPC",
+    "version": __version__,
+    "provider": {"organization": "Feeless402", "url": "https://feeless402.com"},
+    "documentationUrl": "https://feeless402.com/docs.html",
+    "capabilities": {
+        "streaming": False,
+        "pushNotifications": False,
+        "stateTransitionHistory": False,
+    },
+    "defaultInputModes": ["text/plain"],
+    "defaultOutputModes": ["application/json", "text/plain"],
+    "securitySchemes": {},
+    "security": [],
+    "skills": [
+        {
+            "id": "x402-quote-and-compare",
+            "name": "Quote an x402 endpoint across rails",
+            "description": (
+                "Give it an x402 API URL (optionally with a JSON body). It "
+                "returns the endpoint's live 402 quote — full offer menu, "
+                "XNO price, destination — plus a per-rail payer-cost "
+                "comparison. Read-only: nothing is paid."
+            ),
+            "tags": ["x402", "pricing", "402", "nano", "rails"],
+            "examples": [
+                "quote https://feeless402.com/premium",
+                "what would https://nano-gpt.com/api/v1/chat/completions cost per call?",
+            ],
+            "inputModes": ["text/plain"],
+            "outputModes": ["application/json", "text/plain"],
+        },
+        {
+            "id": "faucet-info",
+            "name": "Starter-funds faucet status",
+            "description": (
+                "Live status of the Feeless402 onboarding faucet: address, "
+                "per-claim amount, remaining claims, and how an agent claims."
+            ),
+            "tags": ["faucet", "nano", "onboarding"],
+            "examples": ["faucet status"],
+            "inputModes": ["text/plain"],
+            "outputModes": ["application/json", "text/plain"],
+        },
+    ],
+}
+
+app = FastAPI(openapi_url=None, docs_url=None, redoc_url=None)
+
+
+@app.get("/.well-known/agent-card.json")
+@app.get("/a2a/.well-known/agent-card.json")
+def agent_card():
+    return CARD
+
+
+@app.get("/a2a")
+def a2a_get():
+    return {
+        "protocol": "a2a",
+        "endpoint": AGENT_URL,
+        "agent_card": "https://feeless402.com/.well-known/agent-card.json",
+        "usage": "POST JSON-RPC 2.0, method message/send",
+    }
+
+
+def _texts(message: dict) -> str:
+    parts = message.get("parts") or []
+    return " ".join(p.get("text", "") for p in parts if p.get("kind") == "text")
+
+
+def _quote_and_compare(url: str, method: str = "GET", json_body: str = "") -> dict:
+    r = _fetch_402(url, method, json_body)
+    if r.status_code != 402:
+        return {"url": url, "status_code": r.status_code, "note": "not a 402 endpoint"}
+    quote = parse_quote(r)
+    out = {"url": url, "offers": collect_offers(quote), "compare": compare_rails(quote)}
+    try:
+        offer = pick_nano_offer(quote)
+        out["nano"] = {
+            "amount_xno": raw_to_xno(offer_amount_raw(offer)),
+            "pay_to": offer.get("payTo") or offer.get("pay_to"),
+        }
+    except Exception as e:
+        out["nano"] = {"note": str(e)}
+    return out
+
+
+def _faucet_info() -> dict:
+    info = RPC().account_info(FAUCET_ADDR) or {}
+    bal = int(info.get("balance", 0))
+    per_claim = int(float(FAUCET_CLAIM_XNO) * 10**30)
+    return {
+        "faucet_address": FAUCET_ADDR,
+        "claim_xno": FAUCET_CLAIM_XNO,
+        "balance_xno": raw_to_xno(bal),
+        "claims_remaining": bal // per_claim if per_claim else 0,
+        "rules": "one claim per address ever; 3 per IP per day; proof-of-work required",
+        "how_to_claim": "pip install feeless402; nano-pay claim https://feeless402.com",
+    }
+
+
+HELP = (
+    "Send me an x402 API URL and I return its live 402 quote plus a per-rail "
+    "cost comparison, without paying. Say 'faucet' for starter-funds info. "
+    "I am read-only and hold no wallet — the self-custodied client is "
+    "pip install feeless402."
+)
+
+
+def _handle_message(message: dict) -> list:
+    """Return A2A parts answering one inbound message."""
+    text = _texts(message)
+    data_parts = [p.get("data") or {} for p in (message.get("parts") or []) if p.get("kind") == "data"]
+    url = next((d["url"] for d in data_parts if isinstance(d, dict) and d.get("url")), None)
+    if not url:
+        m = URL_RE.search(text)
+        url = m.group(0).rstrip(".,;)]") if m else None
+    if url:
+        body = next((json.dumps(d["json_body"]) for d in data_parts
+                     if isinstance(d, dict) and d.get("json_body")), "")
+        method = next((d["method"] for d in data_parts
+                       if isinstance(d, dict) and d.get("method")), "GET")
+        try:
+            result = _quote_and_compare(url, method, body)
+        except ValueError as e:  # SSRF guard / bad URL — refusal is the answer
+            result = {"url": url, "error": str(e)}
+        summary = (
+            f"{result['nano']['amount_xno']} XNO per call on nano:mainnet"
+            if isinstance(result.get("nano"), dict) and result["nano"].get("amount_xno")
+            else result.get("error") or result.get("note") or "see data"
+        )
+        return [
+            {"kind": "data", "data": result},
+            {"kind": "text", "text": f"Quote for {url}: {summary}."},
+        ]
+    if "faucet" in text.lower():
+        info = _faucet_info()
+        return [
+            {"kind": "data", "data": info},
+            {"kind": "text", "text": f"Faucet holds {info['balance_xno']} XNO "
+                                     f"({info['claims_remaining']} claims left)."},
+        ]
+    return [{"kind": "text", "text": HELP}]
+
+
+def _rpc_error(rid, code: int, msg: str, status: int = 200) -> JSONResponse:
+    return JSONResponse({"jsonrpc": "2.0", "id": rid, "error": {"code": code, "message": msg}},
+                        status_code=status)
+
+
+@app.post("/a2a")
+async def a2a_rpc(request: Request):
+    try:
+        req = await request.json()
+    except Exception:
+        return _rpc_error(None, -32700, "parse error", 400)
+    rid = req.get("id")
+    method = req.get("method")
+    if method != "message/send":
+        if method in ("tasks/get", "tasks/cancel", "tasks/resubscribe"):
+            return _rpc_error(rid, -32001, "task not found — this agent replies "
+                                           "instantly with messages and creates no tasks")
+        return _rpc_error(rid, -32601, f"method not supported: {method}")
+    message = (req.get("params") or {}).get("message") or {}
+    try:
+        parts = _handle_message(message)
+    except Exception as e:  # never leak a traceback to the wire
+        return _rpc_error(rid, -32603, f"internal error: {type(e).__name__}")
+    return {
+        "jsonrpc": "2.0",
+        "id": rid,
+        "result": {
+            "kind": "message",
+            "role": "agent",
+            "messageId": str(uuid.uuid4()),
+            "contextId": message.get("contextId") or str(uuid.uuid4()),
+            "parts": parts,
+        },
+    }
+
+
+def main():
+    import uvicorn
+
+    uvicorn.run(app, host="127.0.0.1", port=8404, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

{feeless402-0.2.2 → feeless402-0.2.4}/nano_pay/cli.py

@@ -214,23 +214,47 @@ def _claim_one(base, w):
     """Claim from one faucet, solving its PoW challenge if it has one."""
     import requests as rq
 
-    base = base.rstrip("/")
+    # Accept the site root, the /faucet endpoint itself, or either with a
+    # query string (e.g. ``https://feeless402.com/faucet?ref=skill`` as the
+    # skill docs show) — normalize to the root and carry the query along so
+    # attribution tags survive.
+    from urllib.parse import parse_qsl, urlsplit
+
+    u = urlsplit(base)
+    path = u.path.rstrip("/")
+    if path.endswith("/faucet"):
+        path = path[: -len("/faucet")]
+    base = f"{u.scheme}://{u.netloc}{path}"
+    extra = dict(parse_qsl(u.query))
+    extra.pop("address", None)
     payload = {"address": w.address}
     try:
         ch = rq.get(
             f"{base}/faucet/challenge",
-            params={"address": w.address},
+            params={**extra, "address": w.address},
             timeout=30,
         ).json()
         if ch.get("pow_required"):
             import nanopy
 
+            # Deliberately local: the faucet's challenge is meant to cost the
+            # claimant real CPU, which is what stops a farm claiming in bulk.
+            # It cannot be handed to a work service without giving that away.
+            # It can, however, say so — running silent for minutes on the
+            # first command anyone tries reads as a hang.
+            print("solving the faucet's proof-of-work on this machine — "
+                  "usually 30s to a few minutes. This is what keeps the "
+                  "faucet from being drained; it only happens once.",
+                  file=sys.stderr, flush=True)
+            t0 = time.time()
             payload["work"] = (
                 f"{nanopy.ext.work_generate(bytes.fromhex(ch['root']), int(ch['difficulty'], 16), __import__('os').urandom(128)):016x}"
             )
+            print(f"proof-of-work solved in {time.time() - t0:.0f}s — claiming…",
+                  file=sys.stderr, flush=True)
     except Exception:
         pass  # no challenge endpoint — plain claim
-    r = rq.post(f"{base}/faucet", json=payload, timeout=240)
+    r = rq.post(f"{base}/faucet", params=extra or None, json=payload, timeout=240)
     try:
         return r.status_code, r.json()
     except Exception:
@@ -270,21 +294,64 @@ def cmd_claim(args):
                 if got:
                     break
                 time.sleep(1.5)
-            if got:
-                w.prework(got[-1][0], rpc)   # warm the next block off the hash
             acct = w.synced_account(rpc)
-            out(
-                {
-                    "claimed_from": base,
-                    "result": res,
-                    "received": [
-                        {"hash": h, "amount_xno": raw_to_xno(a)}
-                        for h, a in got
-                    ],
-                    "balance_xno": raw_to_xno(acct.raw_bal),
-                    "attempts": attempts,
-                }
-            )
+            payload = {
+                "claimed_from": base,
+                "result": res,
+                "received": [
+                    {"hash": h, "amount_xno": raw_to_xno(a)}
+                    for h, a in got
+                ],
+                "balance_xno": raw_to_xno(acct.raw_bal),
+                "attempts": attempts,
+            }
+            # Report the grant BEFORE warming the next block. Pre-computing
+            # takes minutes on a modest machine, and doing it first left the
+            # user staring at a blank terminal wondering whether the claim
+            # worked — on the very first command they ever run. Same order
+            # and same guard as send()/pay().
+            if got:
+                print(json.dumps(payload, indent=2, default=str), flush=True)
+                print("claimed — that was the slow part, and it is over. "
+                      "Pre-computing the proof-of-work for your next block "
+                      "now, and again after every transaction, so payments "
+                      "from here are near-instant. Safe to Ctrl-C.",
+                      file=sys.stderr, flush=True)
+                try:
+                    w.prework(got[-1][0], rpc)
+                except Exception:
+                    pass
+                sys.exit(0)
+            out(payload)
+    # An already-claimed address is not a broken faucet: the money was
+    # granted earlier (possibly to a client that gave up before the reply).
+    # Pocket anything still pending and report the balance instead of a
+    # hard error — exit 0 when the wallet is funded, since the agent can
+    # proceed straight to paying.
+    already = [
+        a for a in attempts
+        if a["status"] == 429
+        and "already claimed" in str(a["result"].get("error", ""))
+    ]
+    if already:
+        rpc = RPC()
+        got = w.receive_all(rpc, prework=False)
+        acct = w.synced_account(rpc)
+        bal = raw_to_xno(acct.raw_bal)
+        out(
+            {
+                "status": "already_claimed",
+                "message": f"this address already received its starter XNO — "
+                           f"balance {bal} XNO, nothing more to claim here; "
+                           f"generate a fresh wallet if you need a new grant",
+                "balance_xno": bal,
+                "received_now": [
+                    {"hash": h, "amount_xno": raw_to_xno(a)} for h, a in got
+                ],
+                "attempts": attempts,
+            },
+            code=0 if acct.raw_bal else 1,
+        )
     out({"error": "no faucet granted a claim", "attempts": attempts}, code=1)
 
 

{feeless402-0.2.2 → feeless402-0.2.4}/nano_pay/mcp_remote.py

@@ -24,7 +24,7 @@ from .rpc import RPC
 from .x402 import collect_offers, compare_rails, offer_amount_raw, parse_quote, pick_nano_offer
 
 FAUCET_ADDR = "nano_1hk1cu3773u5r39e75mtqrauzro75j3hwdzyewz8izokzur66semy739w14h"
-FAUCET_CLAIM_XNO = "0.005"
+FAUCET_CLAIM_XNO = "0.0005"
 
 INSTRUCTIONS = """Read-only demo of the Feeless402 rail: price any x402
 (HTTP 402 Payment Required) API across payment rails and see what the
@@ -156,7 +156,7 @@ def faucet_info() -> str:
             "rules": "one claim per address ever; 3 per IP per day; proof-of-work required",
             "how_to_claim": "pip install feeless402; nano-pay claim https://feeless402.com "
             "(or the faucet_claim tool of the LOCAL MCP server: nano-pay mcp)",
-            "donations": f"send XNO to {FAUCET_ADDR} — every 0.005 onboards another agent",
+            "donations": f"send XNO to {FAUCET_ADDR} — every 0.0005 onboards another agent",
         }
     )
 

{feeless402-0.2.2 → feeless402-0.2.4}/nano_pay/rpc.py

@@ -1,7 +1,18 @@
 """Nano node RPC client with public-node failover."""
 
+import os
+
 import requests
 
+# Optional dedicated proof-of-work service, tried before the public nodes.
+# Public nodes serve work in ~5s and many refuse outright, which caps how
+# fast a faucet or merchant can sign blocks. Set:
+#   F402_WORK_URLS  comma-separated work endpoints
+#   F402_WORK_KEY   sent as {"key": ...} and as a Bearer header (services differ)
+WORK_URLS = [u.strip() for u in os.environ.get("F402_WORK_URLS", "").split(",")
+             if u.strip()]
+WORK_KEY = os.environ.get("F402_WORK_KEY", "")
+
 DEFAULT_RPCS = [
     "https://rpc.nano.to",
     "https://node.somenano.com/proxy",
@@ -19,9 +30,11 @@ class RPCError(Exception):
 
 
 class RPC:
-    def __init__(self, urls=None, timeout=20):
+    def __init__(self, urls=None, timeout=20, work_urls=None, work_key=None):
         self.urls = urls or list(DEFAULT_RPCS)
         self.timeout = timeout
+        self.work_urls = work_urls if work_urls is not None else list(WORK_URLS)
+        self.work_key = work_key if work_key is not None else WORK_KEY
 
     def call(self, payload: dict) -> dict:
         last_err = None
@@ -91,18 +104,22 @@ class RPC:
         return res["hash"]
 
     def work_generate(self, root: str, difficulty: str):
-        """Ask nodes for work; many public nodes refuse — return None then."""
-        for url in self.urls:
+        """Ask a work service first, then nodes; many public nodes refuse.
+
+        Returns None if nobody will do it, and the caller falls back to
+        local PoW.
+        """
+        payload = {"action": "work_generate", "hash": root,
+                   "difficulty": difficulty}
+        for url in list(self.work_urls) + list(self.urls):
+            body = dict(payload)
+            headers = {}
+            if url in self.work_urls and self.work_key:
+                body["key"] = self.work_key            # BoomPoW-style
+                headers["Authorization"] = f"Bearer {self.work_key}"
             try:
-                r = requests.post(
-                    url,
-                    json={
-                        "action": "work_generate",
-                        "hash": root,
-                        "difficulty": difficulty,
-                    },
-                    timeout=self.timeout,
-                )
+                r = requests.post(url, json=body, headers=headers,
+                                  timeout=self.timeout)
                 data = r.json()
                 if isinstance(data, dict) and data.get("work"):
                     return data["work"]

{feeless402-0.2.2 → feeless402-0.2.4}/nano_pay/server.py

@@ -32,8 +32,15 @@ DOCS_URL = os.environ.get(
     "F402_DOCS_URL", "https://github.com/feeless402/feeless402"
 )
 PRICE_XNO = os.environ.get("F402_PRICE_XNO", "0.0001")
-FAUCET_XNO = os.environ.get("F402_FAUCET_XNO", "0.005")
+FAUCET_XNO = os.environ.get("F402_FAUCET_XNO", "0.0005")
+FAUCET_TOPUP_XNO = os.environ.get("F402_FAUCET_TOPUP_XNO", "0.0045")
+# Kept as a string for xno_to_raw's Decimal path; parsed separately so the
+# "is it switched on" test can't trip over a str/int comparison.
+FAUCET_TOPUP_ON = float(FAUCET_TOPUP_XNO or 0) > 0
+# When the grant size last changed, so dispensed-history math stays honest.
+FAUCET_RATE_CHANGES = [(0.0, 0.005), (1786021000.0, float(FAUCET_XNO))]
 FAUCET_PER_IP_PER_DAY = int(os.environ.get("F402_FAUCET_PER_IP_PER_DAY", "3"))
+FAUCET_GLOBAL_PER_HOUR = int(os.environ.get("F402_FAUCET_GLOBAL_PER_HOUR", "12"))
 FAUCET_POW = os.environ.get("F402_FAUCET_POW", "0") == "1"
 # Sibling faucets advertised in railHint — the federation list. Comma-sep.
 FAUCET_FEDERATION = [
@@ -90,6 +97,61 @@ def _self_addresses() -> set:
         return set()
 
 
+# Addresses a faucet farm sweeps its grants into. A farm has to collect what it
+# harvests somewhere, and that destination is the one thing it can't fake away
+# without spending more than it earns — so it is the honest way to tell a bot's
+# payment from a person's, after the fact. Add to this list if a new one appears.
+FARM_COLLECTORS = {
+    "nano_3amg1cayw1ynb4fhyzhyc4hpwrehsy1ubtcdgi57bbz7ycjjkzjhpxtdcm6y",
+}
+
+
+def _looks_like_farm(payer: str) -> bool:
+    """Has this payer swept its balance into a known farm collector?
+
+    Runs off the request path — it costs an RPC call and a payment must never
+    wait on bookkeeping.
+    """
+    try:
+        hist = rpc.call({"action": "account_history", "account": payer,
+                         "count": "25"}).get("history", [])
+        return any(b.get("type") == "send"
+                   and b.get("account") in FARM_COLLECTORS for b in hist)
+    except Exception:
+        return False
+
+
+def _reclassify_if_farm(payer: str) -> None:
+    """Move a payment from external to farm once the sweep gives it away.
+
+    The farm pays our 0.0001 fee like anyone else, so at the moment of payment
+    it is indistinguishable from a real user. It gives itself away minutes or
+    hours later, when it sweeps. This re-checks then, so the public numbers
+    settle on the truth instead of flattering us.
+    """
+    def _check():
+        time.sleep(300)                      # give it time to sweep
+        if not _looks_like_farm(payer):
+            return
+        try:
+            d = json.loads(PAID_CALLS.read_text())
+            if payer in (d.get("payers", {}).get("farm") or []):
+                return                        # already counted as farm
+            d["external"] = max(0, int(d.get("external", 0)) - 1)
+            d["farm"] = int(d.get("farm", 0)) + 1
+            d.setdefault("payers", {}).setdefault("farm", []).append(payer)
+            ext = d.get("payers", {}).get("external") or []
+            if payer in ext:
+                ext.remove(payer)
+            tmp = PAID_CALLS.with_name(PAID_CALLS.name + ".tmp")
+            tmp.write_text(json.dumps(d, indent=2))
+            tmp.replace(PAID_CALLS)
+            print(f"reclassified farm payment: {payer[:20]}…", flush=True)
+        except Exception as e:
+            print("reclassify failed:", e, flush=True)
+    threading.Thread(target=_check, daemon=True).start()
+
+
 def _count_paid_call(payer: str, demo_address: str) -> None:
     """Tally a settled payment by who paid. Never raises — a bookkeeping
     failure must not affect a payment that already settled on-chain."""
@@ -115,19 +177,62 @@ def _count_paid_call(payer: str, demo_address: str) -> None:
         pass
 
 
+def _maybe_graduate(payer: str) -> None:
+    """First real x402 payment from a faucet claimant quietly tops their
+    starter grant up to a full allowance. Never raises, never blocks the
+    payment response; the send runs in its own thread under FAUCET_LOCK.
+
+    Deliberately unadvertised on every user-facing surface: the paid call
+    itself is the proof of a real integration.
+
+    ⚠️ Aug 7 2026: SET TO ZERO (disabled). The premise — that paying proves
+    a real integration — held for about sixteen hours. A farm started paying
+    the 0.0001 premium fee to unlock the 0.0045 top-up, a 45x return, and
+    took 11 of 12 grants in a day. Any unlock that costs far less than the
+    prize is just a price, not a proof. Re-enable by setting
+    F402_FAUCET_TOPUP_XNO above zero if the economics ever change.
+    """
+    try:
+        if not FAUCET_TOPUP_ON:
+            return
+        if payer == demo_wallet.address or payer in _self_addresses():
+            return
+        led = _ledger()
+        if payer not in led["addresses"] or payer in led.get("graduated", {}):
+            return
+
+        def _send():
+            try:
+                with FAUCET_LOCK:
+                    led2 = _ledger()
+                    if payer in led2.setdefault("graduated", {}):
+                        return
+                    faucet_wallet.load()
+                    faucet_wallet.receive_all(rpc, prework=False)
+                    faucet_wallet.send(
+                        rpc, payer, xno_to_raw(FAUCET_TOPUP_XNO),
+                        prework=False)
+                    led2["graduated"][payer] = time.time()
+                    _save_ledger(led2)
+            except Exception:
+                pass
+
+        threading.Thread(target=_send, daemon=True).start()
+    except Exception:
+        pass
+
+
 def _faucet_funding() -> dict:
     """Who has put XNO INTO the faucet, read straight off the chain.
 
     Three kinds of deposit: our own top-ups, grants an agent didn't spend
     and sent back, and donations from people who owed us nothing.
     """
-    try:
-        hist = (rpc.call({"action": "account_history",
-                          "account": faucet_wallet.address,
-                          "count": "500"}).get("history") or [])
-    except Exception:
-        return {"donations": None, "donated_xno": None,
-                "returned_grants": None, "recent": [], "address": None}
+    # No try/except: an RPC failure must RAISE so _cached() serves the last
+    # good funding block instead of caching this None-shaped placeholder.
+    hist = (rpc.call({"action": "account_history",
+                      "account": faucet_wallet.address,
+                      "count": "500"}).get("history") or [])
     ours = _self_addresses()
     claimants = set(_ledger().get("addresses", {}))
     donations, returned, donated_raw = [], 0, 0
@@ -159,13 +264,17 @@ def _faucet_funding() -> dict:
 def _paid_calls() -> dict:
     try:
         d = json.loads(PAID_CALLS.read_text())
+        # "external" must mean a person. Farm payments are broken out rather
+        # than folded in — a faucet farm paying our own fee to unlock a grant
+        # is not usage, and counting it as such flatters the numbers 5x.
         return {"external": int(d.get("external", 0)),
+                "farm": int(d.get("farm", 0)),
                 "demo": int(d.get("demo", 0)),
                 "self_test": int(d.get("self", 0)),
                 "last_external_unix": d.get("last_external_unix")}
     except Exception:
-        return {"external": None, "demo": None, "self_test": None,
-                "last_external_unix": None}
+        return {"external": None, "farm": None, "demo": None,
+                "self_test": None, "last_external_unix": None}
 
 
 def _self_ips() -> set:
@@ -206,6 +315,36 @@ def _client_ip(request) -> str:
             or (request.client.host if request.client else "unknown"))
 
 
+# JSON Schema (Draft 2020-12) validating the rail-hint `info` object. Shipped
+# inline with every declaration per the x402 SDK extension convention
+# ({"info": ..., "schema": ...}), so clients can validate without a fetch.
+# Canonical copy: https://railhint.com/railhint.schema.json
+RAILHINT_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://railhint.com/railhint.schema.json",
+    "title": "rail-hint",
+    "description": (
+        "Advisory rail-negotiation extension for x402 v2 402 responses. "
+        "Carried at extensions.\"rail-hint\" as {info, schema}. Non-binding: "
+        "the accepts array remains the only binding payment terms."
+    ),
+    "type": "object",
+    "required": ["cheapest", "why"],
+    "properties": {
+        "cheapest": {"type": "string"},
+        "why": {"type": "string"},
+        "docs": {"type": "string", "format": "uri"},
+        "site": {"type": "string", "format": "uri"},
+        "agentReadme": {"type": "string", "format": "uri"},
+        "bootstrap": {"type": "string"},
+        "topup": {"type": "string"},
+        "faucets": {"type": "array", "items": {"type": "string", "format": "uri"}},
+        "spec": {"type": "string"},
+    },
+    "additionalProperties": True,
+}
+
+
 def rail_hint(price_raw: int) -> dict:
     return {
         "cheapest": "nano:mainnet",
@@ -235,7 +374,7 @@ def rail_hint(price_raw: int) -> dict:
 def payment_required_body(price_raw: int, pay_to: str, resource: str) -> dict:
     return {
         "x402Version": 2,
-        "error": "Payment required — feeless XNO option available (see extensions.railHint)",
+        "error": "Payment required — feeless XNO option available (see extensions[\"rail-hint\"])",
         "resource": {"url": resource, "mimeType": "application/json"},
         "accepts": [
             {
@@ -247,7 +386,17 @@ def payment_required_body(price_raw: int, pay_to: str, resource: str) -> dict:
                 "maxTimeoutSeconds": 60,
             }
         ],
-        "extensions": {"railHint": rail_hint(price_raw)},
+        "extensions": {
+            # Conformant with the x402 SDK extension convention:
+            # kebab-case key, {info, schema} shape.
+            "rail-hint": {
+                "info": rail_hint(price_raw),
+                "schema": RAILHINT_SCHEMA,
+            },
+            # DEPRECATED legacy key (flat shape, draft-railhint-00 as first
+            # published). Kept while integrators migrate; will be removed.
+            "railHint": rail_hint(price_raw),
+        },
     }
 
 
@@ -344,10 +493,11 @@ def _stats_data():
     day_ago = time.time() - 86400
 
     def _bal(w):
-        try:
-            return round(float(raw_to_xno(w.synced_account(rpc).raw_bal)), 6)
-        except Exception:
-            return None
+        # Raises on RPC trouble — deliberately. _cached() turns a raise into
+        # "keep the last good value, retry in fail_ttl"; returning None here
+        # instead would CACHE the None as if it were data, and the page shows
+        # a wall of dashes for the whole TTL (the Aug 15 blank-out).
+        return round(float(raw_to_xno(w.synced_account(rpc).raw_bal)), 6)
 
     faucet_bal = _cached("faucet_bal", 300, lambda: _bal(faucet_wallet))
     per_claim = float(FAUCET_XNO)
@@ -358,7 +508,10 @@ def _stats_data():
             "claims_total": len(ext_times),
             "claims_24h": sum(1 for t in ext_times if t > day_ago),
             "self_test_claims": len(claims) - len(ext_times),
-            "xno_dispensed": round(len(claims) * per_claim, 6),
+            "xno_dispensed": round(sum(
+                next(rate for start, rate in reversed(FAUCET_RATE_CHANGES)
+                     if t >= start)
+                for t in ts_list), 6),
             "xno_per_claim": per_claim,
             "balance_xno": faucet_bal,
             "claims_remaining": (
@@ -448,7 +601,7 @@ STATS_HTML = """<title>Stats — Feeless402</title>
 <main>
   <header>
     <div class="brand"><a href="/"><b>feeless402</b></a> / stats</div>
-    <nav><a href="/">Home</a><a href="/docs.html">Docs</a><a href="/faucet.html">Faucet</a><a href="/stats">Stats</a><a href="https://railhint.com" target="_blank" rel="noopener">Spec</a><a href="/llms.txt">llms.txt</a></nav>
+    <nav><a href="/">Home</a><a href="/docs.html">Docs</a><a href="/faucet.html">Faucet</a><a href="/stats">Stats</a><a href="/briefing/">Briefing</a><a href="/audits/">Audits</a><a href="https://railhint.com" target="_blank" rel="noopener">Spec</a><a href="/llms.txt">llms.txt</a><a href="/.well-known/agent-card.json">A2A</a></nav>
   </header>
 
   <h1>Live usage</h1>
@@ -502,6 +655,7 @@ STATS_HTML = """<title>Stats — Feeless402</title>
   <div class="grid">
     <div class="tile"><div class="num" id="p_ext">&ndash;</div><div class="lbl">paid calls by strangers</div></div>
     <div class="tile"><div class="num" id="p_demo">&ndash;</div><div class="lbl">homepage demo unlocks (we pay those)</div></div>
+    <div class="tile"><div class="num" id="p_farm">&ndash;</div><div class="lbl">faucet-farm payments (excluded from the count above)</div></div>
     <div class="tile"><div class="num" id="t_bal">&ndash;</div><div class="lbl">treasury balance (XNO, incl. our own demo)</div></div>
     <div class="tile"><div class="num" id="t_price">&ndash;</div><div class="lbl">price per call (XNO)</div></div>
   </div>
@@ -534,7 +688,7 @@ async function load(){
       '" target="_blank" rel="noopener noreferrer">'+
       d.from.slice(0,16)+'…'+d.from.slice(-6)+'</a> &mdash; <strong>'+
       d.xno+' XNO</strong> '+when+'</div>';}).join('');
-  var pc=t.paid_calls||{};n2('p_ext',pc.external);n2('p_demo',pc.demo);
+  var pc=t.paid_calls||{};n2('p_ext',pc.external);n2('p_demo',pc.demo);n2('p_farm',pc.farm);
   document.getElementById('t_bal').textContent=(t.balance_xno==null&&t.receivable_xno==null)?'–':xno((t.balance_xno||0)+(t.receivable_xno||0));
   document.getElementById('t_price').textContent=xno(t.price_per_call_xno);
   const gen=new Date((s.generated_unix||Date.now()/1000)*1000);
@@ -580,7 +734,20 @@ def create_app() -> FastAPI:
 
     @app.get("/stats.json")
     def stats_json():
-        return _stats_data()
+        # No caching: the page fetches this client-side, and a browser-cached
+        # copy is how a corrected figure keeps displaying the wrong number.
+        return JSONResponse(_stats_data(), headers={
+            "Cache-Control": "no-store, max-age=0"})
+
+    # Liveness for uptime monitors and integrators (real users probed for
+    # both spellings) — cheap on purpose: no RPC, no wallet, no state writes.
+    start_unix = time.time()
+
+    @app.get("/health")
+    @app.get("/status")
+    def health():
+        return {"ok": True, "service": "feeless402", "version": __version__,
+                "uptime_s": int(time.time() - start_unix)}
 
     @app.get("/stats", response_class=HTMLResponse)
     def stats_page():
@@ -609,6 +776,12 @@ def create_app() -> FastAPI:
             "## Top up for real work\n"
             "nano-pay topup 5 --asset USDC-BASE --execute\n"
             "# $5 of USDC ≈ 100,000+ micro-calls at this endpoint's price\n\n"
+            "## Agent interfaces (read-only, no wallet)\n"
+            f"Daily agent-written x402 briefing + feed: {SITE_URL}/briefing/ "
+            f"(machine-readable: {SITE_URL}/briefing/feed.json)\n"
+            f"MCP (streamable HTTP): {SITE_URL}/mcp\n"
+            f"A2A agent (JSON-RPC): {SITE_URL}/a2a — card at "
+            f"{SITE_URL}/.well-known/agent-card.json\n\n"
             f"Docs: {DOCS_URL}\nSpec: x402 exact scheme, nano:mainnet\n"
             "x402 is stewarded by the Linux Foundation's x402 Foundation "
             "(premier members incl. Coinbase, Cloudflare, Stripe, Google, "
@@ -643,6 +816,8 @@ def create_app() -> FastAPI:
             )
             receipt = settle_block(block, rpc)
             _count_paid_call(payer, demo_wallet.address)
+            _reclassify_if_farm(payer)
+            _maybe_graduate(payer)
         except PaymentInvalid as e:
             return JSONResponse(
                 {"error": f"payment invalid: {e}"}, status_code=402
@@ -875,7 +1050,7 @@ def create_app() -> FastAPI:
             "payer": demo_wallet.address,
             "hash": receipt["hash"],
             "confirmed": bool(receipt.get("confirmed")),
-            "explorer": f"https://nanexplorer.com/nano/block/{receipt['hash']}",
+            "explorer": f"https://blocklattice.io/block/{receipt['hash']}",
             "elapsed_s": elapsed,
             "article": r2.json().get("article"),
             "ledger": ledger,
@@ -994,8 +1169,17 @@ def create_app() -> FastAPI:
         }
 
     @app.get("/faucet")
-    def faucet_info():
+    def faucet_info(request: Request):
         """A human clicking a pasted /faucet link gets a signpost, not a 405."""
+        # Rescue for nano-pay <= 0.2.3 clients given a faucet URL that carries
+        # a query string (SKILL.md's ``claim https://feeless402.com/faucet?ref=skill``):
+        # they naively append "/faucet/challenge" and arrive here as
+        # ``/faucet?ref=skill/faucet/challenge&address=nano_…``. Serve them the
+        # challenge they meant to ask for instead of the signpost.
+        qs = str(request.url.query)
+        addr = request.query_params.get("address", "")
+        if "/faucet/challenge" in qs and addr.startswith("nano_"):
+            return faucet_challenge(addr)
         return {
             "how": "POST JSON {\"address\": \"nano_...\", \"work\": \"...\"} "
                    "— GET /faucet/challenge first for the PoW root",
@@ -1081,6 +1265,35 @@ def create_app() -> FastAPI:
                 headers={"Retry-After": str(max(1, int(frees_at - time.time())))},
             )
 
+        # Global budget: the faucet as a whole serves at most N claims per
+        # rolling hour, regardless of who is asking. Per-IP and per-address
+        # rules rotate away for free against a proxy pool (Aug 6 farm:
+        # 100+ claims/hour from unique IPs, identical UA); this is the one
+        # limit that can't. Counted straight from ledger timestamps, so it
+        # needs no extra state and survives restarts.
+        hour_ago = time.time() - 3600
+        hour_claims = sorted(
+            t for t in led["addresses"].values() if t > hour_ago)
+        if len(hour_claims) >= FAUCET_GLOBAL_PER_HOUR:
+            # Honest Retry-After: the moment the in-window count drops BELOW
+            # the cap — not when the single oldest claim ages out, which
+            # after a burst frees no capacity at all.
+            frees_at = hour_claims[len(hour_claims) - FAUCET_GLOBAL_PER_HOUR] + 3600
+            wait = max(1, int(frees_at - time.time()))
+            return JSONResponse(
+                {"error": "faucet hourly budget used up — try again shortly",
+                 "limit_per_hour_global": FAUCET_GLOBAL_PER_HOUR,
+                 "retry_after_seconds": wait,
+                 "retry_at_utc": time.strftime(
+                     "%Y-%m-%dT%H:%M:%SZ", time.gmtime(frees_at)),
+                 "note": "shared across all users; separately, each address "
+                         "may claim once ever",
+                 "building_something": "if the budget keeps blocking a real "
+                                       f"integration, ask: {DOCS_URL}/issues"},
+                status_code=429,
+                headers={"Retry-After": str(wait)},
+            )
+
         amount = xno_to_raw(FAUCET_XNO)
 
         def _locked_claim():
@@ -1092,6 +1305,16 @@ def create_app() -> FastAPI:
                 led2 = _ledger()
                 if address in led2["addresses"]:
                     return None
+                # Re-check the global budget now that we hold the lock: a
+                # burst can push many requests past the pre-lock check while
+                # earlier sends are still queued here (Aug 6: 5 claims slipped
+                # through a 3/hour cap exactly this way).
+                cutoff = time.time() - 3600
+                inwin = sorted(t for t in led2["addresses"].values()
+                               if t > cutoff)
+                if len(inwin) >= FAUCET_GLOBAL_PER_HOUR:
+                    return ("budget",
+                            inwin[len(inwin) - FAUCET_GLOBAL_PER_HOUR] + 3600)
                 faucet_wallet.load()
                 # pocket any pending refills first
                 faucet_wallet.receive_all(rpc, prework=False)
@@ -1117,6 +1340,17 @@ def create_app() -> FastAPI:
                 {"error": "address already claimed its starter XNO"},
                 status_code=429,
             )
+        if isinstance(h, tuple) and h[0] == "budget":
+            wait = max(1, int(h[1] - time.time()))
+            return JSONResponse(
+                {"error": "faucet hourly budget used up — try again shortly",
+                 "limit_per_hour_global": FAUCET_GLOBAL_PER_HOUR,
+                 "retry_after_seconds": wait,
+                 "note": "shared across all users; separately, each address "
+                         "may claim once ever"},
+                status_code=429,
+                headers={"Retry-After": str(wait)},
+            )
         # Wait briefly for the send to confirm before answering. Clients
         # typically ask for their pending block the moment we reply, and if
         # it hasn't propagated they see "received nothing" and a zero

{feeless402-0.2.2 → feeless402-0.2.4}/nano_pay/wallet.py

@@ -13,6 +13,8 @@ Design notes:
 
 import json
 import os
+import tempfile
+import threading
 from pathlib import Path
 
 import nanopy
@@ -34,6 +36,7 @@ class Wallet:
     def __init__(self, path: Path = None):
         self.path = Path(path) if path else DEFAULT_DIR / "wallet.json"
         self.data = None
+        self._save_lock = threading.Lock()
 
     # ---------- persistence ----------
 
@@ -65,10 +68,26 @@ class Wallet:
         return self
 
     def _save(self):
-        tmp = self.path.with_suffix(".tmp")
-        tmp.write_text(json.dumps(self.data, indent=2))
-        os.chmod(tmp, 0o600)
-        tmp.replace(self.path)
+        # Concurrent saves (send path + work-precompute thread) once interleaved
+        # on a shared .tmp name and promoted a mangled file — lock the whole
+        # write and give each save its own temp file.
+        with self._save_lock:
+            fd, tmp = tempfile.mkstemp(
+                dir=self.path.parent, prefix=self.path.name + ".", suffix=".tmp"
+            )
+            try:
+                with os.fdopen(fd, "w") as f:
+                    f.write(json.dumps(self.data, indent=2))
+                    f.flush()
+                    os.fsync(f.fileno())
+                os.chmod(tmp, 0o600)
+                os.replace(tmp, self.path)
+            except BaseException:
+                try:
+                    os.unlink(tmp)
+                except OSError:
+                    pass
+                raise
 
     # ---------- account / state ----------
 

{feeless402-0.2.2 → feeless402-0.2.4}/nano_pay/x402.py

@@ -263,8 +263,16 @@ def request_with_payment(
         wallet.payment_succeeded(rpc, new_frontier, work_root, prework=prework)
     else:
         wallet.payment_failed(work_root)
-    return r2, receipt or {
+    # What we paid is ours to know regardless of what the merchant echoes
+    # back — merge our ground truth under their receipt fields.
+    base = {
         "amount_xno": raw_to_xno(amount),
         "pay_to": pay_to,
+        "block": new_frontier,
         "settled": 200 <= r2.status_code < 300,
     }
+    if receipt:
+        base.update(receipt)
+        base["amount_xno"] = raw_to_xno(amount)
+        base["block"] = new_frontier
+    return r2, base

{feeless402-0.2.2 → feeless402-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "feeless402"
-version = "0.2.2"
+version = "0.2.4"
 description = "Feeless x402 micropayments for AI agents — self-custodied XNO wallet, pay-per-call client, merchant server with railHint, faucet, and MCP server"
 readme = "README.md"
 license = { text = "MIT" }