k402 0.1.0__py3-none-any.whl

k402/__init__.py

@@ -0,0 +1,32 @@
+# k402 — HTTP 402 payments on Kaspa. See PROTOCOL.md for the wire protocol.
+from .addresses import (AddressProvider, CallbackAddressProvider,
+                        StaticAddressProvider, XpubAddressProvider)
+from .backend import ChainBackend, NodeBackend, PnnBackend
+from .client import Client, Payer, PaymentFailed
+from .schemes import (K402_VERSION, PAYMENT_HEADER, SESSION_HEADER,
+                      FacilitatorFee, ProtocolError, SessionOffer, UtxoOffer,
+                      format_payment_header, parse_offers, parse_payment_header,
+                      payment_required_body)
+from .server import K402, PaymentRequired
+from .store import MemoryStore, PaymentRecord, PaymentStore, SqliteStore
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "K402", "Client", "PaymentRequired", "PaymentFailed",
+    "UtxoOffer", "SessionOffer", "FacilitatorFee", "ProtocolError",
+    "parse_offers", "payment_required_body",
+    "format_payment_header", "parse_payment_header",
+    "PAYMENT_HEADER", "SESSION_HEADER", "K402_VERSION",
+    "PnnBackend", "NodeBackend", "ChainBackend",
+    "AddressProvider", "XpubAddressProvider", "CallbackAddressProvider",
+    "StaticAddressProvider",
+    "PaymentStore", "MemoryStore", "SqliteStore", "PaymentRecord",
+    "Payer",
+]
+
+try:  # optional: requires the kaspa SDK extra
+    from .wallet import HotWallet  # noqa: F401
+    __all__.append("HotWallet")
+except ImportError:
+    pass

k402/addresses.py

@@ -0,0 +1,59 @@
+# Address providers hand the server a fresh pay_to address per payment_id.
+# The recommended provider is watch-only xpub derivation: the web server never
+# holds a private key, so a compromised server can lose at most unswept revenue.
+from __future__ import annotations
+
+import itertools
+import threading
+from typing import Callable, Protocol
+
+
+class AddressProvider(Protocol):
+    def next_address(self, payment_id: str) -> str: ...
+
+
+class CallbackAddressProvider:
+    """Bring your own derivation: fn(payment_id) -> address."""
+
+    def __init__(self, fn: Callable[[str], str]):
+        self._fn = fn
+
+    def next_address(self, payment_id: str) -> str:
+        return self._fn(payment_id)
+
+
+class XpubAddressProvider:
+    """Watch-only HD derivation from an account xpub (kaspa SDK required).
+
+    NOTE: the index counter is in-memory. Across restarts pass start_index
+    higher than any previously issued index (persist it next to your payment
+    store) — reusing an index only risks correlating two payments to one
+    address, not losing funds, but fresh-per-payment is the protocol's intent.
+    """
+
+    def __init__(self, xpub: str, network: str = "mainnet", start_index: int = 0):
+        try:
+            from kaspa import PublicKeyGenerator
+        except ImportError as e:
+            raise ImportError(
+                "XpubAddressProvider needs the kaspa SDK: pip install 'k402[kaspa]'") from e
+        self._gen = PublicKeyGenerator.from_xpub(xpub)
+        self._network = network
+        self._counter = itertools.count(start_index)
+        self._lock = threading.Lock()
+
+    def next_address(self, payment_id: str) -> str:
+        with self._lock:
+            index = next(self._counter)
+        return self._gen.receive_address_as_string(self._network, index)
+
+
+class StaticAddressProvider:
+    """A fixed address for every payment. Dev/demo ONLY: concurrent payments to
+    one address can satisfy each other's verification. Never use in production."""
+
+    def __init__(self, address: str):
+        self._address = address
+
+    def next_address(self, payment_id: str) -> str:
+        return self._address

k402/backend.py

@@ -0,0 +1,92 @@
+# Chain backends answer one question for the verifier: how many sompi has an
+# address received? Fresh-address-per-payment makes that equal to its balance.
+#
+# PnnBackend resolves a public node via the Kaspa Resolver (PNN,
+# https://kaspa.aspectron.org/rpc/pnn.html). PNN is dev/test-grade by its own
+# docs — point production at your own node with NodeBackend(url=...).
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Optional, Protocol
+
+
+class ChainBackend(Protocol):
+    async def address_received_sompi(self, address: str) -> int: ...
+    async def close(self) -> None: ...
+
+
+def _require_kaspa():
+    try:
+        import kaspa
+        return kaspa
+    except ImportError as e:
+        raise ImportError(
+            "chain backends need the kaspa SDK: pip install 'k402[kaspa]'") from e
+
+
+class _RpcBackend:
+    """Shared wRPC client lifecycle for resolver- and url-based backends."""
+
+    def __init__(self, network: str = "mainnet", url: Optional[str] = None):
+        self.network = network
+        self.url = url
+        self._client = None
+        self._lock = asyncio.Lock()
+
+    async def _rpc(self):
+        kaspa = _require_kaspa()
+        async with self._lock:
+            if self._client is None or not self._client.is_connected():
+                if self.url:
+                    self._client = kaspa.RpcClient(url=self.url)
+                else:
+                    self._client = kaspa.RpcClient(
+                        resolver=kaspa.Resolver(), network_id=self.network)
+                await self._client.connect()
+            return self._client
+
+    async def address_received_sompi(self, address: str) -> int:
+        rpc = await self._rpc()
+        resp = await rpc.get_balance_by_address({"address": address})
+        return int(resp["balance"])
+
+    async def utxos(self, address: str) -> list:
+        rpc = await self._rpc()
+        resp = await rpc.get_utxos_by_addresses({"addresses": [address]})
+        return resp["entries"]
+
+    async def submit_transaction(self, pending) -> str:
+        rpc = await self._rpc()
+        return await pending.submit(rpc)
+
+    async def wait_for_payment(self, address: str, amount_sompi: int,
+                               timeout: float = 120.0, poll: float = 1.0) -> bool:
+        """Poll until `address` has received `amount_sompi` (Kaspa confirms ~1s,
+        so polling at 1s is adequate; a utxos-changed subscription can replace
+        this later without changing callers)."""
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if await self.address_received_sompi(address) >= amount_sompi:
+                return True
+            await asyncio.sleep(poll)
+        return False
+
+    async def close(self) -> None:
+        if self._client is not None and self._client.is_connected():
+            await self._client.disconnect()
+        self._client = None
+
+
+class PnnBackend(_RpcBackend):
+    """Public Node Network via the Kaspa Resolver. Dev/test-grade."""
+
+    def __init__(self, network: str = "mainnet"):
+        super().__init__(network=network)
+
+
+class NodeBackend(_RpcBackend):
+    """Your own node's wRPC endpoint (e.g. ws://127.0.0.1:17110). Production."""
+
+    def __init__(self, url: str, network: str = "mainnet"):
+        super().__init__(network=network, url=url)

k402/client.py

@@ -0,0 +1,88 @@
+# Client side of k402: an httpx wrapper that turns HTTP 402 into payment.
+#
+#   client = Client(payer=HotWallet(private_key))       # kaspa-utxo, non-custodial
+#   client = Client(session="s_...")                    # kaspa-session, prepaid
+#   r = await client.post("https://api.example/summarize", json={...})
+from __future__ import annotations
+
+from typing import Optional, Protocol
+
+import httpx
+
+from .schemes import (PAYMENT_HEADER, SESSION_HEADER, ProtocolError,
+                      SessionOffer, UtxoOffer, format_payment_header,
+                      parse_offers)
+
+
+class Payer(Protocol):
+    async def pay(self, offer: UtxoOffer) -> str:
+        """Pay the offer on-chain; return the txid."""
+        ...
+
+
+class PaymentFailed(Exception):
+    """The 402 could not be satisfied. `offers` holds what the server accepts."""
+
+    def __init__(self, message: str, offers: Optional[list] = None):
+        self.offers = offers or []
+        super().__init__(message)
+
+
+class Client:
+    def __init__(self, payer: Optional[Payer] = None, session: Optional[str] = None,
+                 max_kas_per_call: float = 1.0, confirm_retries: int = 5,
+                 http: Optional[httpx.AsyncClient] = None):
+        self.payer = payer
+        self.session = session
+        self.max_sompi_per_call = int(max_kas_per_call * 100_000_000)
+        self.confirm_retries = confirm_retries
+        self.http = http or httpx.AsyncClient(timeout=180)
+
+    async def request(self, method: str, url: str, **kwargs) -> httpx.Response:
+        headers = dict(kwargs.pop("headers", {}) or {})
+        if self.session:
+            headers[SESSION_HEADER] = self.session
+
+        r = await self.http.request(method, url, headers=headers, **kwargs)
+        if r.status_code != 402:
+            return r
+
+        try:
+            offers = parse_offers(r.json())
+        except (ProtocolError, ValueError) as e:
+            raise PaymentFailed(f"server sent 402 but not a k402 body: {e}")
+
+        utxo = next((o for o in offers if isinstance(o, UtxoOffer)), None)
+        if utxo is None or self.payer is None:
+            hint = next((f"open a session at {o.open}" for o in offers
+                         if isinstance(o, SessionOffer)), "no payable offer")
+            raise PaymentFailed(
+                f"payment required and no payer configured ({hint})", offers)
+
+        if utxo.total_sompi > self.max_sompi_per_call:
+            raise PaymentFailed(
+                f"offer wants {utxo.total_sompi} sompi, over the "
+                f"max_kas_per_call guard of {self.max_sompi_per_call}", offers)
+
+        txid = await self.payer.pay(utxo)
+        headers[PAYMENT_HEADER] = format_payment_header(txid, utxo.payment_id)
+
+        # Kaspa accepts in ~1s; retry briefly in case we beat the node to it.
+        import asyncio
+        for attempt in range(self.confirm_retries):
+            r = await self.http.request(method, url, headers=headers, **kwargs)
+            if r.status_code != 402:
+                return r
+            await asyncio.sleep(1.0 + attempt)
+        raise PaymentFailed(
+            f"paid tx {txid} but server still returns 402 after "
+            f"{self.confirm_retries} retries", offers)
+
+    async def get(self, url: str, **kw) -> httpx.Response:
+        return await self.request("GET", url, **kw)
+
+    async def post(self, url: str, **kw) -> httpx.Response:
+        return await self.request("POST", url, **kw)
+
+    async def aclose(self) -> None:
+        await self.http.aclose()

k402/schemes.py

@@ -0,0 +1,151 @@
+# Wire format for the k402 protocol: 402 offer bodies and payment headers.
+# This module is dependency-free and is the normative reference implementation
+# of PROTOCOL.md — keep the two in lockstep.
+from __future__ import annotations
+
+import secrets
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+K402_VERSION = "0.1"
+PAYMENT_HEADER = "X-K402-Payment"
+SESSION_HEADER = "X-Session"
+
+SCHEME_UTXO = "kaspa-utxo"
+SCHEME_SESSION = "kaspa-session"
+
+
+class ProtocolError(ValueError):
+    """Malformed k402 wire data (offer body or payment header)."""
+
+
+def new_payment_id() -> str:
+    return "p_" + secrets.token_hex(8)
+
+
+@dataclass
+class FacilitatorFee:
+    """Optional, transparent service fee quoted inside an offer (never a rail toll)."""
+    sompi: str
+    to: str
+    by: str = ""
+
+    def to_dict(self) -> dict:
+        d = {"sompi": self.sompi, "to": self.to}
+        if self.by:
+            d["by"] = self.by
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "FacilitatorFee":
+        return cls(sompi=str(d["sompi"]), to=d["to"], by=d.get("by", ""))
+
+
+@dataclass
+class UtxoOffer:
+    """kaspa-utxo: non-custodial per-call payment to a fresh address."""
+    network: str
+    amount_sompi: str
+    pay_to: str
+    payment_id: str
+    expires: int
+    description: str = ""
+    finality: int = 1
+    facilitator_fee: Optional[FacilitatorFee] = None
+    scheme: str = field(default=SCHEME_UTXO, init=False)
+
+    def to_dict(self) -> dict:
+        d: dict[str, Any] = {
+            "scheme": self.scheme,
+            "network": self.network,
+            "amount_sompi": str(self.amount_sompi),
+            "pay_to": self.pay_to,
+            "payment_id": self.payment_id,
+            "expires": self.expires,
+        }
+        if self.description:
+            d["description"] = self.description
+        if self.finality != 1:
+            d["finality"] = self.finality
+        if self.facilitator_fee:
+            d["facilitator_fee"] = self.facilitator_fee.to_dict()
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "UtxoOffer":
+        try:
+            amount = str(d["amount_sompi"])
+            int(amount)  # must be an integer string; float KAS never crosses the wire
+            return cls(
+                network=d["network"],
+                amount_sompi=amount,
+                pay_to=d["pay_to"],
+                payment_id=d["payment_id"],
+                expires=int(d["expires"]),
+                description=d.get("description", ""),
+                finality=int(d.get("finality", 1)),
+                facilitator_fee=FacilitatorFee.from_dict(d["facilitator_fee"])
+                if d.get("facilitator_fee") else None,
+            )
+        except (KeyError, TypeError, ValueError) as e:
+            raise ProtocolError(f"invalid kaspa-utxo offer: {e}") from e
+
+    @property
+    def total_sompi(self) -> int:
+        """Amount the payer sends in total, including any facilitator fee output."""
+        total = int(self.amount_sompi)
+        if self.facilitator_fee:
+            total += int(self.facilitator_fee.sompi)
+        return total
+
+
+@dataclass
+class SessionOffer:
+    """kaspa-session: prepaid metered balance (deposit address minted by `open`)."""
+    open: str
+    scheme: str = field(default=SCHEME_SESSION, init=False)
+
+    def to_dict(self) -> dict:
+        return {"scheme": self.scheme, "open": self.open}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "SessionOffer":
+        try:
+            return cls(open=d["open"])
+        except KeyError as e:
+            raise ProtocolError(f"invalid kaspa-session offer: {e}") from e
+
+
+Offer = UtxoOffer | SessionOffer
+
+_SCHEME_TYPES = {SCHEME_UTXO: UtxoOffer, SCHEME_SESSION: SessionOffer}
+
+
+def payment_required_body(offers: list[Offer]) -> dict:
+    """The JSON body of a k402 HTTP 402 response."""
+    return {"k402": K402_VERSION, "accepts": [o.to_dict() for o in offers]}
+
+
+def parse_offers(body: dict) -> list[Offer]:
+    """Parse a 402 body; unknown schemes are skipped (forward compatibility)."""
+    if not isinstance(body, dict) or "k402" not in body:
+        raise ProtocolError("not a k402 402 body (missing 'k402' version key)")
+    offers: list[Offer] = []
+    for entry in body.get("accepts", []):
+        typ = _SCHEME_TYPES.get(entry.get("scheme"))
+        if typ is not None:
+            offers.append(typ.from_dict(entry))
+    return offers
+
+
+def format_payment_header(txid: str, payment_id: str, scheme: str = SCHEME_UTXO) -> str:
+    return f"{scheme} {txid} {payment_id}"
+
+
+def parse_payment_header(value: str) -> tuple[str, str, str]:
+    """-> (scheme, txid, payment_id)"""
+    parts = value.strip().split()
+    if len(parts) != 3:
+        raise ProtocolError(
+            f"malformed {PAYMENT_HEADER} header (want '<scheme> <txid> <payment_id>')")
+    return parts[0], parts[1], parts[2]

k402/server.py

@@ -0,0 +1,128 @@
+# Server side of k402: issue offers, verify payments, gate endpoints.
+#
+#   k402 = K402(address_provider=XpubAddressProvider(xpub),
+#               backend=NodeBackend("ws://127.0.0.1:17110"))  # PnnBackend() for dev
+#   app = FastAPI()
+#   k402.install(app)
+#
+#   @app.post("/summarize")
+#   async def summarize(req: Req, payment=Depends(k402.paid(sompi=1_500_000))):
+#       ...
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+from .addresses import AddressProvider
+from .backend import ChainBackend
+from .schemes import (PAYMENT_HEADER, SCHEME_UTXO, FacilitatorFee, Offer,
+                      ProtocolError, UtxoOffer, new_payment_id,
+                      parse_payment_header, payment_required_body)
+from .store import MemoryStore, PaymentRecord, PaymentStore
+
+
+class PaymentRequired(Exception):
+    """Raised when a request must (re)pay. Carries the 402 body to send."""
+
+    def __init__(self, offers: list[Offer], reason: str = ""):
+        self.body = payment_required_body(offers)
+        if reason:
+            self.body["reason"] = reason
+        super().__init__(reason or "payment required")
+
+
+class K402:
+    def __init__(self, address_provider: AddressProvider, backend: ChainBackend,
+                 store: Optional[PaymentStore] = None, network: str = "mainnet",
+                 quote_ttl: int = 600,
+                 facilitator_fee: Optional[FacilitatorFee] = None,
+                 extra_offers: Optional[list[Offer]] = None):
+        self.address_provider = address_provider
+        self.backend = backend
+        self.store = store or MemoryStore()
+        self.network = network
+        self.quote_ttl = quote_ttl
+        self.facilitator_fee = facilitator_fee
+        self.extra_offers = extra_offers or []  # e.g. a SessionOffer
+
+    # -------------------------------------------------------------- protocol core
+    def create_offer(self, sompi: int, description: str = "") -> UtxoOffer:
+        payment_id = new_payment_id()
+        offer = UtxoOffer(
+            network=self.network,
+            amount_sompi=str(sompi),
+            pay_to=self.address_provider.next_address(payment_id),
+            payment_id=payment_id,
+            expires=int(time.time()) + self.quote_ttl,
+            description=description,
+            facilitator_fee=self.facilitator_fee,
+        )
+        self.store.create(PaymentRecord(
+            payment_id=payment_id, address=offer.pay_to,
+            amount_sompi=sompi, expires=offer.expires))
+        return offer
+
+    def _demand(self, sompi: int, description: str, reason: str = "") -> PaymentRequired:
+        return PaymentRequired(
+            [self.create_offer(sompi, description), *self.extra_offers], reason)
+
+    async def verify(self, header_value: str, sompi: int,
+                     description: str = "") -> PaymentRecord:
+        """Verify an X-K402-Payment header; returns the consumed PaymentRecord.
+        Raises PaymentRequired (with a fresh offer) on any failure."""
+        try:
+            scheme, txid, payment_id = parse_payment_header(header_value)
+        except ProtocolError as e:
+            raise self._demand(sompi, description, str(e))
+        if scheme != SCHEME_UTXO:
+            raise self._demand(sompi, description, f"unsupported scheme '{scheme}'")
+
+        rec = self.store.get(payment_id)
+        if rec is None:
+            raise self._demand(sompi, description, "unknown payment_id")
+        if rec.used:
+            raise self._demand(sompi, description, "payment_id already used")
+        if rec.expired:
+            raise self._demand(sompi, description, "quote expired")
+
+        received = await self.backend.address_received_sompi(rec.address)
+        if received < rec.amount_sompi:
+            raise self._demand(
+                sompi, description,
+                f"address has received {received} of {rec.amount_sompi} sompi "
+                f"(tx {txid} not accepted yet? retry in ~1s)")
+
+        if not self.store.mark_used(payment_id):  # lost the race to a parallel request
+            raise self._demand(sompi, description, "payment_id already used")
+        rec.used = True
+        rec.meta["txid"] = txid
+        return rec
+
+    # -------------------------------------------------------------- FastAPI glue
+    def paid(self, sompi: int, description: str = ""):
+        """FastAPI dependency: `payment = Depends(k402.paid(sompi=...))`."""
+        try:
+            from fastapi import Request
+        except ImportError as e:
+            raise ImportError("k402.paid() needs fastapi: pip install 'k402[server]'") from e
+
+        async def dependency(request) -> PaymentRecord:
+            header = request.headers.get(PAYMENT_HEADER)
+            if not header:
+                raise self._demand(sompi, description)
+            return await self.verify(header, sompi, description)
+
+        # `from __future__ import annotations` stringifies closure annotations,
+        # and FastAPI can't resolve "Request" from a function-local import —
+        # attach the real class so dependency injection sees it.
+        dependency.__annotations__["request"] = Request
+        return dependency
+
+    def install(self, app) -> None:
+        """Register the 402 exception handler so PaymentRequired renders as a
+        protocol-compliant HTTP 402 body (not FastAPI's {'detail': ...})."""
+        from fastapi.responses import JSONResponse
+
+        @app.exception_handler(PaymentRequired)
+        async def _handler(request, exc: PaymentRequired):
+            return JSONResponse(status_code=402, content=exc.body)

k402/store.py

@@ -0,0 +1,101 @@
+# Payment stores persist issued offers and enforce single-use payment_ids.
+# mark_used() must be atomic — it is the replay-protection primitive.
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Optional, Protocol
+
+
+@dataclass
+class PaymentRecord:
+    payment_id: str
+    address: str
+    amount_sompi: int
+    expires: int
+    used: bool = False
+    meta: dict = field(default_factory=dict)
+
+    @property
+    def expired(self) -> bool:
+        return time.time() > self.expires
+
+
+class PaymentStore(Protocol):
+    def create(self, record: PaymentRecord) -> None: ...
+    def get(self, payment_id: str) -> Optional[PaymentRecord]: ...
+    def mark_used(self, payment_id: str) -> bool:
+        """True iff this call transitioned the record from unused to used."""
+        ...
+
+
+class MemoryStore:
+    """Process-local store. Fine for a single-worker dev server."""
+
+    def __init__(self):
+        self._records: dict[str, PaymentRecord] = {}
+        self._lock = threading.Lock()
+
+    def create(self, record: PaymentRecord) -> None:
+        with self._lock:
+            self._records[record.payment_id] = record
+
+    def get(self, payment_id: str) -> Optional[PaymentRecord]:
+        with self._lock:
+            return self._records.get(payment_id)
+
+    def mark_used(self, payment_id: str) -> bool:
+        with self._lock:
+            rec = self._records.get(payment_id)
+            if rec is None or rec.used:
+                return False
+            rec.used = True
+            return True
+
+
+class SqliteStore:
+    """Durable store; safe across restarts and multiple workers on one host."""
+
+    def __init__(self, path: str):
+        self._path = path
+        self._local = threading.local()
+        with self._conn() as c:
+            c.execute("""CREATE TABLE IF NOT EXISTS k402_payments (
+                payment_id TEXT PRIMARY KEY,
+                address TEXT NOT NULL,
+                amount_sompi INTEGER NOT NULL,
+                expires INTEGER NOT NULL,
+                used INTEGER NOT NULL DEFAULT 0,
+                meta TEXT NOT NULL DEFAULT '{}')""")
+
+    def _conn(self) -> sqlite3.Connection:
+        conn = getattr(self._local, "conn", None)
+        if conn is None:
+            conn = sqlite3.connect(self._path, isolation_level=None)
+            conn.execute("PRAGMA journal_mode=WAL")
+            self._local.conn = conn
+        return conn
+
+    def create(self, record: PaymentRecord) -> None:
+        self._conn().execute(
+            "INSERT INTO k402_payments VALUES (?,?,?,?,?,?)",
+            (record.payment_id, record.address, record.amount_sompi,
+             record.expires, int(record.used), json.dumps(record.meta)))
+
+    def get(self, payment_id: str) -> Optional[PaymentRecord]:
+        row = self._conn().execute(
+            "SELECT payment_id, address, amount_sompi, expires, used, meta "
+            "FROM k402_payments WHERE payment_id=?", (payment_id,)).fetchone()
+        if row is None:
+            return None
+        return PaymentRecord(payment_id=row[0], address=row[1], amount_sompi=row[2],
+                             expires=row[3], used=bool(row[4]), meta=json.loads(row[5]))
+
+    def mark_used(self, payment_id: str) -> bool:
+        cur = self._conn().execute(
+            "UPDATE k402_payments SET used=1 WHERE payment_id=? AND used=0",
+            (payment_id,))
+        return cur.rowcount == 1

k402/wallet.py

@@ -0,0 +1,56 @@
+# HotWallet: a minimal single-address payer for the kaspa-utxo scheme.
+# Meant for agent/service wallets holding small working balances — not vaults.
+# Keys stay in-process and are never sent anywhere.
+from __future__ import annotations
+
+from typing import Optional
+
+from .backend import _RpcBackend, NodeBackend, PnnBackend
+from .schemes import UtxoOffer
+
+
+class HotWallet:
+    def __init__(self, private_key_hex: str, network: str = "mainnet",
+                 backend: Optional[_RpcBackend] = None, priority_fee_sompi: int = 0):
+        try:
+            from kaspa import PrivateKey
+        except ImportError as e:
+            raise ImportError("HotWallet needs the kaspa SDK: pip install 'k402[kaspa]'") from e
+        self._key = PrivateKey(private_key_hex)
+        self.network = network
+        self.address = self._key.to_keypair().to_address(network).to_string()
+        self.backend = backend or PnnBackend(network=network)
+        self.priority_fee_sompi = priority_fee_sompi
+
+    async def balance_sompi(self) -> int:
+        return await self.backend.address_received_sompi(self.address)
+
+    async def pay(self, offer: UtxoOffer) -> str:
+        """Payer protocol: pay offer.pay_to (and any facilitator fee), return txid."""
+        from kaspa import PaymentOutput, Address, create_transactions
+
+        if offer.network != self.network:
+            raise ValueError(
+                f"offer is for {offer.network} but this wallet is {self.network}")
+
+        outputs = [PaymentOutput(Address(offer.pay_to), int(offer.amount_sompi))]
+        if offer.facilitator_fee:
+            outputs.append(PaymentOutput(
+                Address(offer.facilitator_fee.to), int(offer.facilitator_fee.sompi)))
+
+        entries = await self.backend.utxos(self.address)
+        if not entries:
+            raise ValueError(f"wallet {self.address} has no UTXOs to spend")
+
+        bundle = create_transactions(
+            network_id=self.network,
+            entries=entries,
+            outputs=outputs,
+            change_address=Address(self.address),
+            priority_fee=self.priority_fee_sompi,
+        )
+        txid = ""
+        for pending in bundle["transactions"]:
+            pending.sign([self._key])
+            txid = await self.backend.submit_transaction(pending)
+        return txid

k402-0.1.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: k402
+Version: 0.1.0
+Summary: k402 — HTTP 402 payments on Kaspa. Protocol library: client, server middleware, and PNN-backed verification. No accounts, no API keys.
+Project-URL: Homepage, https://github.com/Kali123411/k402
+Project-URL: Repository, https://github.com/Kali123411/k402
+Author: Kaspa Lab
+License: MIT
+License-File: LICENSE
+Keywords: agent-payments,http-402,k402,kaspa,micropayments,payments,x402
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: all
+Requires-Dist: fastapi>=0.110; extra == 'all'
+Requires-Dist: kaspa>=2.0; extra == 'all'
+Provides-Extra: kaspa
+Requires-Dist: kaspa>=2.0; extra == 'kaspa'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == 'server'
+Description-Content-Type: text/markdown
+
+# k402
+
+**HTTP 402 payments on Kaspa.** Charge (or pay) KAS per API call — no
+accounts, no API keys, no card rails. Kaspa confirms in ~1 second, so a
+non-custodial payment adds about a second to the first request and nothing
+after that.
+
+The wire protocol is [PROTOCOL.md](PROTOCOL.md) — one 402 body, one header,
+implementable in any language. This package is the Python reference
+implementation: client, FastAPI server middleware, and chain verification.
+
+```
+pip install 'k402[all]'     # client + server + kaspa SDK
+pip install k402            # protocol types + client only (httpx)
+```
+
+## Sell: gate a FastAPI endpoint
+
+```python
+from fastapi import FastAPI, Depends
+from k402 import K402, XpubAddressProvider, PnnBackend, SqliteStore
+
+k402 = K402(
+    address_provider=XpubAddressProvider("kpub..."),   # watch-only: server holds no keys
+    backend=PnnBackend(),          # dev/test: community Public Node Network
+                                   # prod: NodeBackend("ws://your-node:17110")
+    store=SqliteStore("payments.db"),
+)
+
+app = FastAPI()
+k402.install(app)
+
+@app.post("/summarize")
+async def summarize(body: dict, payment=Depends(k402.paid(sompi=1_500_000))):
+    return {"summary": ..., "paid_by_tx": payment.meta["txid"]}
+```
+
+Unpaid calls get a protocol 402 with a fresh payment address; paid calls run.
+Replay, expiry, and double-spend-of-the-quote are handled for you.
+
+## Buy: a client that pays as it goes
+
+```python
+from k402 import Client, HotWallet
+
+client = Client(payer=HotWallet(private_key_hex), max_kas_per_call=0.1)
+r = await client.post("https://api.example.com/summarize", json={"text": ...})
+```
+
+The client hits the endpoint, gets the 402, pays the exact quoted sompi from
+its wallet, retries with proof, and returns the real response. The
+`max_kas_per_call` guard caps what it will ever pay (facilitator fees
+included) without asking you.
+
+No wallet? Services may also offer `kaspa-session` (prepaid balance):
+`Client(session="s_...")`.
+
+## Chain backends
+
+| Backend | Use | Notes |
+|---|---|---|
+| `PnnBackend()` | development, testing | resolves a community [PNN](https://kaspa.aspectron.org/rpc/pnn.html) node via the Kaspa Resolver; dev/test-grade by PNN's own guidance |
+| `NodeBackend("ws://host:17110")` | production | your own node (`kaspad --utxoindex`), wRPC Borsh endpoint |
+
+## Design in one paragraph
+
+Every payment gets a **fresh watch-only address**, so verification is just
+"has this address received N sompi" — answerable by any UTXO-indexed node, no
+tx parsing, no payloads, no custody anywhere. Payment ids are single-use and
+marked atomically (replay protection). The protocol takes **no fee**; services
+built on it (facilitators, hosted checkout) quote theirs as a transparent
+`facilitator_fee` line item. Amounts are integer sompi strings end-to-end.
+
+## Status
+
+v0.1.0 — wire protocol stable enough to build against; API may move.
+MIT license.

k402-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+k402/__init__.py,sha256=eNcWGANcL6KLmgmwAWeLJCPnmahDVA2UYFqJPxXir5U,1413
+k402/addresses.py,sha256=2un7ATthDMtF8JhS4nvgldaSjs9Jd_YgYtvqitxeIBk,2131
+k402/backend.py,sha256=N7lFbR9CK9q_9MfJwXYoTIQ67zEg5nodSPJXJRur56A,3341
+k402/client.py,sha256=DU3ZN0BhqWnKWGk9egUmUiLYQVkqohP0x0Q13L4ugio,3500
+k402/schemes.py,sha256=Sb3iBmf5RuIffmjpAvCdhNTGyGlX3Hi-U0aTNEisYMA,4867
+k402/server.py,sha256=Sbj2KRUAO9ORWFPRtbCbDyjlz1qOd_VNDS8WGSLziw4,5568
+k402/store.py,sha256=5sCtxJMkf90y44Flzltr0EXwj-45ckAvEkvBBtPbn8I,3465
+k402/wallet.py,sha256=a2HJZ3bI63_78eydOQbtYAjTW3tIyBVRj3yBbPiaH2M,2305
+k402-0.1.0.dist-info/METADATA,sha256=DbIKeFSwBELBXx5wqFCNpLbZSbbBXYI5bN2hQKEow7g,3845
+k402-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+k402-0.1.0.dist-info/licenses/LICENSE,sha256=nYGFAzdYK_UkNEE3zlFW5avyV0M25U4BMFjzURV4FlA,1066
+k402-0.1.0.dist-info/RECORD,,

k402-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

k402-0.1.0.dist-info/licenses/LICENSE

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