hashlock-sdk 0.4.0__tar.gz

hashlock_sdk-0.4.0/.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+*.tsbuildinfo
+__pycache__/
+*.egg-info/
+build/
+.venv/
+.env
+.DS_Store

hashlock_sdk-0.4.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: hashlock-sdk
+Version: 0.4.0
+Summary: Python SDK for the Hashlock Markets developer API — non-custodial cross-chain atomic swaps (BTC <-> EVM/TRON) over sealed RFQ + HTLC.
+Project-URL: Homepage, https://github.com/Hashlock-Tech/hashlock-sdk
+License: MIT
+Keywords: atomic-swap,bitcoin,cross-chain,defi,hashlock,htlc,otc
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: ws
+Requires-Dist: websockets>=12; extra == 'ws'
+Description-Content-Type: text/markdown
+
+# hashlock-sdk (Python)
+
+Python SDK for the [Hashlock Markets](https://github.com/Hashlock-Tech/hashlock-sdk) developer API —
+non-custodial cross-chain atomic swaps (BTC ↔ EVM/TRON). Python 3.9+, built on `httpx`.
+
+> ⚠️ **Sandbox / testnet preview (0.x)** — defaults to `api-dev.hashlock.markets`, testnets only,
+> pre-mainnet. The API may change before the stable `1.0`. Not for mainnet funds.
+
+```bash
+pip install hashlock-sdk          # add [ws] for the maker WebSocket feed: hashlock-sdk[ws]
+```
+
+```python
+from hashlock import HashlockClient, new_secret, verify_webhook
+
+client = HashlockClient(api_key=os.environ["HASHLOCK_API_KEY"])
+client.me()
+
+# cursor pagination — page or auto-iterate
+page = client.list_swaps(limit=20)
+for swap in client.swaps():
+    ...
+
+# initiator: secret stays private; submit only the hashlock
+secret, hashlock = new_secret()
+client.accept_terms(thread_id, hashlock=hashlock)
+
+# webhooks: verify a delivery against the raw body
+ok = verify_webhook(secret, raw_body, request.headers.get("x-hashlock-signature"), request.headers.get("x-hashlock-timestamp"))
+```
+
+Settlement is custody-agnostic: `build_fund` / `build_claim` / `build_refund` return unsigned transactions —
+sign with your wallet or HSM (see [`../examples/fireblocks`](../examples/fireblocks)) and `broadcast(...)`.
+See the [root README](../README.md) for the full swap lifecycle.
+
+MIT

hashlock_sdk-0.4.0/README.md

@@ -0,0 +1,36 @@
+# hashlock-sdk (Python)
+
+Python SDK for the [Hashlock Markets](https://github.com/Hashlock-Tech/hashlock-sdk) developer API —
+non-custodial cross-chain atomic swaps (BTC ↔ EVM/TRON). Python 3.9+, built on `httpx`.
+
+> ⚠️ **Sandbox / testnet preview (0.x)** — defaults to `api-dev.hashlock.markets`, testnets only,
+> pre-mainnet. The API may change before the stable `1.0`. Not for mainnet funds.
+
+```bash
+pip install hashlock-sdk          # add [ws] for the maker WebSocket feed: hashlock-sdk[ws]
+```
+
+```python
+from hashlock import HashlockClient, new_secret, verify_webhook
+
+client = HashlockClient(api_key=os.environ["HASHLOCK_API_KEY"])
+client.me()
+
+# cursor pagination — page or auto-iterate
+page = client.list_swaps(limit=20)
+for swap in client.swaps():
+    ...
+
+# initiator: secret stays private; submit only the hashlock
+secret, hashlock = new_secret()
+client.accept_terms(thread_id, hashlock=hashlock)
+
+# webhooks: verify a delivery against the raw body
+ok = verify_webhook(secret, raw_body, request.headers.get("x-hashlock-signature"), request.headers.get("x-hashlock-timestamp"))
+```
+
+Settlement is custody-agnostic: `build_fund` / `build_claim` / `build_refund` return unsigned transactions —
+sign with your wallet or HSM (see [`../examples/fireblocks`](../examples/fireblocks)) and `broadcast(...)`.
+See the [root README](../README.md) for the full swap lifecycle.
+
+MIT

hashlock_sdk-0.4.0/hashlock/__init__.py

@@ -0,0 +1,8 @@
+"""Hashlock Markets developer SDK — non-custodial cross-chain atomic swaps (BTC ↔ EVM/TRON)."""
+from .client import HashlockClient
+from .errors import HashlockError
+from .secret import new_secret, sha256_hex
+from .webhooks import verify_webhook
+
+__all__ = ["HashlockClient", "HashlockError", "new_secret", "sha256_hex", "verify_webhook"]
+__version__ = "0.4.0"

hashlock_sdk-0.4.0/hashlock/client.py

@@ -0,0 +1,183 @@
+"""Thin, typed client for the Hashlock Markets developer API (/v1).
+
+Custody-agnostic: the settlement endpoints return UNSIGNED transactions you sign with your own key/HSM
+(see ``examples/``), then hand back to :meth:`HashlockClient.broadcast`. The server never holds your keys.
+"""
+from __future__ import annotations
+
+from typing import Any, Iterator, Optional
+
+import httpx
+
+from .errors import HashlockError
+
+DEFAULT_BASE = "https://api-dev.hashlock.markets/v1"
+
+
+class HashlockClient:
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE, timeout: float = 30.0) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._base = base_url.rstrip("/")
+        self._http = httpx.Client(timeout=timeout, headers={"authorization": f"Bearer {api_key}"})
+
+    # ── context manager ────────────────────────────────────────────────────────
+    def __enter__(self) -> "HashlockClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    # ── core ───────────────────────────────────────────────────────────────────
+    def me(self) -> dict[str, Any]:
+        """Verify the key and see its scopes."""
+        return self._request("GET", "/me")
+
+    def assets(self) -> list[dict[str, Any]]:
+        """The asset registry (chain, token|native, decimals, symbol)."""
+        return self._request("GET", "/assets")["assets"]
+
+    # ── RFQs ─────────────────────────────────────────────────────────────────────
+    def list_rfqs(self, **params: Any) -> dict[str, Any]:
+        """One page of the order book: ``{"items": [...], "next_cursor": str | None}``.
+
+        Query params: base_asset_id, quote_asset_id, direction, limit, cursor.
+        """
+        r = self._request("GET", "/rfqs", params=_camel(params))
+        return {"items": r.get("rfqs", []), "next_cursor": r.get("nextCursor")}
+
+    def rfqs(self, **params: Any) -> Iterator[dict[str, Any]]:
+        """Iterate the whole order book, following the cursor automatically."""
+        yield from self._paginate(self.list_rfqs, params)
+
+    def get_rfq(self, rfq_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/rfqs/{rfq_id}")["rfq"]
+
+    def create_rfq(
+        self,
+        direction: str,
+        base_asset_id: str,
+        base_amount: str,
+        quote_asset_id: str,
+        ttl_seconds: int,
+        ask_amount: Optional[str] = None,
+        visibility: Optional[str] = None,
+        target_address: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Create an RFQ (requires the ``taker`` scope)."""
+        body = {
+            "direction": direction,
+            "baseAssetId": base_asset_id,
+            "baseAmount": base_amount,
+            "quoteAssetId": quote_asset_id,
+            "ttlSeconds": ttl_seconds,
+            "askAmount": ask_amount,
+            "visibility": visibility,
+            "targetAddress": target_address,
+        }
+        return self._request("POST", "/rfqs", json={k: v for k, v in body.items() if v is not None}, idempotency_key=idempotency_key)["rfq"]
+
+    def quote_rfq(self, rfq_id: str, quote_amount: str, idempotency_key: Optional[str] = None) -> dict[str, Any]:
+        """Quote an RFQ (requires the ``maker`` scope) — opens a settlement thread."""
+        return self._request("POST", f"/rfqs/{rfq_id}/quotes", json={"quoteAmount": quote_amount}, idempotency_key=idempotency_key)
+
+    # ── negotiation thread ───────────────────────────────────────────────────────
+    def get_thread(self, thread_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/threads/{thread_id}")
+
+    def propose_terms(self, thread_id: str, quote_amount: str) -> dict[str, Any]:
+        return self._request("POST", f"/threads/{thread_id}/propose", json={"quoteAmount": quote_amount})
+
+    def accept_proposal(self, thread_id: str) -> dict[str, Any]:
+        return self._request("POST", f"/threads/{thread_id}/accept-proposal")
+
+    def accept_terms(self, thread_id: str, hashlock: Optional[str] = None) -> dict[str, Any]:
+        """Accept the current terms. When BOTH sides accept, the swap is created. The initiator (funds the
+        long leg) MUST pass ``hashlock`` = sha256(secret) — see :func:`hashlock.secret.new_secret`."""
+        return self._request("POST", f"/threads/{thread_id}/accept", json={"hashlock": hashlock} if hashlock else {})
+
+    # ── swaps ─────────────────────────────────────────────────────────────────────
+    def list_swaps(self, **params: Any) -> dict[str, Any]:
+        r = self._request("GET", "/swaps", params=_camel(params))
+        return {"items": r.get("swaps", []), "next_cursor": r.get("nextCursor")}
+
+    def swaps(self, **params: Any) -> Iterator[dict[str, Any]]:
+        yield from self._paginate(self.list_swaps, params)
+
+    def get_swap(self, swap_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/swaps/{swap_id}")["swap"]
+
+    def set_swap_address(self, swap_id: str, chain: str, address: str) -> dict[str, Any]:
+        """Set your receive (payout) / refund address for a leg. Bitcoin: the compressed pubkey (hex)."""
+        return self._request("POST", f"/swaps/{swap_id}/address", json={"chain": chain, "address": address})["swap"]
+
+    # ── settlement builders (UNSIGNED — sign with your own key/HSM, then broadcast) ─
+    def build_fund(self, swap_id: str, leg: str) -> dict[str, Any]:
+        return self._request("POST", f"/swaps/{swap_id}/legs/{leg}/fund")
+
+    def build_claim(self, swap_id: str, leg: str, secret: str) -> dict[str, Any]:
+        return self._request("POST", f"/swaps/{swap_id}/legs/{leg}/claim", json={"secret": secret})
+
+    def build_refund(self, swap_id: str, leg: str) -> dict[str, Any]:
+        return self._request("POST", f"/swaps/{swap_id}/legs/{leg}/refund")
+
+    def broadcast(self, chain: str, signed: Any, idempotency_key: Optional[str] = None) -> dict[str, Any]:
+        """Relay a client-signed tx. ``chain``: 'evm' (0x raw) | 'tron' (signed obj) | 'bitcoin' (raw hex)."""
+        return self._request("POST", "/tx/broadcast", json={"chain": chain, "signed": signed}, idempotency_key=idempotency_key)
+
+    # ── webhooks ─────────────────────────────────────────────────────────────────
+    def list_webhooks(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/webhooks")["webhooks"]
+
+    def create_webhook(self, url: str, events: Optional[list[str]] = None) -> dict[str, Any]:
+        """Register a webhook. The returned ``secret`` is shown ONCE — store it to verify deliveries."""
+        body: dict[str, Any] = {"url": url}
+        if events:
+            body["events"] = events
+        return self._request("POST", "/webhooks", json=body)
+
+    def delete_webhook(self, webhook_id: str) -> dict[str, Any]:
+        return self._request("DELETE", f"/webhooks/{webhook_id}")
+
+    def ping_webhook(self, webhook_id: str) -> dict[str, Any]:
+        return self._request("POST", f"/webhooks/{webhook_id}/ping")
+
+    # ── internals ────────────────────────────────────────────────────────────────
+    def _paginate(self, page_fn: Any, params: dict[str, Any]) -> Iterator[dict[str, Any]]:
+        cursor: Optional[str] = None
+        while True:
+            page = page_fn(**{**params, **({"cursor": cursor} if cursor else {})})
+            yield from page["items"]
+            cursor = page["next_cursor"]
+            if not cursor:
+                break
+
+    def _request(self, method: str, path: str, *, params: Any = None, json: Any = None, idempotency_key: Optional[str] = None) -> Any:
+        headers = {}
+        if idempotency_key:
+            headers["idempotency-key"] = idempotency_key
+        resp = self._http.request(method, self._base + path, params=params, json=json, headers=headers or None)
+        try:
+            data = resp.json()
+        except Exception:
+            data = None
+        if resp.status_code >= 400:
+            msg = (data or {}).get("error") if isinstance(data, dict) else None
+            retry_after = resp.headers.get("retry-after")
+            raise HashlockError(resp.status_code, msg or f"HTTP {resp.status_code}", data, int(retry_after) if retry_after else None)
+        return data
+
+
+def _camel(params: dict[str, Any]) -> dict[str, Any]:
+    """snake_case query params → the API's camelCase; drop Nones."""
+    out: dict[str, Any] = {}
+    for k, v in params.items():
+        if v is None:
+            continue
+        parts = k.split("_")
+        out[parts[0] + "".join(p.title() for p in parts[1:])] = v
+    return out

hashlock_sdk-0.4.0/hashlock/errors.py

@@ -0,0 +1,20 @@
+"""Error type raised for non-2xx API responses."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class HashlockError(Exception):
+    def __init__(self, status: int, message: str, body: Any = None, retry_after: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+        self.retry_after = retry_after  # seconds until the rate-limit window resets (on 429)
+
+    @property
+    def is_rate_limited(self) -> bool:
+        return self.status == 429
+
+    @property
+    def is_auth_error(self) -> bool:
+        return self.status in (401, 403)

hashlock_sdk-0.4.0/hashlock/secret.py

@@ -0,0 +1,21 @@
+"""The swap secret + its hashlock.
+
+The INITIATOR (funds the long leg) generates the secret locally, keeps it private, and passes only
+``hashlock = sha256(secret)`` to ``accept_terms``. The secret is revealed on-chain when the initiator
+claims the counter-leg; keep it until then.
+"""
+from __future__ import annotations
+
+import hashlib
+import secrets
+
+
+def new_secret() -> tuple[str, str]:
+    """Return ``(secret_hex, hashlock_hex)`` — a fresh 32-byte secret and its sha256 hashlock (no 0x)."""
+    secret = secrets.token_bytes(32)
+    return secret.hex(), hashlib.sha256(secret).hexdigest()
+
+
+def sha256_hex(hex_str: str) -> str:
+    """sha256(preimage) as hex — verify a preimage against a swap's hashlock."""
+    return hashlib.sha256(bytes.fromhex(hex_str[2:] if hex_str.startswith("0x") else hex_str)).hexdigest()

hashlock_sdk-0.4.0/hashlock/webhooks.py

@@ -0,0 +1,36 @@
+"""Verify webhook deliveries.
+
+The server signs each POST with::
+
+    X-Hashlock-Signature: sha256=HMAC-SHA256(secret, f"{timestamp}.{raw_body}")
+
+where ``timestamp`` is the ``X-Hashlock-Timestamp`` header. Verify against the RAW request body.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from typing import Optional
+
+
+def verify_webhook(
+    secret: str,
+    raw_body: str,
+    signature: Optional[str],
+    timestamp: Optional[str],
+    tolerance_seconds: int = 300,
+    now_unix: Optional[int] = None,
+) -> bool:
+    """Return True iff the signature matches and the timestamp is within tolerance (0 disables the check)."""
+    if not signature or not timestamp:
+        return False
+    if tolerance_seconds > 0:
+        try:
+            ts = int(timestamp)
+        except ValueError:
+            return False
+        if abs((now_unix if now_unix is not None else int(time.time())) - ts) > tolerance_seconds:
+            return False
+    expected = "sha256=" + hmac.new(secret.encode(), f"{timestamp}.{raw_body}".encode(), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature)

hashlock_sdk-0.4.0/hashlock/ws.py

@@ -0,0 +1,41 @@
+"""Maker feed over WebSocket (/v1/ws), using the ``websockets`` library (async).
+
+Authenticate with an API key that has the ``maker`` scope, receive a snapshot of the public order book,
+then a live stream of quotable RFQs; submit quotes on the same socket.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncIterator
+
+try:
+    import websockets  # type: ignore
+except ImportError:  # pragma: no cover
+    websockets = None  # the maker feed is optional; install `hashlock-sdk[ws]`
+
+DEFAULT_WS = "wss://api-dev.hashlock.markets/v1/ws"
+
+
+async def maker_feed(api_key: str, url: str = DEFAULT_WS) -> AsyncIterator[dict[str, Any]]:
+    """Async-iterate feed messages: {'type': 'snapshot'|'ready'|'rfq'|'quoted'|'error', ...}.
+
+    Example::
+
+        async for msg in maker_feed(api_key):
+            if msg["type"] == "rfq":
+                ...  # decide whether to quote
+    """
+    if websockets is None:
+        raise RuntimeError("install `hashlock-sdk[ws]` (the `websockets` package) to use the maker feed")
+    async with websockets.connect(url) as ws:
+        await ws.send(json.dumps({"apiKey": api_key}))
+        async for raw in ws:
+            try:
+                yield json.loads(raw)
+            except json.JSONDecodeError:
+                continue
+
+
+async def submit_quote(ws: Any, rfq_id: str, quote_amount: str) -> None:
+    """Submit a quote on an open maker-feed socket."""
+    await ws.send(json.dumps({"quote": {"rfqId": rfq_id, "quoteAmount": quote_amount}}))

hashlock_sdk-0.4.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hashlock-sdk"
+version = "0.4.0"
+description = "Python SDK for the Hashlock Markets developer API — non-custodial cross-chain atomic swaps (BTC <-> EVM/TRON) over sealed RFQ + HTLC."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["hashlock", "atomic-swap", "htlc", "bitcoin", "cross-chain", "otc", "defi"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: MIT License",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Office/Business :: Financial",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.optional-dependencies]
+ws = ["websockets>=12"]
+
+[project.urls]
+Homepage = "https://github.com/Hashlock-Tech/hashlock-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["hashlock"]