nyen-sdk 0.1.0__tar.gz

nyen_sdk-0.1.0/LICENSE

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

nyen_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: nyen-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the NYEN /v1 public API — reads, satoshi-safe amounts, NTS token ops, SSE events, HMAC webhooks, and the non-custodial invoice/webhook payment flow.
+Author: NYEN
+License-Expression: MIT
+Project-URL: Homepage, https://docs.nyen.cc/api
+Project-URL: Documentation, https://docs.nyen.cc/api
+Keywords: nyen,nts,blockchain,utxo,wallet,payments
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nyen-sdk (Python)
+
+Official Python SDK for the **NYEN `/v1` public API** — the same versioned edge
+the TypeScript [`@nyen/sdk`](../nyen-sdk) wraps. Reads, satoshi-safe amounts, NTS
+token ops, SSE events, HMAC webhooks, Login-with-NyenID, and a non-custodial
+**invoice/webhook payment flow**. **Zero third-party dependencies** (pure
+stdlib). Signing stays in the user's wallet — this SDK is keyless read + broadcast.
+
+```bash
+pip install nyen-sdk        # or: pip install -e Website/packages/nyen-sdk-py
+```
+
+## Read a balance (5 lines)
+
+```python
+from nyen_sdk import NyenClient
+
+nyen = NyenClient("https://api.nyen.cc/v1", api_key="…")
+info = nyen.address("R…")            # native NYEN + every NTS token, one call
+print(info["native"]["balance"], [f'{t["balance"]} {t["name"]}' for t in info["tokens"]])
+```
+
+Amounts are **satoshi-exact** — never `float()` a balance:
+
+```python
+from nyen_sdk import to_sat, from_sat
+to_sat("1.5")          # "150000000"
+from_sat("150000000")  # "1.50000000"
+nyen.balance("R…")     # int satoshis, exact
+```
+
+## Accept deposits with no node (merchant)
+
+```python
+from nyen_sdk import NyenClient, NyenPayments
+
+pay = NyenPayments(NyenClient("https://api.nyen.cc/v1", api_key="…"))
+
+# 1. create an invoice against YOUR OWN receive address + register a webhook
+inv = pay.create_invoice(address="R…", amount="10",
+                         callback_url="https://shop.example/nyen-hook")
+print(pay.payment_uri(inv))          # nyen:R…?amount=10&req=inv_…  (QR / deep-link)
+
+# 2. in your webhook endpoint (e.g. Flask):
+res = pay.handle_webhook(request.headers, request.get_data(as_text=True))
+if res.outcome == "paid":
+    fulfill_order(res.invoice.metadata)      # HMAC verified, amount checked
+```
+
+`handle_webhook` verifies the Stripe-style HMAC (`x-nyen-signature`), matches the
+confirmed deposit to the open invoice by address, checks the amount, and settles
+it — you never run a node or poll the chain.
+
+## Live-watch (no webhook endpoint)
+
+```python
+for evt in nyen.subscribe(channels=["address:R…"]):
+    if evt["type"] == "address":
+        print("deposit", evt["data"]["value"], evt["data"]["txid"])
+        break
+```
+
+## Verify a webhook signature yourself
+
+```python
+ok = NyenClient.verify_webhook_signature(secret, ts, raw_body, sig_header)
+```
+
+## Surface
+
+`NyenClient`: `health status chain block tx address balance address_utxos
+address_history tokens token holders token_history identity fee_mint fee_estimate
+decode_tx build_tx broadcast rpc verify_message subscribe events_stats
+create_webhook list_webhooks get_webhook delete_webhook verify_webhook_signature`.
+
+`NyenPayments`: `create_invoice payment_uri handle_webhook cancel_invoice
+expire_stale sign_request verify_request` + `parse_payment_uri`.
+
+Errors raise a typed `NyenError` with a **stable** `.code` (`"tx-rejected"`,
+`"forbidden"`, …), `.rpc_code`, `.reason`, `.hint`, `.retryable` — mirroring the
+`/v1` structured-error contract. See the [error index](https://docs.nyen.cc/api/errors).
+
+MIT.

nyen_sdk-0.1.0/README.md

@@ -0,0 +1,83 @@
+# nyen-sdk (Python)
+
+Official Python SDK for the **NYEN `/v1` public API** — the same versioned edge
+the TypeScript [`@nyen/sdk`](../nyen-sdk) wraps. Reads, satoshi-safe amounts, NTS
+token ops, SSE events, HMAC webhooks, Login-with-NyenID, and a non-custodial
+**invoice/webhook payment flow**. **Zero third-party dependencies** (pure
+stdlib). Signing stays in the user's wallet — this SDK is keyless read + broadcast.
+
+```bash
+pip install nyen-sdk        # or: pip install -e Website/packages/nyen-sdk-py
+```
+
+## Read a balance (5 lines)
+
+```python
+from nyen_sdk import NyenClient
+
+nyen = NyenClient("https://api.nyen.cc/v1", api_key="…")
+info = nyen.address("R…")            # native NYEN + every NTS token, one call
+print(info["native"]["balance"], [f'{t["balance"]} {t["name"]}' for t in info["tokens"]])
+```
+
+Amounts are **satoshi-exact** — never `float()` a balance:
+
+```python
+from nyen_sdk import to_sat, from_sat
+to_sat("1.5")          # "150000000"
+from_sat("150000000")  # "1.50000000"
+nyen.balance("R…")     # int satoshis, exact
+```
+
+## Accept deposits with no node (merchant)
+
+```python
+from nyen_sdk import NyenClient, NyenPayments
+
+pay = NyenPayments(NyenClient("https://api.nyen.cc/v1", api_key="…"))
+
+# 1. create an invoice against YOUR OWN receive address + register a webhook
+inv = pay.create_invoice(address="R…", amount="10",
+                         callback_url="https://shop.example/nyen-hook")
+print(pay.payment_uri(inv))          # nyen:R…?amount=10&req=inv_…  (QR / deep-link)
+
+# 2. in your webhook endpoint (e.g. Flask):
+res = pay.handle_webhook(request.headers, request.get_data(as_text=True))
+if res.outcome == "paid":
+    fulfill_order(res.invoice.metadata)      # HMAC verified, amount checked
+```
+
+`handle_webhook` verifies the Stripe-style HMAC (`x-nyen-signature`), matches the
+confirmed deposit to the open invoice by address, checks the amount, and settles
+it — you never run a node or poll the chain.
+
+## Live-watch (no webhook endpoint)
+
+```python
+for evt in nyen.subscribe(channels=["address:R…"]):
+    if evt["type"] == "address":
+        print("deposit", evt["data"]["value"], evt["data"]["txid"])
+        break
+```
+
+## Verify a webhook signature yourself
+
+```python
+ok = NyenClient.verify_webhook_signature(secret, ts, raw_body, sig_header)
+```
+
+## Surface
+
+`NyenClient`: `health status chain block tx address balance address_utxos
+address_history tokens token holders token_history identity fee_mint fee_estimate
+decode_tx build_tx broadcast rpc verify_message subscribe events_stats
+create_webhook list_webhooks get_webhook delete_webhook verify_webhook_signature`.
+
+`NyenPayments`: `create_invoice payment_uri handle_webhook cancel_invoice
+expire_stale sign_request verify_request` + `parse_payment_uri`.
+
+Errors raise a typed `NyenError` with a **stable** `.code` (`"tx-rejected"`,
+`"forbidden"`, …), `.rpc_code`, `.reason`, `.hint`, `.retryable` — mirroring the
+`/v1` structured-error contract. See the [error index](https://docs.nyen.cc/api/errors).
+
+MIT.

nyen_sdk-0.1.0/nyen_sdk/__init__.py

@@ -0,0 +1,47 @@
+"""nyen_sdk — official Python SDK for the NYEN /v1 public API.
+
+Mirrors @nyen/sdk (TypeScript). Read + broadcast over the gateway edge
+(NyenClient), satoshi-safe amounts, NTS token reads, SSE events, HMAC webhooks,
+Login-with-NyenID, and the non-custodial invoice/webhook payment flow
+(NyenPayments). Zero third-party deps — pure stdlib. Signing stays in the user's
+wallet; this SDK is keyless read + broadcast.
+
+Quickstart:
+    from nyen_sdk import NyenClient
+    nyen = NyenClient("https://api.nyen.cc/v1", api_key="…")
+    info = nyen.address("R…")
+    print(info["native"]["balance"], [t["name"] for t in info["tokens"]])
+
+Merchant deposits with no node:
+    from nyen_sdk import NyenClient, NyenPayments
+    pay = NyenPayments(NyenClient("https://api.nyen.cc/v1", api_key="…"))
+    inv = pay.create_invoice(address="R…", amount="10", callback_url="https://shop/hook")
+    print(pay.payment_uri(inv))
+    # in your webhook handler:
+    res = pay.handle_webhook(request.headers, request.get_data(as_text=True))
+    if res.outcome == "paid": fulfill(res.invoice)
+"""
+
+from .amounts import (
+    SATOSHIS_PER_COIN, add_sat, amount, amount_from_sat, cmp_sat, from_sat, to_sat,
+)
+from .client import NyenClient
+from .errors import NYEN_ERROR_CODES, NyenError
+from .events import subscribe_events
+from .payments import (
+    Invoice, InvoiceStore, MemoryInvoiceStore, NyenPayments, WebhookResult,
+    parse_payment_uri,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "NyenClient",
+    "NyenError", "NYEN_ERROR_CODES",
+    "NyenPayments", "Invoice", "InvoiceStore", "MemoryInvoiceStore",
+    "WebhookResult", "parse_payment_uri",
+    "subscribe_events",
+    "to_sat", "from_sat", "amount", "amount_from_sat", "add_sat", "cmp_sat",
+    "SATOSHIS_PER_COIN",
+    "__version__",
+]

nyen_sdk-0.1.0/nyen_sdk/amounts.py

@@ -0,0 +1,69 @@
+"""amounts.py — satoshi-safe amount helpers (RPC_PLAN G9).
+
+NYEN amounts are 8-decimal fixed point. The daemon prints them as decimal
+strings (a float hazard). This SDK NEVER round-trips an amount through a Python
+float: every conversion is integer arithmetic, exactly mirroring server/v1.js
+`toSat` / `balanceFromSat` and the TS SDK's amounts.ts. Use these instead of
+`float()` on any balance/fee you read from the API.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Union
+
+SATOSHIS_PER_COIN = 100_000_000
+
+Number = Union[str, int, float]
+
+_DEC_RE = re.compile(r"^-?\d*(\.\d*)?$")
+_INT_RE = re.compile(r"^-?\d+$")
+
+
+def to_sat(dec: Number) -> str:
+    """Decimal string/number -> satoshi integer string, exact. Mirrors v1.js.
+
+    A number/int is read as DECIMAL COINS (to_sat(1) == '100000000'), matching
+    the TS SDK's number path — not as a raw satoshi count.
+    """
+    s = str(dec if dec is not None else "0").strip()
+    if not _DEC_RE.match(s) or s in ("", "-"):
+        return "0"
+    neg = s.startswith("-")
+    body = s[1:] if neg else s
+    i, _, f = body.partition(".")
+    frac = (f + "00000000")[:8]
+    digits = ((i or "0") + frac).lstrip("0") or "0"
+    return ("-" if neg and digits != "0" else "") + digits
+
+
+def from_sat(sat: Number) -> str:
+    """Satoshi integer -> canonical decimal string (8 places)."""
+    s = str(sat if sat is not None else "0").strip()
+    if not _INT_RE.match(s):
+        return "0.00000000"
+    neg = s.startswith("-")
+    d = (s[1:] if neg else s).rjust(9, "0")
+    return f"{'-' if neg else ''}{d[:-8]}.{d[-8:]}"
+
+
+def amount(dec: Number) -> dict:
+    """{ 'balance', 'balancesat' } from a decimal amount."""
+    return {"balance": str(dec if dec is not None else "0"), "balancesat": to_sat(dec)}
+
+
+def amount_from_sat(sat: Number) -> dict:
+    """{ 'balance', 'balancesat' } from a satoshi integer."""
+    bal = str(sat if sat is not None else "0")
+    return {"balance": from_sat(bal), "balancesat": bal}
+
+
+def add_sat(a: Number, b: Number) -> str:
+    """Add two satoshi amounts -> satoshi integer string, exact."""
+    return str(int(str(a)) + int(str(b)))
+
+
+def cmp_sat(a: Number, b: Number) -> int:
+    """Compare two satoshi amounts: -1 | 0 | 1."""
+    x, y = int(str(a)), int(str(b))
+    return -1 if x < y else (1 if x > y else 0)

nyen_sdk-0.1.0/nyen_sdk/client.py

@@ -0,0 +1,246 @@
+"""client.py — NyenClient: the typed wrapper over the NYEN /v1 public API.
+
+Mirrors the TS SDK's client.ts, for Python exchanges / bots / payment backends.
+One class for every read/write on the gateway edge (server/v1.js):
+    reads    health/status/chain/block/tx/address(+utxos/history)/token(+holders
+             /history)/tokens/fee/id
+    writes   tx decode / tx build (UNSIGNED) / broadcast (signed) / rpc passthrough
+    events   subscribe (SSE) / events_stats / webhooks CRUD + signature verify
+Every call unwraps the { ok, data, meta } envelope and raises a typed NyenError
+on { ok:false }. Amounts stay satoshi-exact (see amounts.py). Signing is NEVER
+done here — keys stay in the user's wallet; this class is keyless read+broadcast.
+
+Zero third-party deps: pure stdlib (urllib, hmac, hashlib, json).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Iterator, List, Optional
+
+from .amounts import amount_from_sat, from_sat, to_sat
+from .errors import NyenError
+from .events import subscribe_events
+
+
+class NyenClient:
+    """Typed client for the NYEN /v1 REST API."""
+
+    def __init__(self, base_url: str, api_key: Optional[str] = None, timeout: float = 15.0):
+        if not base_url:
+            raise NyenError.local("bad-request", "NyenClient needs a base_url (…/v1)")
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+    # ── core request → unwrap envelope → data or raise NyenError ────────────────
+    def _request(
+        self, path: str, method: str = "GET",
+        query: Optional[Dict[str, Any]] = None, body: Optional[Any] = None,
+    ) -> Any:
+        url = self.base_url + path
+        if query:
+            q = {k: v for k, v in query.items() if v is not None}
+            if q:
+                url += "?" + urllib.parse.urlencode(q)
+        headers = {"accept": "application/json"}
+        if self.api_key:
+            headers["x-api-key"] = self.api_key
+        data = None
+        if body is not None:
+            headers["content-type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            resp = urllib.request.urlopen(req, timeout=self.timeout)  # noqa: S310
+            status = resp.getcode()
+            raw = resp.read()
+        except urllib.error.HTTPError as e:
+            status = e.code
+            raw = e.read()
+        except urllib.error.URLError as e:
+            raise NyenError.local("network-error", f"network error: {e.reason}")
+        except TimeoutError:
+            raise NyenError.local("timeout", f"request timed out after {self.timeout}s")
+
+        try:
+            env = json.loads(raw.decode("utf-8"))
+        except Exception:
+            raise NyenError({"code": "internal", "message": f"non-JSON response (HTTP {status})"}, status)
+        if isinstance(env, dict) and env.get("ok") is True:
+            return env.get("data")
+        err = env.get("error") if isinstance(env, dict) else None
+        if isinstance(err, dict):
+            raise NyenError(err, status)
+        raise NyenError({"code": "internal", "message": f"unexpected response (HTTP {status})"}, status)
+
+    # ── satoshi-safe helpers on the instance for ergonomics ────────────────────
+    to_sat = staticmethod(to_sat)
+    from_sat = staticmethod(from_sat)
+    amount_from_sat = staticmethod(amount_from_sat)
+
+    # ── unauthenticated ────────────────────────────────────────────────────────
+    def health(self) -> Dict[str, Any]:
+        """GET /v1/health — no key. Returns {height,synced,peers,version}."""
+        try:
+            return self._request("/health")
+        except NyenError:
+            return {"height": 0, "synced": False, "peers": 0, "version": "v1"}
+
+    def openapi(self) -> Any:
+        return self._request("/openapi.json")
+
+    # ── reads ──────────────────────────────────────────────────────────────────
+    def status(self) -> Dict[str, Any]:
+        return self._request("/status")
+
+    def chain(self) -> Dict[str, Any]:
+        return self._request("/chain")
+
+    def block(self, id_or_height) -> Dict[str, Any]:
+        return self._request(f"/block/{urllib.parse.quote(str(id_or_height), safe='')}")
+
+    def tx(self, txid: str) -> Dict[str, Any]:
+        return self._request(f"/tx/{urllib.parse.quote(txid, safe='')}")
+
+    def address(self, addr: str) -> Dict[str, Any]:
+        return self._request(f"/address/{urllib.parse.quote(addr, safe='')}")
+
+    def balance(self, addr: str) -> int:
+        """The native satoshi balance of an address, as an int (exact)."""
+        info = self.address(addr)
+        return int(info["native"]["balancesat"])
+
+    def address_utxos(self, addr: str) -> Dict[str, Any]:
+        return self._request(f"/address/{urllib.parse.quote(addr, safe='')}/utxos")
+
+    def address_history(self, addr: str, cursor: Optional[str] = None, limit: Optional[int] = None) -> Dict[str, Any]:
+        return self._request(
+            f"/address/{urllib.parse.quote(addr, safe='')}/history",
+            query={"cursor": cursor, "limit": limit},
+        )
+
+    def tokens(self, metadata: bool = False) -> Any:
+        return self._request("/tokens", query={"metadata": "true" if metadata else None})
+
+    def token(self, token_id: str) -> Dict[str, Any]:
+        return self._request(f"/token/{urllib.parse.quote(token_id, safe='')}")
+
+    def holders(self, token_id: str, minbalance=None, start=None, count=None) -> Any:
+        return self._request(
+            f"/token/{urllib.parse.quote(token_id, safe='')}/holders",
+            query={"minbalance": minbalance, "start": start, "count": count},
+        )
+
+    def token_history(self, token_id: str, from_block=None, to_block=None, count=None) -> Any:
+        # R6: served by the read-only `gettokenhistory` daemon RPC (block-walk in
+        # the node) — `count` caps the returned events.
+        return self._request(
+            f"/token/{urllib.parse.quote(token_id, safe='')}/history",
+            query={"from": from_block, "to": to_block, "count": count},
+        )
+
+    def identity(self, name: str) -> Dict[str, Any]:
+        return self._request(f"/id/{urllib.parse.quote(name, safe='')}")
+
+    # ── fees ────────────────────────────────────────────────────────────────────
+    def fee_mint(self, height: Optional[int] = None) -> Dict[str, Any]:
+        return self._request("/fee/mint", query={"height": height})
+
+    def fee_estimate(self, op: str = "send", outputs: int = 1) -> Dict[str, Any]:
+        return self._request("/fee/estimate", query={"op": op, "outputs": outputs})
+
+    # ── tx tooling (keyless build/decode; signed broadcast) ────────────────────
+    def decode_tx(self, hex_str: str) -> Dict[str, Any]:
+        return self._request("/tx/decode", method="POST", body={"hex": hex_str})
+
+    def build_tx(self, inputs: List[dict], outputs: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("/tx/build", method="POST", body={"inputs": inputs, "outputs": outputs})
+
+    def broadcast(self, signed_hex: str) -> str:
+        """POST /v1/tx/broadcast { hex } — submit an ALREADY-SIGNED tx. Returns txid."""
+        return self._request("/tx/broadcast", method="POST", body={"hex": signed_hex})["txid"]
+
+    def rpc(self, method: str, params: Optional[list] = None) -> Any:
+        """POST /v1/rpc — raw JSON-RPC passthrough (allowlisted methods only).
+
+        Returns the RAW daemon result; raises NyenError on a gateway rejection or
+        a daemon error.
+        """
+        url = self.base_url + "/rpc"
+        headers = {"accept": "application/json", "content-type": "application/json"}
+        if self.api_key:
+            headers["x-api-key"] = self.api_key
+        payload = json.dumps({"jsonrpc": "1.0", "id": "nyen-sdk-py", "method": method, "params": params or []}).encode()
+        req = urllib.request.Request(url, data=payload, headers=headers, method="POST")
+        try:
+            resp = urllib.request.urlopen(req, timeout=self.timeout)  # noqa: S310
+            status, raw = resp.getcode(), resp.read()
+        except urllib.error.HTTPError as e:
+            status, raw = e.code, e.read()
+        except urllib.error.URLError as e:
+            raise NyenError.local("network-error", f"network error: {e.reason}")
+        obj = json.loads(raw.decode("utf-8"))
+        if isinstance(obj, dict) and obj.get("ok") is False:  # gateway-level (403) envelope
+            raise NyenError(obj.get("error") or {}, status)
+        if isinstance(obj, dict) and obj.get("error"):
+            e = obj["error"]
+            raise NyenError({"code": "internal", "message": e.get("message"), "rpcCode": e.get("code")}, status)
+        return obj.get("result") if isinstance(obj, dict) else obj
+
+    def verify_message(self, address: str, signature: str, message: str) -> bool:
+        """Verify a Login-with-NyenID signature (D30) via the verifymessage passthrough."""
+        return bool(self.rpc("verifymessage", [address, signature, message]))
+
+    # ── events (SSE) ────────────────────────────────────────────────────────────
+    def subscribe(self, channels: Optional[List[str]] = None, last_event_id: Optional[str] = None) -> Iterator[dict]:
+        """Yield pushed block/tx/address/token events (blocks; run in a thread).
+
+        channels: ["block","tx","address:{a}","token:{id}"]; None = all.
+        """
+        return subscribe_events(self.base_url, self.api_key, channels, last_event_id, self.timeout)
+
+    def events_stats(self) -> Dict[str, Any]:
+        return self._request("/events/stats")
+
+    # ── webhooks ────────────────────────────────────────────────────────────────
+    def create_webhook(
+        self, url: str, events: Optional[List[str]] = None,
+        secret: Optional[str] = None, address: Optional[str] = None, token: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """POST /v1/webhooks — register an HMAC-signed delivery endpoint. The
+        `secret` is returned ONCE; store it to verify each delivery."""
+        body = {"url": url}
+        if events:
+            body["events"] = events
+        if secret:
+            body["secret"] = secret
+        if address:
+            body["address"] = address
+        if token:
+            body["token"] = token
+        return self._request("/webhooks", method="POST", body=body)
+
+    def list_webhooks(self) -> List[dict]:
+        return self._request("/webhooks").get("webhooks", [])
+
+    def get_webhook(self, webhook_id: str) -> Dict[str, Any]:
+        return self._request(f"/webhooks/{urllib.parse.quote(webhook_id, safe='')}")
+
+    def delete_webhook(self, webhook_id: str) -> bool:
+        self._request(f"/webhooks/{urllib.parse.quote(webhook_id, safe='')}", method="DELETE")
+        return True
+
+    @staticmethod
+    def verify_webhook_signature(secret: str, timestamp: str, raw_body: str, signature_header: str) -> bool:
+        """Verify a webhook delivery signature (Stripe-style, matches events.js):
+        x-nyen-signature == "sha256=" + HMAC-SHA256(secret, f"{timestamp}.{raw_body}").
+        Constant-time compare."""
+        mac = hmac.new(secret.encode("utf-8"), f"{timestamp}.{raw_body}".encode("utf-8"), hashlib.sha256).hexdigest()
+        expected = f"sha256={mac}"
+        return hmac.compare_digest(expected, (signature_header or "").strip())

nyen_sdk-0.1.0/nyen_sdk/errors.py

@@ -0,0 +1,65 @@
+"""errors.py — the SDK error type, mirroring server/errors.js (RPC_PLAN G3).
+
+Every /v1 failure arrives as { ok:false, error:{ code, message, rpcCode, reason,
+hint, docs } }. The SDK raises a single typed `NyenError` so callers can branch
+on a STABLE string contract (`err.code == "tx-rejected"`) — never a raw daemon
+integer. Mirrors the TS SDK's errors.ts.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+# The stable /v1 error codes. This set IS the contract (mirror errors.js).
+NYEN_ERROR_CODES = (
+    "bad-request",
+    "unauthorized",
+    "forbidden",
+    "not-found",
+    "invalid-params",
+    "insufficient-funds",
+    "tx-rejected",
+    "tx-error",
+    "rate-limited",
+    "in-warmup",
+    "upstream-timeout",
+    "upstream-unreachable",
+    "internal",
+    # SDK-local codes (never sent by the server):
+    "network-error",
+    "timeout",
+    "aborted",
+)
+
+_RETRYABLE = {
+    "rate-limited", "upstream-timeout", "upstream-unreachable",
+    "in-warmup", "network-error", "timeout",
+}
+
+
+class NyenError(Exception):
+    """One typed error for every /v1 and transport failure."""
+
+    def __init__(self, body: dict, http_status: Optional[int] = None):
+        self.code = body.get("code") or "internal"
+        self.message = body.get("message") or self.code or "nyen error"
+        self.rpc_code = body.get("rpcCode")
+        self.reason = body.get("reason")
+        self.hint = body.get("hint")
+        self.docs = body.get("docs")
+        self.http_status = http_status
+        self.retry_after = body.get("retryAfter")
+        super().__init__(self.message)
+
+    @property
+    def retryable(self) -> bool:
+        """True for errors worth retrying (rate-limit, upstream, warmup, transport)."""
+        return self.code in _RETRYABLE
+
+    @staticmethod
+    def local(code: str, message: str) -> "NyenError":
+        """Build from a wrapped transport/SDK failure (no server envelope)."""
+        return NyenError({"code": code, "message": message})
+
+    def __repr__(self) -> str:
+        return f"NyenError(code={self.code!r}, rpc_code={self.rpc_code!r}, message={self.message!r})"

nyen_sdk-0.1.0/nyen_sdk/events.py

@@ -0,0 +1,86 @@
+"""events.py — SSE subscription to GET /v1/events (RPC_PLAN R3).
+
+Push, not poll. Yields NyenEvent dicts {id, type, data} as the gateway pushes
+them. Pure stdlib (urllib streaming SSE parse). The browser EventSource can't set
+headers, so the /v1 route also accepts the key as ?key= (G32) — this server-side
+client uses the x-api-key header, but passes ?key= too for symmetry.
+
+Usage:
+    for evt in subscribe_events(base_url, api_key, channels=["block", "tx"]):
+        print(evt["type"], evt["data"])
+        # break to stop; the connection closes on generator close.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.parse
+import urllib.request
+from typing import Iterator, List, Optional
+
+
+def subscribe_events(
+    base_url: str,
+    api_key: Optional[str] = None,
+    channels: Optional[List[str]] = None,
+    last_event_id: Optional[str] = None,
+    timeout: Optional[float] = None,
+) -> Iterator[dict]:
+    """Yield pushed SSE events. Blocks; iterate in a thread for concurrency.
+
+    channels: e.g. ["block", "tx", "address:R…", "token:i…"]; None/[] = ALL.
+    """
+    base = base_url.rstrip("/")
+    q = {}
+    if channels:
+        q["channels"] = ",".join(channels)
+    if api_key:
+        q["key"] = api_key  # G32: query-key path (EventSource parity)
+    url = base + "/events" + ("?" + urllib.parse.urlencode(q) if q else "")
+    headers = {"accept": "text/event-stream"}
+    if api_key:
+        headers["x-api-key"] = api_key
+    if last_event_id:
+        headers["Last-Event-ID"] = last_event_id
+
+    req = urllib.request.Request(url, headers=headers)
+    resp = urllib.request.urlopen(req, timeout=timeout)  # noqa: S310 (trusted base)
+    try:
+        event_type = None
+        data_lines: List[str] = []
+        eid = None
+        for raw in resp:
+            line = raw.decode("utf-8", "replace").rstrip("\n").rstrip("\r")
+            if line == "":
+                # dispatch on a blank line
+                if data_lines:
+                    payload = "\n".join(data_lines)
+                    parsed = _parse_data(payload)
+                    yield {"id": eid, "type": event_type or "message", "data": parsed}
+                event_type, data_lines, eid = None, [], eid
+                continue
+            if line.startswith(":"):
+                continue  # comment / heartbeat
+            field, _, value = line.partition(":")
+            if value.startswith(" "):
+                value = value[1:]
+            if field == "event":
+                event_type = value
+            elif field == "data":
+                data_lines.append(value)
+            elif field == "id":
+                eid = value
+    finally:
+        try:
+            resp.close()
+        except Exception:
+            pass
+
+
+def _parse_data(payload: str):
+    try:
+        obj = json.loads(payload)
+        # server frames "data:" as the event's `data` field JSON directly
+        return obj
+    except Exception:
+        return payload

nyen_sdk-0.1.0/nyen_sdk/payments.py

@@ -0,0 +1,291 @@
+"""payments.py — NyenPayments: non-custodial invoice + webhook deposit flow
+(RPC_PLAN §8 payments, Phase R5). Mirrors the TS SDK's payments.ts.
+
+A merchant integrates NYEN deposits with NO node of their own:
+    1. create_invoice(address=…, amount=…)  — merchant supplies their OWN receive
+       address (keys stay in the merchant's wallet). Optionally registers a scoped
+       `deposit.confirmed` webhook on that address.
+    2. show payment_uri(inv) as a QR / nyen: link.
+    3. on each webhook POST -> handle_webhook(headers, raw_body) verifies the HMAC,
+       matches the deposit to an open invoice by address, checks the amount, and
+       marks it paid.
+Rides the existing /v1 edge (create_webhook + deposit.confirmed/token.transfer +
+verify_webhook_signature). No node, no key at the edge. Amounts satoshi-exact.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import secrets
+import time
+import urllib.parse
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+from .amounts import amount_from_sat, cmp_sat, from_sat, to_sat
+from .client import NyenClient
+from .errors import NyenError
+
+
+@dataclass
+class Invoice:
+    id: str
+    address: str
+    currency: str
+    amount: str
+    amountsat: str
+    status: str  # pending | underpaid | paid | expired | canceled
+    created_at: int
+    expires_at: Optional[int]
+    memo: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+    paid_at: Optional[int] = None
+    paid_amountsat: Optional[str] = None
+    txid: Optional[str] = None
+    webhook_id: Optional[str] = None
+
+
+class InvoiceStore:
+    """Pluggable persistence. Default is in-memory; a real merchant swaps a DB."""
+
+    def put(self, inv: Invoice) -> None: raise NotImplementedError
+    def get(self, invoice_id: str) -> Optional[Invoice]: raise NotImplementedError
+    def by_address(self, address: str) -> Optional[Invoice]: raise NotImplementedError
+    def list(self) -> List[Invoice]: raise NotImplementedError
+
+
+class MemoryInvoiceStore(InvoiceStore):
+    def __init__(self):
+        self._by_id: Dict[str, Invoice] = {}
+
+    def put(self, inv: Invoice) -> None:
+        self._by_id[inv.id] = inv
+
+    def get(self, invoice_id: str) -> Optional[Invoice]:
+        return self._by_id.get(invoice_id)
+
+    def by_address(self, address: str) -> Optional[Invoice]:
+        for inv in self._by_id.values():
+            if inv.address == address and inv.status in ("pending", "underpaid"):
+                return inv
+        return None
+
+    def list(self) -> List[Invoice]:
+        return list(self._by_id.values())
+
+
+@dataclass
+class WebhookResult:
+    verified: bool
+    event: Optional[str]
+    invoice: Optional[Invoice]
+    outcome: str  # paid | underpaid | already-paid | no-match | ignored | bad-signature
+    data: Optional[Dict[str, Any]]
+
+
+def _now() -> int:
+    return int(time.time())
+
+
+class NyenPayments:
+    """The merchant-side payment processor. Owns no keys, needs no node."""
+
+    def __init__(
+        self, client: NyenClient, store: Optional[InvoiceStore] = None,
+        on_paid: Optional[Callable[[Invoice], None]] = None,
+        on_underpaid: Optional[Callable[[Invoice], None]] = None,
+    ):
+        if client is None:
+            raise NyenError.local("bad-request", "NyenPayments needs a NyenClient")
+        self.client = client
+        self.store = store or MemoryInvoiceStore()
+        self.on_paid = on_paid
+        self.on_underpaid = on_underpaid
+        self._secrets: Dict[str, str] = {}
+
+    def create_invoice(
+        self, address: str, amount=None, amountsat=None, currency: str = "NYEN",
+        memo: Optional[str] = None, metadata: Optional[dict] = None,
+        expires_in_sec: Optional[int] = 3600,
+        callback_url: Optional[str] = None, webhook_secret: Optional[str] = None,
+    ) -> Invoice:
+        if not address:
+            raise NyenError.local("bad-request", "create_invoice needs a receive address")
+        sat = str(int(str(amountsat))) if amountsat is not None else (to_sat(amount) if amount is not None else "0")
+        if cmp_sat(sat, "0") <= 0:
+            raise NyenError.local("bad-request", "create_invoice needs a positive amount")
+        created = _now()
+        inv = Invoice(
+            id="inv_" + secrets.token_hex(12),
+            address=address,
+            currency=currency,
+            amount=from_sat(sat),
+            amountsat=sat,
+            status="pending",
+            created_at=created,
+            expires_at=(created + expires_in_sec) if expires_in_sec else None,
+            memo=memo,
+            metadata=metadata,
+        )
+        if callback_url:
+            is_token = currency != "NYEN"
+            wh = self.client.create_webhook(
+                url=callback_url,
+                events=["token.transfer" if is_token else "deposit.confirmed"],
+                secret=webhook_secret,
+                address=None if is_token else address,
+                token=currency if is_token else None,
+            )
+            inv.webhook_id = wh["id"]
+            self._secrets[inv.id] = wh["secret"]
+        self.store.put(inv)
+        return inv
+
+    def payment_uri(self, inv: Invoice) -> str:
+        """A BIP21-style payment URI for a QR / deep-link."""
+        q: Dict[str, str] = {}
+        if cmp_sat(inv.amountsat, "0") > 0:
+            q["amount"] = inv.amount
+        if inv.memo:
+            q["label"] = inv.memo
+        if inv.currency and inv.currency != "NYEN":
+            q["currency"] = inv.currency
+        q["req"] = inv.id
+        qs = urllib.parse.urlencode(q)
+        return f"nyen:{inv.address}" + (f"?{qs}" if qs else "")
+
+    def bind_secret(self, invoice_id: str, secret: str) -> None:
+        """Record the webhook secret for an invoice created out-of-band."""
+        self._secrets[invoice_id] = secret
+
+    def handle_webhook(
+        self, headers: Dict[str, str], raw_body: str, secret: Optional[str] = None,
+    ) -> WebhookResult:
+        """Feed one webhook POST here. Verifies HMAC, matches an OPEN invoice by
+        address, checks the amount, settles it, and fires on_paid/on_underpaid."""
+        def h(name: str) -> str:
+            for k, v in headers.items():
+                if k.lower() == name.lower():
+                    return v if isinstance(v, str) else (v[0] if v else "")
+            return ""
+
+        ts = h("x-nyen-timestamp")
+        sig = h("x-nyen-signature")
+        event_hdr = h("x-nyen-event") or None
+        try:
+            body = json.loads(raw_body)
+        except Exception:
+            return WebhookResult(False, event_hdr, None, "bad-signature", None)
+        event = body.get("event") or event_hdr
+        data = body.get("data") or None
+
+        address = ""
+        if data:
+            address = str(data.get("address") or (data.get("addresses") or [""])[0] or "")
+        invoice = self.store.by_address(address) if address else None
+
+        use_secret = (self._secrets.get(invoice.id) if invoice else None) or secret
+        if not use_secret:
+            return WebhookResult(False, event, invoice, "bad-signature", data)
+        if not NyenClient.verify_webhook_signature(use_secret, ts, raw_body, sig):
+            return WebhookResult(False, event, invoice, "bad-signature", data)
+
+        if event not in ("deposit.confirmed", "token.transfer"):
+            return WebhookResult(True, event, invoice, "ignored", data)
+        if not invoice:
+            return WebhookResult(True, event, None, "no-match", data)
+        if invoice.status == "paid":
+            return WebhookResult(True, event, invoice, "already-paid", data)
+
+        raw_amt = data.get("amount") if event == "token.transfer" else data.get("value")
+        paidsat = to_sat(raw_amt) if raw_amt is not None else "0"
+        invoice.paid_amountsat = paidsat
+        invoice.txid = data.get("txid") or invoice.txid
+        settled = amount_from_sat(paidsat)
+        if cmp_sat(paidsat, invoice.amountsat) >= 0:
+            invoice.status = "paid"
+            invoice.paid_at = _now()
+            self.store.put(invoice)
+            if self.on_paid:
+                self.on_paid(invoice)
+            return WebhookResult(True, event, invoice, "paid", {**(data or {}), "settled": settled})
+        invoice.status = "underpaid"
+        self.store.put(invoice)
+        if self.on_underpaid:
+            self.on_underpaid(invoice)
+        return WebhookResult(True, event, invoice, "underpaid", {**(data or {}), "settled": settled})
+
+    def cancel_invoice(self, invoice_id: str) -> Optional[Invoice]:
+        inv = self.store.get(invoice_id)
+        if not inv:
+            return None
+        if inv.status in ("pending", "underpaid"):
+            inv.status = "canceled"
+        if inv.webhook_id:
+            try:
+                self.client.delete_webhook(inv.webhook_id)
+            except Exception:
+                pass
+        self.store.put(inv)
+        return inv
+
+    def expire_stale(self) -> List[Invoice]:
+        t = _now()
+        changed: List[Invoice] = []
+        for inv in self.store.list():
+            if inv.status in ("pending", "underpaid") and inv.expires_at and t > inv.expires_at:
+                inv.status = "expired"
+                if inv.webhook_id:
+                    try:
+                        self.client.delete_webhook(inv.webhook_id)
+                    except Exception:
+                        pass
+                self.store.put(inv)
+                changed.append(inv)
+        return changed
+
+    # ── Signed payment request (app-layer HMAC) ────────────────────────────────
+    #  The merchant SIGNS the request so the payer's wallet can trust the
+    #  address+amount weren't tampered with. Pragmatic no-daemon-change version
+    #  (shared secret). RECOMMENDED R6 upgrade: sign with a NyenID identity so any
+    #  wallet verifies against the chain (verifymessage), no pre-shared secret.
+    @staticmethod
+    def _canonical(inv: Invoice) -> str:
+        return json.dumps({
+            "address": inv.address,
+            "amountsat": inv.amountsat,
+            "currency": inv.currency,
+            "memo": inv.memo or "",
+            "expiresAt": inv.expires_at,
+            "id": inv.id,
+        }, separators=(",", ":"), sort_keys=False)
+
+    @staticmethod
+    def sign_request(secret: str, inv: Invoice) -> str:
+        return hmac.new(secret.encode(), NyenPayments._canonical(inv).encode(), hashlib.sha256).hexdigest()
+
+    @staticmethod
+    def verify_request(secret: str, inv: Invoice, signature_hex: str) -> bool:
+        expected = NyenPayments.sign_request(secret, inv)
+        return hmac.compare_digest(expected, (signature_hex or "").strip().lower())
+
+
+def parse_payment_uri(uri: str) -> Optional[dict]:
+    """Parse a `nyen:<addr>?amount=&label=&currency=&req=` URI (payer side)."""
+    s = (uri or "").strip()
+    if not s.lower().startswith("nyen:"):
+        return None
+    rest = s[5:]
+    addr, _, qs = rest.partition("?")
+    q = urllib.parse.parse_qs(qs)
+    amount = q.get("amount", [None])[0]
+    return {
+        "address": urllib.parse.unquote(addr),
+        "amount": amount,
+        "amountsat": to_sat(amount) if amount is not None else None,
+        "memo": q.get("label", q.get("message", [None]))[0],
+        "currency": q.get("currency", ["NYEN"])[0],
+        "req": q.get("req", [None])[0],
+    }

nyen_sdk-0.1.0/nyen_sdk.egg-info/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: nyen-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the NYEN /v1 public API — reads, satoshi-safe amounts, NTS token ops, SSE events, HMAC webhooks, and the non-custodial invoice/webhook payment flow.
+Author: NYEN
+License-Expression: MIT
+Project-URL: Homepage, https://docs.nyen.cc/api
+Project-URL: Documentation, https://docs.nyen.cc/api
+Keywords: nyen,nts,blockchain,utxo,wallet,payments
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nyen-sdk (Python)
+
+Official Python SDK for the **NYEN `/v1` public API** — the same versioned edge
+the TypeScript [`@nyen/sdk`](../nyen-sdk) wraps. Reads, satoshi-safe amounts, NTS
+token ops, SSE events, HMAC webhooks, Login-with-NyenID, and a non-custodial
+**invoice/webhook payment flow**. **Zero third-party dependencies** (pure
+stdlib). Signing stays in the user's wallet — this SDK is keyless read + broadcast.
+
+```bash
+pip install nyen-sdk        # or: pip install -e Website/packages/nyen-sdk-py
+```
+
+## Read a balance (5 lines)
+
+```python
+from nyen_sdk import NyenClient
+
+nyen = NyenClient("https://api.nyen.cc/v1", api_key="…")
+info = nyen.address("R…")            # native NYEN + every NTS token, one call
+print(info["native"]["balance"], [f'{t["balance"]} {t["name"]}' for t in info["tokens"]])
+```
+
+Amounts are **satoshi-exact** — never `float()` a balance:
+
+```python
+from nyen_sdk import to_sat, from_sat
+to_sat("1.5")          # "150000000"
+from_sat("150000000")  # "1.50000000"
+nyen.balance("R…")     # int satoshis, exact
+```
+
+## Accept deposits with no node (merchant)
+
+```python
+from nyen_sdk import NyenClient, NyenPayments
+
+pay = NyenPayments(NyenClient("https://api.nyen.cc/v1", api_key="…"))
+
+# 1. create an invoice against YOUR OWN receive address + register a webhook
+inv = pay.create_invoice(address="R…", amount="10",
+                         callback_url="https://shop.example/nyen-hook")
+print(pay.payment_uri(inv))          # nyen:R…?amount=10&req=inv_…  (QR / deep-link)
+
+# 2. in your webhook endpoint (e.g. Flask):
+res = pay.handle_webhook(request.headers, request.get_data(as_text=True))
+if res.outcome == "paid":
+    fulfill_order(res.invoice.metadata)      # HMAC verified, amount checked
+```
+
+`handle_webhook` verifies the Stripe-style HMAC (`x-nyen-signature`), matches the
+confirmed deposit to the open invoice by address, checks the amount, and settles
+it — you never run a node or poll the chain.
+
+## Live-watch (no webhook endpoint)
+
+```python
+for evt in nyen.subscribe(channels=["address:R…"]):
+    if evt["type"] == "address":
+        print("deposit", evt["data"]["value"], evt["data"]["txid"])
+        break
+```
+
+## Verify a webhook signature yourself
+
+```python
+ok = NyenClient.verify_webhook_signature(secret, ts, raw_body, sig_header)
+```
+
+## Surface
+
+`NyenClient`: `health status chain block tx address balance address_utxos
+address_history tokens token holders token_history identity fee_mint fee_estimate
+decode_tx build_tx broadcast rpc verify_message subscribe events_stats
+create_webhook list_webhooks get_webhook delete_webhook verify_webhook_signature`.
+
+`NyenPayments`: `create_invoice payment_uri handle_webhook cancel_invoice
+expire_stale sign_request verify_request` + `parse_payment_uri`.
+
+Errors raise a typed `NyenError` with a **stable** `.code` (`"tx-rejected"`,
+`"forbidden"`, …), `.rpc_code`, `.reason`, `.hint`, `.retryable` — mirroring the
+`/v1` structured-error contract. See the [error index](https://docs.nyen.cc/api/errors).
+
+MIT.

nyen_sdk-0.1.0/nyen_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+nyen_sdk/__init__.py
+nyen_sdk/amounts.py
+nyen_sdk/client.py
+nyen_sdk/errors.py
+nyen_sdk/events.py
+nyen_sdk/payments.py
+nyen_sdk.egg-info/PKG-INFO
+nyen_sdk.egg-info/SOURCES.txt
+nyen_sdk.egg-info/dependency_links.txt
+nyen_sdk.egg-info/top_level.txt

nyen_sdk-0.1.0/nyen_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nyen_sdk-0.1.0/nyen_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+nyen_sdk

nyen_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nyen-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the NYEN /v1 public API — reads, satoshi-safe amounts, NTS token ops, SSE events, HMAC webhooks, and the non-custodial invoice/webhook payment flow."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "NYEN" }]
+keywords = ["nyen", "nts", "blockchain", "utxo", "wallet", "payments"]
+dependencies = []  # zero third-party deps — pure stdlib
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Office/Business :: Financial",
+]
+
+[project.urls]
+Homepage = "https://docs.nyen.cc/api"
+Documentation = "https://docs.nyen.cc/api"
+
+[tool.setuptools]
+packages = ["nyen_sdk"]

nyen_sdk-0.1.0/setup.cfg

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