feeless402 0.2.0__py3-none-any.whl

feeless402-0.2.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: feeless402
+Version: 0.2.0
+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
+Project-URL: Specification, https://railhint.com
+Project-URL: Source, https://github.com/feeless402/feeless402
+Keywords: x402,micropayments,ai-agents,nano,xno,http-402,mcp,railhint
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: nanopy
+Requires-Dist: requests
+Provides-Extra: server
+Requires-Dist: fastapi; extra == "server"
+Requires-Dist: uvicorn[standard]; extra == "server"
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.0; extra == "mcp"
+Provides-Extra: all
+Requires-Dist: fastapi; extra == "all"
+Requires-Dist: uvicorn[standard]; extra == "all"
+Requires-Dist: mcp>=2.0; extra == "all"
+Dynamic: license-file
+
+# nano-pay · Feeless402
+
+Self-custodied Nano (XNO) wallet + x402 payment client **and** merchant
+server, built for AI agents. Client spends; `nano-pay serve` earns — paid
+endpoints, on-ledger verification/settlement (no facilitator), a starter
+faucet, and the `railHint` x402 extension that teaches visiting agents how
+to onboard (see SPEC-railhint.md). Site: site/index.html + site/llms.txt.
+
+**The pitch, in one number:** the same $5 buys 5,000 API calls paid as
+per-call USDC-on-Base x402 payments (merchants floor prices at 0.001 USDC),
+or ~1.8 million calls paid in Nano at the true metered price
+($0.0000027/call observed live at nano-gpt.com). Top up once, micropay
+forever.
+
+## Install
+
+```bash
+pip install -e .          # needs Python 3.10+; pulls nanopy + requests
+nano-pay init             # creates ~/.nano-pay/wallet.json (chmod 600)
+```
+
+## Agent flow
+
+```bash
+nano-pay topup 5                    # quote: $5 USDC-BASE → ~12.3 XNO (NanSwap)
+nano-pay topup 5 --execute          # create order (set NANSWAP_API_KEY)
+#   → send USDC to the returned deposit address; XNO arrives in 30-60s
+nano-pay receive                    # pocket incoming XNO
+nano-pay quote https://nano-gpt.com/api/v1/chat/completions \
+    --json '{"model":"gpt-5-nano","messages":[{"role":"user","content":"hi"}]}'
+nano-pay pay   https://nano-gpt.com/api/v1/chat/completions \
+    --json '{"model":"gpt-5-nano","messages":[{"role":"user","content":"hi"}]}'
+```
+
+`pay` handles the whole x402 handshake: request → parse the 402 quote
+(both the x402nano/`PAYMENT-REQUIRED` v2 dialect and the NanoGPT/`accepts`
+v1 dialect) → price-cap check → sign a send state block locally → retry
+with `PAYMENT-SIGNATURE` + `X-PAYMENT` headers. The server settles the
+block via its facilitator; nothing is broadcast unless the server accepts.
+
+## Design notes
+
+- **Self-custody:** seed never leaves `~/.nano-pay/wallet.json` (0600).
+- **No node required:** public RPC failover (rpc.nano.to, somenano,
+  rainstorm.city, nanoslo); all signing and PoW happen locally (nanopy
+  C extension). RPC `work_generate` is tried first, local PoW is the
+  fallback (~25s), and work for the next block is pre-cached after every
+  transaction so steady-state payments are instant.
+- **Safety rails:** per-payment price cap (`--max-xno`, default 0.05);
+  `quote` command inspects any endpoint's price without paying;
+  balance is always re-synced from the network, never trusted locally.
+- **Top-ups without custody:** `topup` quotes/creates swaps directly with
+  NanSwap's API (1,400+ input assets, ~$0.02 minimum). This tool never
+  holds or routes funds.
+
+## Fork-hazard note (x402 payments)
+
+An x402 payment signs a block the *server* broadcasts. If the server
+errors after receiving the block, it may still settle it late. The wallet
+re-syncs its frontier from the network before every operation, so a late
+settlement is picked up naturally; a competing block signed in the
+meantime simply makes one of the two invalid (funds are never at risk,
+but don't fire concurrent payments from one wallet).
+
+## Status
+
+Beta (v0.2.0). 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.
+
+## Security notes (read before holding real funds)
+
+- **Self-custody**: the seed lives only in `~/.nano-pay/*.json` (0600).
+  No tool or log path ever prints it. Back it up offline.
+- **Working capital only**: this is beta wallet software. Keep a few
+  dollars in it, not your savings.
+- **Spend caps**: `pay` refuses quotes above `--max-xno` (default 0.05).
+  MCP `x402_pay` enforces the same cap parameter.
+- **railHint is advisory**: hints from remote servers are untrusted
+  input. This client never executes remote bootstrap strings; it only
+  acts on structured offers that pass its own checks, and `accepts`
+  always binds, never the hint.
+- **Merchant fork guard**: servers cache accepted frontiers and reject
+  duplicate-frontier blocks; payer balance/frontier/signature are
+  verified against the live ledger before settlement.
+- Not audited. MIT — no warranty.

feeless402-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+feeless402-0.2.0.dist-info/licenses/LICENSE,sha256=4opTpL__CfG6AO7_rWBxer5Xof5dM4fvJ4L_hHsPDUk,1080
+nano_pay/__init__.py,sha256=3Atghf3_9IiHmbdE25ddouhLWj8Ny7XhElntm_2-iPg,367
+nano_pay/cli.py,sha256=7gGuugO8Ilrg4trIAt1QCD1D0HytL0vXImUT4ahPNuk,10269
+nano_pay/mcp_server.py,sha256=4K5KVQqkZN_EZoY9-y_ikgLBrqKsMMmP6thLPVg77fM,5377
+nano_pay/rpc.py,sha256=LyDo_FFNLxvmyotssR7n2hOehKtcFKvnC33-zCp0WSw,3820
+nano_pay/server.py,sha256=BL1vGEzHXZUwC4ZW5fXVsEY1IGdOFtG31oOkLCaPLoM,10845
+nano_pay/topup.py,sha256=nd8X58Qgx3E7YRxy2vHY1jIDPv8EdmnpvxNyWz-uUBc,2653
+nano_pay/verify.py,sha256=JY227KYAVMYPJnejIbUVl9zl9BONnpG5mYyKjQBOuNo,3564
+nano_pay/wallet.py,sha256=_e8nz2_aTmg9qYZtSd3h8RI_gp9VIorENVFXy9FCZ2k,7426
+nano_pay/x402.py,sha256=j4z7DSrLvP6LW9P6FkN8UnmNSihNmNPGn9ut4gdbNYo,8625
+feeless402-0.2.0.dist-info/METADATA,sha256=ZnLsWY4w-8AfndEN5eK0V8obOX1Cs2txewK-HPAC2K0,5590
+feeless402-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+feeless402-0.2.0.dist-info/entry_points.txt,sha256=MgndzNFIsSCptCxjFrRcIqwYnS2dixB36jYBjbESdFk,72
+feeless402-0.2.0.dist-info/top_level.txt,sha256=aHS4ae6qB86LlnQ4kEbRjt59opAOgacx0OH61YjEhnM,9
+feeless402-0.2.0.dist-info/RECORD,,

feeless402-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

feeless402-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+f402 = nano_pay.cli:main
+nano-pay = nano_pay.cli:main

feeless402-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Feeless402 contributors
+
+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.

feeless402-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nano_pay

nano_pay/__init__.py

@@ -0,0 +1,17 @@
+"""nano-pay: self-custodied Nano (XNO) wallet + x402 payment client for AI agents."""
+
+__version__ = "0.1.0"
+
+RAW_PER_XNO = 10**30
+
+
+def xno_to_raw(xno) -> int:
+    from decimal import Decimal
+
+    return int(Decimal(str(xno)) * RAW_PER_XNO)
+
+
+def raw_to_xno(raw: int) -> str:
+    from decimal import Decimal
+
+    return str((Decimal(raw) / RAW_PER_XNO).normalize())

nano_pay/cli.py

@@ -0,0 +1,330 @@
+"""nano-pay CLI — agent-friendly: everything prints compact JSON."""
+
+import argparse
+import json
+import sys
+
+from . import raw_to_xno, xno_to_raw
+from .rpc import RPC
+from .topup import TopupError, create_order, estimate, limits
+from .wallet import Wallet, WalletError
+from .x402 import PriceCapExceeded, X402Error, request_with_payment
+
+DEFAULT_MAX_PAY_XNO = "0.05"  # per-payment safety cap unless overridden
+
+
+def out(obj, code=0):
+    print(json.dumps(obj, indent=2, default=str))
+    sys.exit(code)
+
+
+def cmd_init(args):
+    w = Wallet()
+    if w.exists() and not args.seed:
+        w.load()
+        out({"status": "exists", "address": w.address, "file": str(w.path)})
+    w.create(seed=args.seed)
+    out(
+        {
+            "status": "created",
+            "address": w.address,
+            "file": str(w.path),
+            "note": "fund this address with XNO (see `nano-pay topup`), "
+            "then run `nano-pay receive`",
+        }
+    )
+
+
+def cmd_address(args):
+    out({"address": Wallet().load().address})
+
+
+def cmd_status(args):
+    w = Wallet().load()
+    rpc = RPC()
+    acct = w.synced_account(rpc)
+    pending = rpc.receivable(w.address)
+    out(
+        {
+            "address": w.address,
+            "balance_xno": raw_to_xno(acct.raw_bal),
+            "balance_raw": str(acct.raw_bal),
+            "receivable_count": len(pending),
+            "receivable_xno": raw_to_xno(sum(pending.values())),
+            "opened": acct.frontier != "0" * 64,
+        }
+    )
+
+
+def cmd_receive(args):
+    w = Wallet().load()
+    rpc = RPC()
+    got = w.receive_all(rpc)
+    acct = w.synced_account(rpc)
+    out(
+        {
+            "received": [
+                {"hash": h, "amount_xno": raw_to_xno(a)} for h, a in got
+            ],
+            "balance_xno": raw_to_xno(acct.raw_bal),
+        }
+    )
+
+
+def cmd_send(args):
+    w = Wallet().load()
+    rpc = RPC()
+    h = w.send(rpc, args.to, xno_to_raw(args.amount))
+    out({"status": "sent", "hash": h, "to": args.to, "amount_xno": args.amount})
+
+
+def cmd_prework(args):
+    w = Wallet().load()
+    rpc = RPC()
+    acct = w.synced_account(rpc)
+    root = acct.pk if acct.frontier == "0" * 64 else acct.frontier
+    w.prework(root, rpc)
+    out({"status": "work cached", "root": root})
+
+
+def _do_request(args, dry_run):
+    w = Wallet().load() if not dry_run else (Wallet().load() if Wallet().exists() else None)
+    rpc = RPC()
+    kwargs = {}
+    if args.json:
+        kwargs["json"] = json.loads(args.json)
+    headers = {}
+    for hdr in args.header or []:
+        k, _, v = hdr.partition(":")
+        headers[k.strip()] = v.strip()
+    method = args.method or ("POST" if args.json else "GET")
+    r, info = request_with_payment(
+        method,
+        args.url,
+        w,
+        rpc,
+        max_raw=xno_to_raw(args.max_xno),
+        headers=headers,
+        dry_run=dry_run,
+        **kwargs,
+    )
+    body = r.text
+    try:
+        body = r.json()
+    except Exception:
+        pass
+    out(
+        {
+            "status_code": r.status_code,
+            "paid": (not dry_run) and info is not None,
+            "payment": info,
+            "body": body if not args.body_only else None,
+        }
+        if not args.body_only
+        else body
+    )
+
+
+def cmd_quote(args):
+    args.max_xno = DEFAULT_MAX_PAY_XNO
+    args.body_only = False
+    _do_request(args, dry_run=True)
+
+
+def cmd_pay(args):
+    _do_request(args, dry_run=False)
+
+
+def cmd_topup(args):
+    w = Wallet().load()
+    try:
+        if args.execute:
+            order = create_order(args.asset, args.amount, w.address)
+            out({"status": "order created", "order": order})
+        est = estimate(args.asset, args.amount)
+        lim = limits(args.asset)
+        out(
+            {
+                "from": f"{args.amount} {args.asset.upper()}",
+                "estimated_xno": est,
+                "limits": lim,
+                "receive_address": w.address,
+                "note": "re-run with --execute (needs NANSWAP_API_KEY) to "
+                "create the order, then send the deposit",
+            }
+        )
+    except TopupError as e:
+        out({"error": str(e)}, code=1)
+
+
+def cmd_compare(args):
+    import requests as rq
+
+    from .x402 import compare_rails, parse_quote
+
+    headers = {"x-x402": "true"}
+    for hdr in args.header or []:
+        k, _, v = hdr.partition(":")
+        headers[k.strip()] = v.strip()
+    kwargs = {"json": json.loads(args.json)} if args.json else {}
+    method = args.method or ("POST" if args.json else "GET")
+    r = rq.request(method, args.url, headers=headers, timeout=60, **kwargs)
+    if r.status_code != 402:
+        out({"note": f"endpoint returned {r.status_code}, not 402 — nothing to compare"})
+    rails = compare_rails(parse_quote(r))
+    out({
+        "endpoint": args.url,
+        "rails": rails,
+        "note": "prices quoted live by the server just now — verify, don't trust",
+    })
+
+
+def cmd_serve(args):
+    from .server import serve
+
+    serve(port=args.port, host=args.host)
+
+
+def _claim_one(base, w):
+    """Claim from one faucet, solving its PoW challenge if it has one."""
+    import requests as rq
+
+    base = base.rstrip("/")
+    payload = {"address": w.address}
+    try:
+        ch = rq.get(
+            f"{base}/faucet/challenge",
+            params={"address": w.address},
+            timeout=30,
+        ).json()
+        if ch.get("pow_required"):
+            import nanopy
+
+            payload["work"] = (
+                f"{nanopy.ext.work_generate(bytes.fromhex(ch['root']), int(ch['difficulty'], 16), __import__('os').urandom(128)):016x}"
+            )
+    except Exception:
+        pass  # no challenge endpoint — plain claim
+    r = rq.post(f"{base}/faucet", json=payload, timeout=240)
+    try:
+        return r.status_code, r.json()
+    except Exception:
+        return r.status_code, {"raw": r.text[:300]}
+
+
+def cmd_claim(args):
+    w = Wallet().load()
+    faucets = [args.url] if args.url else []
+    if args.auto:
+        import requests as rq
+
+        for registry in (args.url, "https://feeless402.com"):
+            if not registry:
+                continue
+            try:
+                hint = rq.get(
+                    f"{registry.rstrip('/')}/.well-known/railhint.json",
+                    timeout=20,
+                ).json()
+                faucets += [u for u in hint.get("faucets", []) if u not in faucets]
+            except Exception:
+                pass
+    attempts = []
+    for base in faucets:
+        code, res = _claim_one(base, w)
+        attempts.append({"faucet": base, "status": code, "result": res})
+        if code == 200:
+            rpc = RPC()
+            got = w.receive_all(rpc)
+            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,
+                }
+            )
+    out({"error": "no faucet granted a claim", "attempts": attempts}, code=1)
+
+
+def main():
+    p = argparse.ArgumentParser(
+        prog="nano-pay",
+        description="Self-custodied Nano wallet + x402 payment client for agents",
+    )
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("init", help="create wallet")
+    s.add_argument("--seed", help="import existing 64-hex seed")
+    s.set_defaults(fn=cmd_init)
+
+    s = sub.add_parser("address", help="show wallet address")
+    s.set_defaults(fn=cmd_address)
+
+    s = sub.add_parser("status", help="balance + receivable")
+    s.set_defaults(fn=cmd_status)
+
+    s = sub.add_parser("receive", help="pocket all incoming XNO")
+    s.set_defaults(fn=cmd_receive)
+
+    s = sub.add_parser("send", help="send XNO directly")
+    s.add_argument("to")
+    s.add_argument("amount", help="amount in XNO")
+    s.set_defaults(fn=cmd_send)
+
+    s = sub.add_parser("prework", help="pre-compute PoW for next block")
+    s.set_defaults(fn=cmd_prework)
+
+    for name, fn, hlp in (
+        ("quote", cmd_quote, "show an endpoint's x402 quote WITHOUT paying"),
+        ("pay", cmd_pay, "request URL, auto-paying its Nano x402 quote"),
+        ("compare", cmd_compare, "price the same call on every rail the server offers"),
+    ):
+        s = sub.add_parser(name, help=hlp)
+        s.add_argument("url")
+        s.add_argument("--method")
+        s.add_argument("--json", help="JSON request body")
+        s.add_argument("--header", action="append", help="extra 'K: V' header")
+        s.add_argument("--body-only", action="store_true")
+        if name == "pay":
+            s.add_argument(
+                "--max-xno",
+                default=DEFAULT_MAX_PAY_XNO,
+                help=f"refuse quotes above this (default {DEFAULT_MAX_PAY_XNO})",
+            )
+        s.set_defaults(fn=fn)
+
+    s = sub.add_parser("topup", help="quote/execute small swap into XNO")
+    s.add_argument("amount", type=float, help="amount of source asset")
+    s.add_argument("--asset", default="USDC-BASE", help="source asset w/ network suffix, e.g. USDC-BASE, USDT-SOL (default USDC-BASE)")
+    s.add_argument("--execute", action="store_true")
+    s.set_defaults(fn=cmd_topup)
+
+    s = sub.add_parser("serve", help="run the Feeless402 paid-API + faucet server")
+    s.add_argument("--port", type=int, default=8402)
+    s.add_argument("--host", default="127.0.0.1")
+    s.set_defaults(fn=cmd_serve)
+
+    s = sub.add_parser("mcp", help="run as an MCP server (stdio) for agent frameworks")
+    s.set_defaults(fn=lambda a: __import__("nano_pay.mcp_server", fromlist=["main"]).main())
+
+    s = sub.add_parser("claim", help="claim free starter XNO from a Feeless402 faucet")
+    s.add_argument("url", nargs="?", help="faucet base URL (optional with --auto)")
+    s.add_argument("--auto", action="store_true",
+                   help="cycle the faucet federation list until one grants")
+    s.set_defaults(fn=cmd_claim)
+
+    args = p.parse_args()
+    try:
+        args.fn(args)
+    except (WalletError, X402Error, PriceCapExceeded) as e:
+        out({"error": str(e)}, code=1)
+
+
+if __name__ == "__main__":
+    main()

nano_pay/mcp_server.py

@@ -0,0 +1,167 @@
+"""Feeless402 MCP server — feeless x402 micropayments as agent tools.
+
+Any MCP-speaking agent (Claude, Cursor, OpenClaw bridges, ...) can load
+this and gain the ability to price, pay for, and earn from x402 APIs
+over the feeless rail.
+
+Run:  nano-pay mcp            (stdio transport)
+Config example (Claude Code):
+  claude mcp add feeless402 -- nano-pay mcp
+"""
+
+import json
+
+from mcp.server.mcpserver import MCPServer
+
+from . import raw_to_xno, xno_to_raw
+from .rpc import RPC
+from .wallet import Wallet
+
+INSTRUCTIONS = """Pay for x402-priced HTTP APIs (HTTP 402 Payment Required)
+with feeless, sub-second Nano (XNO) micropayments from a self-custodied
+local wallet.
+
+The economics, verifiable via x402_compare: gas rails floor micro-prices
+(e.g. 0.001 USDC minimum ~ 370x a sub-millicent call); the feeless rail
+quotes the true metered price. Strategy: top up once (or claim free
+starter XNO from a faucet), then micropay per call at marginal cost zero.
+
+Safety: payments are refused above max_xno (default 0.05). The wallet
+seed never leaves the local machine and is never returned by any tool.
+Keep only working capital in this wallet."""
+
+mcp = MCPServer(
+    name="feeless402",
+    instructions=INSTRUCTIONS,
+    website_url="https://feeless402.com",
+)
+
+
+def _rpc():
+    return RPC()
+
+
+@mcp.tool(description="Wallet address, XNO balance, and pending incoming amounts")
+def wallet_status() -> str:
+    w = Wallet().load() if Wallet().exists() else Wallet().create()
+    rpc = _rpc()
+    acct = w.synced_account(rpc)
+    pending = rpc.receivable(w.address)
+    return json.dumps(
+        {
+            "address": w.address,
+            "balance_xno": raw_to_xno(acct.raw_bal),
+            "receivable_xno": raw_to_xno(sum(pending.values())),
+        }
+    )
+
+
+@mcp.tool(
+    description="Fetch an x402 endpoint's payment quote WITHOUT paying. "
+    "Returns price in XNO, destination, and the full offer menu."
+)
+def x402_quote(url: str, method: str = "GET", json_body: str = "") -> str:
+    from .x402 import request_with_payment
+
+    kwargs = {"json": json.loads(json_body)} if json_body else {}
+    if json_body and method == "GET":
+        method = "POST"
+    r, info = request_with_payment(
+        method, url, None, _rpc(), max_raw=0, dry_run=True, **kwargs
+    )
+    if info is None:
+        return json.dumps({"status_code": r.status_code, "note": "not a 402 endpoint"})
+    return json.dumps(
+        {
+            "amount_xno": info["amount_xno"],
+            "pay_to": info["pay_to"],
+            "offer": info["offer"],
+        }
+    )
+
+
+@mcp.tool(
+    description="Price the same API call on EVERY rail the server offers "
+    "(Base/Solana USDC, Lightning, XNO...) from live data — use this to "
+    "verify which rail is cheapest instead of trusting documentation."
+)
+def x402_compare(url: str, method: str = "GET", json_body: str = "") -> str:
+    import requests as rq
+
+    from .x402 import compare_rails, parse_quote
+
+    kwargs = {"json": json.loads(json_body)} if json_body else {}
+    if json_body and method == "GET":
+        method = "POST"
+    r = rq.request(method, url, headers={"x-x402": "true"}, timeout=60, **kwargs)
+    if r.status_code != 402:
+        return json.dumps({"status_code": r.status_code, "note": "not a 402 endpoint"})
+    return json.dumps(compare_rails(parse_quote(r)))
+
+
+@mcp.tool(
+    description="Request a URL and automatically pay its Nano x402 quote "
+    "(feeless, sub-second). Refuses quotes above max_xno. Returns the "
+    "paid response body and the settlement receipt."
+)
+def x402_pay(
+    url: str, method: str = "GET", json_body: str = "", max_xno: str = "0.05"
+) -> str:
+    from .x402 import request_with_payment
+
+    w = Wallet().load()
+    kwargs = {"json": json.loads(json_body)} if json_body else {}
+    if json_body and method == "GET":
+        method = "POST"
+    r, receipt = request_with_payment(
+        method, url, w, _rpc(), max_raw=xno_to_raw(max_xno), **kwargs
+    )
+    try:
+        body = r.json()
+    except Exception:
+        body = r.text[:2000]
+    return json.dumps(
+        {"status_code": r.status_code, "receipt": receipt, "body": body}
+    )
+
+
+@mcp.tool(
+    description="Claim free starter XNO from a Feeless402 faucet (solves "
+    "the faucet's proof-of-work challenge automatically; may take ~1 min "
+    "of CPU). Use when the wallet is empty."
+)
+def faucet_claim(faucet_url: str = "https://feeless402.com") -> str:
+    from .cli import _claim_one
+
+    w = Wallet().load() if Wallet().exists() else Wallet().create()
+    code, res = _claim_one(faucet_url, w)
+    if code == 200:
+        got = w.receive_all(_rpc())
+        res["received_xno"] = raw_to_xno(sum(a for _, a in got))
+    return json.dumps({"status": code, "result": res})
+
+
+@mcp.tool(
+    description="Quote a small swap from another asset (e.g. USDC-BASE, "
+    "USDT-SOL) into XNO for topping up the wallet. Execution requires "
+    "NANSWAP_API_KEY; this tool only quotes."
+)
+def topup_quote(amount: float = 5.0, asset: str = "USDC-BASE") -> str:
+    from .topup import estimate, limits
+
+    w = Wallet().load() if Wallet().exists() else Wallet().create()
+    return json.dumps(
+        {
+            "estimate": estimate(asset, amount),
+            "limits": limits(asset),
+            "receive_address": w.address,
+        }
+    )
+
+
+def main():
+    mcp.run("stdio")
+
+
+if __name__ == "__main__":
+    main()