layerhop 0.1.0__tar.gz

layerhop-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/
+build/

layerhop-0.1.0/LICENSE

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

layerhop-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: layerhop
+Version: 0.1.0
+Summary: LayerHop SDK - best-price cross-chain and same-chain swaps (sync + async, httpx)
+Project-URL: Homepage, https://layerhop.com
+Project-URL: Changelog, https://docs.layerhop.com/changelog
+Project-URL: Documentation, https://docs.layerhop.com/sdks/python
+Project-URL: Repository, https://github.com/layerhop/layerhop-python
+Project-URL: Issues, https://github.com/layerhop/layerhop-python/issues
+Author-email: LayerHop <dev@layerhop.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bridge,bridge-aggregator,cross-chain,defi,dex-aggregator,ethereum,evm,layerhop,sdk,solana,swap,web3
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Requires-Dist: typing-extensions>=4.5; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: anyio>=4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# layerhop (Python SDK)
+
+[![PyPI](https://img.shields.io/pypi/v/layerhop?color=c3f06b&labelColor=090d15)](https://pypi.org/project/layerhop/) [![Python](https://img.shields.io/pypi/pyversions/layerhop?color=7ddec8&labelColor=090d15)](https://pypi.org/project/layerhop/) [![license](https://img.shields.io/pypi/l/layerhop?color=7ddec8&labelColor=090d15)](https://opensource.org/license/mit) [![docs](https://img.shields.io/badge/docs-docs.layerhop.com-7ddec8?labelColor=090d15)](https://docs.layerhop.com/sdks/python)
+
+Best-price cross-chain and same-chain swaps through one non-custodial API. Sync and async clients
+on top of [httpx](https://www.python-httpx.org/), mirroring the TypeScript `@layerhop/sdk`.
+
+> **The SDK never holds keys.** It returns *unsigned* transactions. Your own wallet library
+> (web3.py, eth-account, solders, a KMS, a hardware wallet…) signs and broadcasts them.
+
+## Install
+
+```bash
+pip install layerhop
+```
+
+Python 3.9+. The only runtime dependency is `httpx`.
+
+## Quickstart
+
+Amounts are **integer strings in base units** (100 USDC = `"100000000"`), never floats.
+
+```python
+from layerhop import LayerHop
+
+lh = LayerHop(api_key="lh_live_...")  # api_key is optional
+
+# 1. Quote: every provider is asked; `best` pays the user the most.
+q = lh.quote("base", "USDC", "100000000", "solana", "SOL",
+             sender="0xYourEvmAddress", recipient="YourSolanaAddress")
+best = q["best"]
+print(best["provider"], best["dstAmount"], best["estimatedSeconds"])
+
+# 2. Build the unsigned transaction.
+tx = lh.build_tx(best["quoteId"])
+
+# 3. Sign and send with YOUR wallet library (example: web3.py on Base).
+if tx["vm"] == "evm":
+    # if tx.get("approval"): send ERC-20 approve(spender, amount) on approval["token"] first
+    tx_hash = w3.eth.send_transaction({
+        "to": tx["to"], "data": tx["data"], "value": int(tx["value"]), "chainId": tx["chainId"],
+    }).hex()
+else:
+    # Solana: tx["serializedTx"] is a base64 VersionedTransaction; sign it with solders.
+    # When tx.get("submitViaApi") is true, only sign, then: tx_hash = lh.submit(best["quoteId"], signed_b64)
+    ...
+
+# 4. Tell LayerHop you broadcast it (enables tracking, history and webhooks).
+lh.report_submitted(best["quoteId"], tx_hash)
+
+# 5. Track until filled / refunded / failed.
+for s in lh.watch(best["provider"], tx_hash):
+    print(s["state"], s.get("dstTxHash"))
+```
+
+### Async
+
+```python
+from layerhop import AsyncLayerHop
+
+async with AsyncLayerHop() as lh:
+    q = await lh.quote("base", "USDC", "100000000", "solana", "SOL", sender=s, recipient=r)
+    async for st in lh.watch("relay", tx_hash):
+        print(st["state"])
+```
+
+## API
+
+| Method | Endpoint |
+|---|---|
+| `health()` | `GET /v1/health` |
+| `chains()` | `GET /v1/chains` |
+| `tokens(chain)` | `GET /v1/tokens?chain=` |
+| `quote(src_chain, src_token, amount, dst_chain, dst_token, *, sender, recipient, slippage_bps=50)` | `GET /v1/quote` |
+| `build_tx(quote_id)` | `POST /v1/orders` → the `tx` |
+| `simulate(quote_id)` | `POST /v1/simulate` (dry-run, records nothing) |
+| `submit(quote_id, signed_transaction)` | `POST /v1/orders/submit` (Solana `submitViaApi` only) |
+| `report_submitted(quote_id, tx_hash)` | `POST /v1/orders/{quoteId}/submitted` |
+| `status(provider, id)` | `GET /v1/orders/{provider}/{id}` |
+| `watch(provider, id, *, interval=3.0, timeout=1800)` | polls `status`, yields on change, stops when final |
+| `list_orders(*, address, status, cursor, limit)` | `GET /v1/orders` |
+
+Client options: `base_url` (default `https://api.layerhop.com`), `api_key` (sent as `x-api-key`),
+`channel` (default `"api"`), `integrator`, `integrator_fee_bps`, `timeout`, and `http_client` /
+`transport` for custom httpx setups or tests.
+
+Responses are plain dicts typed with `TypedDict` (keys keep the API's camelCase), so new fields
+never break you.
+
+## Errors
+
+Every non-2xx response raises `LayerHopApiError` with a stable `code` (`QUOTE_EXPIRED`,
+`NO_ROUTE`, …), `status`, `message` and `request_id`. See
+`https://docs.layerhop.com/errors/<code>`.
+
+```python
+from layerhop import LayerHopApiError
+try:
+    lh.build_tx(quote_id)
+except LayerHopApiError as e:
+    if e.code == "QUOTE_EXPIRED":
+        ...  # re-quote
+```
+
+## Webhooks
+
+```python
+from layerhop import verify_webhook_signature, construct_webhook_event
+
+# Flask example — use the RAW body
+ok = verify_webhook_signature(secret, request.get_data(), request.headers.get("LayerHop-Signature"))
+event = construct_webhook_event(secret, request.get_data(), request.headers.get("LayerHop-Signature"))
+```
+
+The header is `t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>`. Signatures older or newer
+than 300 s (`tolerance`) are rejected; comparison is constant-time.
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/python -m pytest
+```
+
+MIT licensed.

layerhop-0.1.0/README.md

@@ -0,0 +1,125 @@
+# layerhop (Python SDK)
+
+[![PyPI](https://img.shields.io/pypi/v/layerhop?color=c3f06b&labelColor=090d15)](https://pypi.org/project/layerhop/) [![Python](https://img.shields.io/pypi/pyversions/layerhop?color=7ddec8&labelColor=090d15)](https://pypi.org/project/layerhop/) [![license](https://img.shields.io/pypi/l/layerhop?color=7ddec8&labelColor=090d15)](https://opensource.org/license/mit) [![docs](https://img.shields.io/badge/docs-docs.layerhop.com-7ddec8?labelColor=090d15)](https://docs.layerhop.com/sdks/python)
+
+Best-price cross-chain and same-chain swaps through one non-custodial API. Sync and async clients
+on top of [httpx](https://www.python-httpx.org/), mirroring the TypeScript `@layerhop/sdk`.
+
+> **The SDK never holds keys.** It returns *unsigned* transactions. Your own wallet library
+> (web3.py, eth-account, solders, a KMS, a hardware wallet…) signs and broadcasts them.
+
+## Install
+
+```bash
+pip install layerhop
+```
+
+Python 3.9+. The only runtime dependency is `httpx`.
+
+## Quickstart
+
+Amounts are **integer strings in base units** (100 USDC = `"100000000"`), never floats.
+
+```python
+from layerhop import LayerHop
+
+lh = LayerHop(api_key="lh_live_...")  # api_key is optional
+
+# 1. Quote: every provider is asked; `best` pays the user the most.
+q = lh.quote("base", "USDC", "100000000", "solana", "SOL",
+             sender="0xYourEvmAddress", recipient="YourSolanaAddress")
+best = q["best"]
+print(best["provider"], best["dstAmount"], best["estimatedSeconds"])
+
+# 2. Build the unsigned transaction.
+tx = lh.build_tx(best["quoteId"])
+
+# 3. Sign and send with YOUR wallet library (example: web3.py on Base).
+if tx["vm"] == "evm":
+    # if tx.get("approval"): send ERC-20 approve(spender, amount) on approval["token"] first
+    tx_hash = w3.eth.send_transaction({
+        "to": tx["to"], "data": tx["data"], "value": int(tx["value"]), "chainId": tx["chainId"],
+    }).hex()
+else:
+    # Solana: tx["serializedTx"] is a base64 VersionedTransaction; sign it with solders.
+    # When tx.get("submitViaApi") is true, only sign, then: tx_hash = lh.submit(best["quoteId"], signed_b64)
+    ...
+
+# 4. Tell LayerHop you broadcast it (enables tracking, history and webhooks).
+lh.report_submitted(best["quoteId"], tx_hash)
+
+# 5. Track until filled / refunded / failed.
+for s in lh.watch(best["provider"], tx_hash):
+    print(s["state"], s.get("dstTxHash"))
+```
+
+### Async
+
+```python
+from layerhop import AsyncLayerHop
+
+async with AsyncLayerHop() as lh:
+    q = await lh.quote("base", "USDC", "100000000", "solana", "SOL", sender=s, recipient=r)
+    async for st in lh.watch("relay", tx_hash):
+        print(st["state"])
+```
+
+## API
+
+| Method | Endpoint |
+|---|---|
+| `health()` | `GET /v1/health` |
+| `chains()` | `GET /v1/chains` |
+| `tokens(chain)` | `GET /v1/tokens?chain=` |
+| `quote(src_chain, src_token, amount, dst_chain, dst_token, *, sender, recipient, slippage_bps=50)` | `GET /v1/quote` |
+| `build_tx(quote_id)` | `POST /v1/orders` → the `tx` |
+| `simulate(quote_id)` | `POST /v1/simulate` (dry-run, records nothing) |
+| `submit(quote_id, signed_transaction)` | `POST /v1/orders/submit` (Solana `submitViaApi` only) |
+| `report_submitted(quote_id, tx_hash)` | `POST /v1/orders/{quoteId}/submitted` |
+| `status(provider, id)` | `GET /v1/orders/{provider}/{id}` |
+| `watch(provider, id, *, interval=3.0, timeout=1800)` | polls `status`, yields on change, stops when final |
+| `list_orders(*, address, status, cursor, limit)` | `GET /v1/orders` |
+
+Client options: `base_url` (default `https://api.layerhop.com`), `api_key` (sent as `x-api-key`),
+`channel` (default `"api"`), `integrator`, `integrator_fee_bps`, `timeout`, and `http_client` /
+`transport` for custom httpx setups or tests.
+
+Responses are plain dicts typed with `TypedDict` (keys keep the API's camelCase), so new fields
+never break you.
+
+## Errors
+
+Every non-2xx response raises `LayerHopApiError` with a stable `code` (`QUOTE_EXPIRED`,
+`NO_ROUTE`, …), `status`, `message` and `request_id`. See
+`https://docs.layerhop.com/errors/<code>`.
+
+```python
+from layerhop import LayerHopApiError
+try:
+    lh.build_tx(quote_id)
+except LayerHopApiError as e:
+    if e.code == "QUOTE_EXPIRED":
+        ...  # re-quote
+```
+
+## Webhooks
+
+```python
+from layerhop import verify_webhook_signature, construct_webhook_event
+
+# Flask example — use the RAW body
+ok = verify_webhook_signature(secret, request.get_data(), request.headers.get("LayerHop-Signature"))
+event = construct_webhook_event(secret, request.get_data(), request.headers.get("LayerHop-Signature"))
+```
+
+The header is `t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>`. Signatures older or newer
+than 300 s (`tolerance`) are rejected; comparison is constant-time.
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/python -m pytest
+```
+
+MIT licensed.

layerhop-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "layerhop"
+version = "0.1.0"
+description = "LayerHop SDK - best-price cross-chain and same-chain swaps (sync + async, httpx)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "LayerHop", email = "dev@layerhop.com" }]
+dependencies = ["httpx>=0.24,<1", "typing_extensions>=4.5; python_version < \"3.11\""]
+keywords = ["layerhop", "bridge", "swap", "cross-chain", "solana", "evm", "ethereum", "defi", "web3", "dex-aggregator", "bridge-aggregator", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Office/Business :: Financial",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+  "Framework :: AsyncIO",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "anyio>=4"]
+
+[project.urls]
+Homepage = "https://layerhop.com"
+Changelog = "https://docs.layerhop.com/changelog"
+Documentation = "https://docs.layerhop.com/sdks/python"
+Repository = "https://github.com/layerhop/layerhop-python"
+Issues = "https://github.com/layerhop/layerhop-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/layerhop"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

layerhop-0.1.0/src/layerhop/__init__.py

@@ -0,0 +1,48 @@
+"""LayerHop Python SDK -- best-price cross-chain and same-chain swaps.
+
+The SDK never holds private keys: it returns unsigned transactions for your own wallet to sign.
+"""
+
+from .client import DEFAULT_BASE_URL, AsyncLayerHop, LayerHop, __version__
+from .errors import LayerHopApiError, WebhookSignatureError
+from .types import (
+    FINAL_STATES,
+    Approval,
+    BuiltTx,
+    Chain,
+    EvmTx,
+    FeeBreakdown,
+    FeeChannel,
+    Order,
+    OrdersPage,
+    OrderState,
+    OrderStatus,
+    ProviderError,
+    ProviderId,
+    Quote,
+    QuoteResponse,
+    ReportSubmittedResponse,
+    SimulateError,
+    SimulateResponse,
+    SvmTx,
+    Token,
+)
+from .webhooks import (
+    SIGNATURE_HEADER,
+    compute_webhook_signature,
+    construct_webhook_event,
+    verify_webhook_signature,
+)
+
+SOLANA_CHAIN_ID = 7565164
+EVM_NATIVE = "0x0000000000000000000000000000000000000000"
+SOL_NATIVE = "So11111111111111111111111111111111111111112"
+
+__all__ = [
+    "LayerHop", "AsyncLayerHop", "LayerHopApiError", "WebhookSignatureError", "DEFAULT_BASE_URL", "__version__",
+    "verify_webhook_signature", "construct_webhook_event", "compute_webhook_signature", "SIGNATURE_HEADER",
+    "SOLANA_CHAIN_ID", "EVM_NATIVE", "SOL_NATIVE", "FINAL_STATES",
+    "Approval", "BuiltTx", "Chain", "EvmTx", "FeeBreakdown", "FeeChannel", "Order", "OrdersPage", "OrderState",
+    "OrderStatus", "ProviderError", "ProviderId", "Quote", "QuoteResponse", "ReportSubmittedResponse",
+    "SimulateError", "SimulateResponse", "SvmTx", "Token",
+]

layerhop-0.1.0/src/layerhop/client.py

@@ -0,0 +1,292 @@
+"""Sync and async LayerHop clients (httpx).
+
+The SDK never holds private keys: it returns unsigned transactions that your own wallet library
+signs and broadcasts.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, AsyncIterator, Dict, Iterator, List, Optional, Union
+from urllib.parse import quote as _urlquote
+
+import httpx
+
+from .errors import LayerHopApiError
+from .types import (
+    FINAL_STATES,
+    BuiltTx,
+    Chain,
+    FeeChannel,
+    OrdersPage,
+    OrderStatus,
+    QuoteResponse,
+    ReportSubmittedResponse,
+    SimulateResponse,
+    Token,
+)
+
+DEFAULT_BASE_URL = "https://api.layerhop.com"
+DEFAULT_TIMEOUT = 30.0
+__version__ = "0.1.0"
+
+
+def _seg(v: str) -> str:
+    return _urlquote(str(v), safe="")
+
+
+class _Base:
+    def __init__(
+        self,
+        *,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        channel: FeeChannel = "api",
+        integrator: Optional[str] = None,
+        integrator_fee_bps: Optional[int] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.api_key = api_key
+        self.channel = channel
+        self.integrator = integrator
+        self.integrator_fee_bps = integrator_fee_bps
+        self.timeout = timeout
+
+    def _headers(self) -> Dict[str, str]:
+        h = {"accept": "application/json", "user-agent": f"layerhop-python/{__version__}"}
+        if self.api_key:
+            h["x-api-key"] = self.api_key
+        return h
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}/v1{path}"
+
+    def _quote_params(
+        self, src_chain: Union[str, int], src_token: str, amount: str, dst_chain: Union[str, int],
+        dst_token: str, sender: str, recipient: str, slippage_bps: int,
+    ) -> Dict[str, str]:
+        if not isinstance(amount, str):
+            raise TypeError("amount must be an integer string in base units (e.g. '100000000')")
+        q = {
+            "srcChain": str(src_chain), "srcToken": src_token, "amount": amount,
+            "dstChain": str(dst_chain), "dstToken": dst_token, "sender": sender, "recipient": recipient,
+            "slippageBps": str(slippage_bps), "channel": self.channel,
+        }
+        if self.integrator:
+            q["integrator"] = self.integrator
+        if self.integrator_fee_bps is not None:
+            q["integratorFeeBps"] = str(self.integrator_fee_bps)
+        return q
+
+    @staticmethod
+    def _orders_params(address: Optional[str], status: Optional[str], cursor: Optional[str], limit: Optional[int]) -> Dict[str, str]:
+        p: Dict[str, str] = {}
+        if address:
+            p["address"] = address
+        if status:
+            p["status"] = status
+        if cursor:
+            p["cursor"] = cursor
+        if limit is not None:
+            p["limit"] = str(limit)
+        return p
+
+    @staticmethod
+    def _handle(res: httpx.Response) -> Any:
+        try:
+            body = res.json()
+        except ValueError:
+            body = {}
+        if res.is_success:
+            return body
+        err = body.get("error") if isinstance(body, dict) else None
+        if not isinstance(err, dict):
+            err = {}
+        raise LayerHopApiError(
+            code=str(err.get("code") or "INTERNAL"),
+            message=str(err.get("message") or res.reason_phrase or f"HTTP {res.status_code}"),
+            status=res.status_code,
+            request_id=err.get("requestId") or res.headers.get("x-request-id"),
+            docs_url=err.get("docsUrl"),
+        )
+
+
+class LayerHop(_Base):
+    """Synchronous client.
+
+    >>> lh = LayerHop(api_key="lh_live_...")
+    >>> q = lh.quote("base", "USDC", "100000000", "solana", "SOL", sender="0x...", recipient="9WzD...")
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        channel: FeeChannel = "api",
+        integrator: Optional[str] = None,
+        integrator_fee_bps: Optional[int] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: Optional[httpx.Client] = None,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        super().__init__(base_url=base_url, api_key=api_key, channel=channel, integrator=integrator,
+                         integrator_fee_bps=integrator_fee_bps, timeout=timeout)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout, transport=transport)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "LayerHop":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def _call(self, method: str, path: str, *, params: Optional[Dict[str, str]] = None, json: Any = None) -> Any:
+        res = self._client.request(method, self._url(path), params=params, json=json, headers=self._headers())
+        return self._handle(res)
+
+    def health(self) -> Dict[str, Any]:
+        return self._call("GET", "/health")
+
+    def chains(self) -> List[Chain]:
+        return self._call("GET", "/chains")["chains"]
+
+    def tokens(self, chain: Union[str, int]) -> List[Token]:
+        return self._call("GET", "/tokens", params={"chain": str(chain)})["tokens"]
+
+    def quote(
+        self, src_chain: Union[str, int], src_token: str, amount: str, dst_chain: Union[str, int], dst_token: str,
+        *, sender: str, recipient: str, slippage_bps: int = 50,
+    ) -> QuoteResponse:
+        """Ask every provider; ``best`` is the highest output for the user. ``amount`` is base units."""
+        return self._call("GET", "/quote", params=self._quote_params(
+            src_chain, src_token, amount, dst_chain, dst_token, sender, recipient, slippage_bps))
+
+    def build_tx(self, quote_id: str) -> BuiltTx:
+        """The unsigned transaction for a quote. EVM txs may carry an ``approval`` to send first."""
+        return self._call("POST", "/orders", json={"quoteId": quote_id})["tx"]
+
+    def submit(self, quote_id: str, signed_transaction: str) -> str:
+        """For SvmTx with ``submitViaApi``: send the wallet-signed tx (base64). Returns the signature."""
+        return self._call("POST", "/orders/submit", json={"quoteId": quote_id, "signedTransaction": signed_transaction})["txHash"]
+
+    def report_submitted(self, quote_id: str, tx_hash: str) -> ReportSubmittedResponse:
+        """Tell LayerHop you broadcast the tx, so it tracks the order (and fires webhooks). Idempotent."""
+        return self._call("POST", f"/orders/{_seg(quote_id)}/submitted", json={"txHash": tx_hash})
+
+    def simulate(self, quote_id: str) -> SimulateResponse:
+        """Build and dry-run the tx without recording an order."""
+        return self._call("POST", "/simulate", json={"quoteId": quote_id})
+
+    def status(self, provider: str, id: str) -> OrderStatus:
+        return self._call("GET", f"/orders/{_seg(provider)}/{_seg(id)}")
+
+    def list_orders(
+        self, *, address: Optional[str] = None, status: Optional[str] = None,
+        cursor: Optional[str] = None, limit: Optional[int] = None,
+    ) -> OrdersPage:
+        """Orders by sender or recipient address, newest first. Pass ``nextCursor`` to page."""
+        return self._call("GET", "/orders", params=self._orders_params(address, status, cursor, limit))
+
+    def watch(self, provider: str, id: str, *, interval: float = 3.0, timeout: float = 1800.0) -> Iterator[OrderStatus]:
+        """Poll until the order is final (filled/refunded/failed), yielding each state change."""
+        end = time.monotonic() + timeout
+        last = None
+        while time.monotonic() < end:
+            s = self.status(provider, id)
+            if s["state"] != last:
+                last = s["state"]
+                yield s
+            if s["state"] in FINAL_STATES:
+                return
+            time.sleep(interval)
+
+
+class AsyncLayerHop(_Base):
+    """Asynchronous client with the same methods as :class:`LayerHop` (``await``-able)."""
+
+    def __init__(
+        self,
+        *,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        channel: FeeChannel = "api",
+        integrator: Optional[str] = None,
+        integrator_fee_bps: Optional[int] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: Optional[httpx.AsyncClient] = None,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        super().__init__(base_url=base_url, api_key=api_key, channel=channel, integrator=integrator,
+                         integrator_fee_bps=integrator_fee_bps, timeout=timeout)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(timeout=timeout, transport=transport)
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncLayerHop":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def _call(self, method: str, path: str, *, params: Optional[Dict[str, str]] = None, json: Any = None) -> Any:
+        res = await self._client.request(method, self._url(path), params=params, json=json, headers=self._headers())
+        return self._handle(res)
+
+    async def health(self) -> Dict[str, Any]:
+        return await self._call("GET", "/health")
+
+    async def chains(self) -> List[Chain]:
+        return (await self._call("GET", "/chains"))["chains"]
+
+    async def tokens(self, chain: Union[str, int]) -> List[Token]:
+        return (await self._call("GET", "/tokens", params={"chain": str(chain)}))["tokens"]
+
+    async def quote(
+        self, src_chain: Union[str, int], src_token: str, amount: str, dst_chain: Union[str, int], dst_token: str,
+        *, sender: str, recipient: str, slippage_bps: int = 50,
+    ) -> QuoteResponse:
+        return await self._call("GET", "/quote", params=self._quote_params(
+            src_chain, src_token, amount, dst_chain, dst_token, sender, recipient, slippage_bps))
+
+    async def build_tx(self, quote_id: str) -> BuiltTx:
+        return (await self._call("POST", "/orders", json={"quoteId": quote_id}))["tx"]
+
+    async def submit(self, quote_id: str, signed_transaction: str) -> str:
+        return (await self._call("POST", "/orders/submit", json={"quoteId": quote_id, "signedTransaction": signed_transaction}))["txHash"]
+
+    async def report_submitted(self, quote_id: str, tx_hash: str) -> ReportSubmittedResponse:
+        return await self._call("POST", f"/orders/{_seg(quote_id)}/submitted", json={"txHash": tx_hash})
+
+    async def simulate(self, quote_id: str) -> SimulateResponse:
+        return await self._call("POST", "/simulate", json={"quoteId": quote_id})
+
+    async def status(self, provider: str, id: str) -> OrderStatus:
+        return await self._call("GET", f"/orders/{_seg(provider)}/{_seg(id)}")
+
+    async def list_orders(
+        self, *, address: Optional[str] = None, status: Optional[str] = None,
+        cursor: Optional[str] = None, limit: Optional[int] = None,
+    ) -> OrdersPage:
+        return await self._call("GET", "/orders", params=self._orders_params(address, status, cursor, limit))
+
+    async def watch(self, provider: str, id: str, *, interval: float = 3.0, timeout: float = 1800.0) -> AsyncIterator[OrderStatus]:
+        end = time.monotonic() + timeout
+        last = None
+        while time.monotonic() < end:
+            s = await self.status(provider, id)
+            if s["state"] != last:
+                last = s["state"]
+                yield s
+            if s["state"] in FINAL_STATES:
+                return
+            await asyncio.sleep(interval)

layerhop-0.1.0/src/layerhop/errors.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class LayerHopApiError(Exception):
+    """A non-2xx API response. ``code`` is a stable error code, e.g. ``QUOTE_EXPIRED``.
+
+    See https://docs.layerhop.com/errors/<code> for causes and fixes.
+    """
+
+    def __init__(self, code: str, message: str, status: int, request_id: Optional[str] = None, docs_url: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.request_id = request_id
+        self.docs_url = docs_url
+
+    def __repr__(self) -> str:
+        return f"LayerHopApiError(code={self.code!r}, status={self.status}, message={self.message!r}, request_id={self.request_id!r})"
+
+    def __str__(self) -> str:
+        return f"{self.code}: {self.message}"
+
+
+class WebhookSignatureError(Exception):
+    """Raised by :func:`layerhop.construct_webhook_event` when a signature does not verify."""

layerhop-0.1.0/src/layerhop/types.py

@@ -0,0 +1,158 @@
+"""Typed models for the LayerHop API.
+
+Responses are plain ``dict`` objects typed as ``TypedDict`` so unknown fields added by newer API
+versions pass through untouched. Keys keep the API's camelCase spelling. Amounts are always
+integer strings in base units -- never floats.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Dict, List, Literal, Optional, Union
+
+if sys.version_info >= (3, 11):
+    from typing import NotRequired, TypedDict
+else:  # pragma: no cover
+    from typing_extensions import NotRequired, TypedDict
+
+ProviderId = str
+"""``jupiter`` | ``relay`` | ``debridge`` | ``mayan`` | ``zerox`` | ``kyberswap`` | ``odos`` | ``lifi`` | ``mock``"""
+
+FeeChannel = Literal["web", "widget", "bot", "api"]
+OrderState = Literal["pending", "filled", "refunded", "failed", "unknown"]
+FINAL_STATES = frozenset({"filled", "refunded", "failed"})
+
+
+class Chain(TypedDict):
+    id: int
+    slug: str
+    name: str
+    vm: Literal["evm", "svm"]
+    nativeSymbol: str
+    nativeDecimals: int
+    explorerTx: str
+
+
+class Token(TypedDict):
+    chainId: int
+    address: str
+    symbol: str
+    decimals: int
+
+
+class FeeBreakdown(TypedDict):
+    ourFeeBps: int
+    providerFeeUsd: NotRequired[float]
+    gasUsd: NotRequired[float]
+    integratorFeeBps: NotRequired[int]
+    integrator: NotRequired[str]
+
+
+class Quote(TypedDict):
+    quoteId: str
+    provider: ProviderId
+    dstAmount: str
+    dstAmountMin: str
+    estimatedSeconds: int
+    fees: FeeBreakdown
+    expiresAt: int
+
+
+class ProviderError(TypedDict):
+    provider: str
+    code: str
+    message: str
+
+
+class QuoteResponse(TypedDict):
+    best: Quote
+    quotes: List[Quote]
+    errors: List[ProviderError]
+
+
+class Approval(TypedDict):
+    token: str
+    spender: str
+    amount: str
+
+
+class EvmTx(TypedDict):
+    vm: Literal["evm"]
+    chainId: int
+    to: str
+    data: str
+    value: str
+    approval: NotRequired[Approval]
+
+
+class SvmTx(TypedDict):
+    vm: Literal["svm"]
+    serializedTx: str
+    submitViaApi: NotRequired[bool]
+
+
+BuiltTx = Union[EvmTx, SvmTx]
+
+
+class OrderStatus(TypedDict):
+    provider: ProviderId
+    id: str
+    state: OrderState
+    srcTxHash: NotRequired[str]
+    dstTxHash: NotRequired[str]
+
+
+class ReportSubmittedResponse(TypedDict):
+    quoteId: str
+    status: str
+
+
+class SimulateError(TypedDict):
+    code: str
+    message: str
+    logs: NotRequired[List[str]]
+
+
+class SimulateResponse(TypedDict):
+    quoteId: str
+    provider: ProviderId
+    ok: bool
+    vm: Literal["evm", "svm"]
+    gasEstimate: NotRequired[str]
+    computeUnits: NotRequired[int]
+    needsApproval: NotRequired[bool]
+    simulated: NotRequired[Literal["tx", "approval"]]
+    error: NotRequired[SimulateError]
+    tx: BuiltTx
+
+
+class Order(TypedDict, total=False):
+    """A recorded order. Fields follow the API; unknown ones are kept as-is."""
+
+    quoteId: str
+    provider: ProviderId
+    status: str
+    statusDetail: Optional[str]
+    channel: FeeChannel
+    ourFeeBps: int
+    partnerFeeBps: int
+    sender: str
+    recipient: str
+    srcChainId: int
+    srcToken: str
+    dstChainId: int
+    dstToken: str
+    amount: str
+    dstAmount: str
+    srcTxHash: str
+    dstTxHash: str
+    createdAt: str
+    updatedAt: str
+
+
+class OrdersPage(TypedDict):
+    orders: List[Order]
+    nextCursor: NotRequired[Optional[str]]
+
+
+Json = Dict[str, Any]

layerhop-0.1.0/src/layerhop/webhooks.py

@@ -0,0 +1,85 @@
+"""Webhook signature verification.
+
+LayerHop signs every delivery with the ``LayerHop-Signature`` header::
+
+    LayerHop-Signature: t=<unix seconds>,v1=<hex hmac_sha256(secret, "<t>.<raw body>")>
+
+Always verify against the *raw* request body (bytes as received), before parsing JSON.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Dict, List, Optional, Union
+
+from .errors import WebhookSignatureError
+
+SIGNATURE_HEADER = "LayerHop-Signature"
+DEFAULT_TOLERANCE_SECONDS = 300
+
+
+def _as_bytes(v: Union[str, bytes]) -> bytes:
+    return v.encode("utf-8") if isinstance(v, str) else v
+
+
+def _parse_header(header: str) -> "tuple[Optional[int], List[str]]":
+    t: Optional[int] = None
+    sigs: List[str] = []
+    for part in header.split(","):
+        k, sep, v = part.strip().partition("=")
+        if not sep:
+            continue
+        if k == "t":
+            try:
+                t = int(v)
+            except ValueError:
+                return None, []
+        elif k == "v1":
+            sigs.append(v.strip())
+    return t, sigs
+
+
+def compute_webhook_signature(secret: Union[str, bytes], timestamp: int, body: Union[str, bytes]) -> str:
+    """Hex HMAC-SHA256 of ``"<timestamp>.<body>"`` -- useful for tests of your own endpoint."""
+    msg = str(timestamp).encode("ascii") + b"." + _as_bytes(body)
+    return hmac.new(_as_bytes(secret), msg, hashlib.sha256).hexdigest()
+
+
+def verify_webhook_signature(
+    secret: Union[str, bytes],
+    body: Union[str, bytes],
+    header: Optional[str],
+    tolerance: int = DEFAULT_TOLERANCE_SECONDS,
+    now: Optional[float] = None,
+) -> bool:
+    """Return True when ``header`` is a valid, fresh signature of ``body`` for ``secret``.
+
+    Rejects timestamps more than ``tolerance`` seconds away from ``now`` (replay protection).
+    Accepts any of several ``v1=`` values (secret rotation). Comparison is constant-time.
+    """
+    if not header:
+        return False
+    t, sigs = _parse_header(header)
+    if t is None or not sigs:
+        return False
+    current = time.time() if now is None else now
+    if abs(current - t) > tolerance:
+        return False
+    expected = compute_webhook_signature(secret, t, body)
+    return any(hmac.compare_digest(expected, s) for s in sigs)
+
+
+def construct_webhook_event(
+    secret: Union[str, bytes],
+    body: Union[str, bytes],
+    header: Optional[str],
+    tolerance: int = DEFAULT_TOLERANCE_SECONDS,
+    now: Optional[float] = None,
+) -> Dict[str, Any]:
+    """Verify the signature and return the parsed event, or raise :class:`WebhookSignatureError`."""
+    if not verify_webhook_signature(secret, body, header, tolerance=tolerance, now=now):
+        raise WebhookSignatureError("Invalid or expired LayerHop-Signature")
+    return json.loads(_as_bytes(body))

layerhop-0.1.0/tests/conftest.py

@@ -0,0 +1,54 @@
+import json
+from typing import Any, Callable, Dict, List, Tuple
+
+import httpx
+import pytest
+
+Route = Tuple[str, str]  # (method, path)
+
+
+class FakeApi:
+    """A tiny router over httpx.MockTransport that records every request."""
+
+    def __init__(self) -> None:
+        self.routes: Dict[Route, Callable[[httpx.Request], httpx.Response]] = {}
+        self.requests: List[httpx.Request] = []
+
+    def on(self, method: str, path: str, body: Any = None, status: int = 200, handler: Any = None) -> None:
+        if handler is None:
+            def handler(_req: httpx.Request, _b: Any = body, _s: int = status) -> httpx.Response:
+                return httpx.Response(_s, json=_b)
+        self.routes[(method, path)] = handler
+
+    def __call__(self, req: httpx.Request) -> httpx.Response:
+        self.requests.append(req)
+        h = self.routes.get((req.method, req.url.raw_path.decode().split("?")[0]))
+        if h is None:
+            return httpx.Response(404, json={"error": {"code": "NOT_FOUND", "message": "no route", "requestId": "r0"}})
+        return h(req)
+
+    @property
+    def last(self) -> httpx.Request:
+        return self.requests[-1]
+
+    def last_json(self) -> Any:
+        return json.loads(self.last.content)
+
+
+@pytest.fixture
+def api() -> FakeApi:
+    return FakeApi()
+
+
+@pytest.fixture
+def anyio_backend() -> str:
+    return "asyncio"
+
+
+QUOTE = {
+    "quoteId": "q_1", "provider": "relay", "dstAmount": "612345678", "dstAmountMin": "609283949",
+    "estimatedSeconds": 8, "fees": {"ourFeeBps": 20}, "expiresAt": 1760000030,
+}
+QUOTE_RESPONSE = {"best": QUOTE, "quotes": [QUOTE], "errors": []}
+EVM_TX = {"vm": "evm", "chainId": 8453, "to": "0xabc", "data": "0x12", "value": "0",
+          "approval": {"token": "0xusdc", "spender": "0xabc", "amount": "100000000"}}

layerhop-0.1.0/tests/test_client.py

@@ -0,0 +1,174 @@
+import httpx
+import pytest
+
+from layerhop import AsyncLayerHop, LayerHop, LayerHopApiError
+from layerhop import client as client_mod
+
+from .conftest import EVM_TX, QUOTE_RESPONSE, FakeApi
+
+
+def make(api: FakeApi, **kw) -> LayerHop:
+    return LayerHop(base_url="http://test/", transport=httpx.MockTransport(api), **kw)
+
+
+def amake(api: FakeApi, **kw) -> AsyncLayerHop:
+    return AsyncLayerHop(base_url="http://test", transport=httpx.MockTransport(api), **kw)
+
+
+def test_default_base_url():
+    assert LayerHop().base_url == "https://api.layerhop.com"
+
+
+def test_health_chains_tokens(api):
+    api.on("GET", "/v1/health", {"ok": True, "providers": ["relay"]})
+    api.on("GET", "/v1/chains", {"chains": [{"id": 8453, "slug": "base"}]})
+    api.on("GET", "/v1/tokens", {"tokens": [{"chainId": 8453, "symbol": "USDC"}]})
+    lh = make(api)
+    assert lh.health()["ok"] is True
+    assert lh.chains()[0]["slug"] == "base"
+    assert lh.tokens("base")[0]["symbol"] == "USDC"
+    assert api.last.url.params["chain"] == "base"
+
+
+def test_quote_query_and_api_key(api):
+    api.on("GET", "/v1/quote", QUOTE_RESPONSE)
+    lh = make(api, api_key="lh_live_x", integrator="myapp", integrator_fee_bps=25)
+    r = lh.quote("base", "USDC", "100000000", "solana", "SOL", sender="0xs", recipient="9W")
+    assert r["best"]["quoteId"] == "q_1"
+    p = api.last.url.params
+    assert dict(p) == {
+        "srcChain": "base", "srcToken": "USDC", "amount": "100000000", "dstChain": "solana", "dstToken": "SOL",
+        "sender": "0xs", "recipient": "9W", "slippageBps": "50", "channel": "api",
+        "integrator": "myapp", "integratorFeeBps": "25",
+    }
+    assert api.last.headers["x-api-key"] == "lh_live_x"
+
+
+def test_quote_rejects_non_string_amount(api):
+    with pytest.raises(TypeError):
+        make(api).quote("base", "USDC", 100, "solana", "SOL", sender="a", recipient="b")  # type: ignore[arg-type]
+
+
+def test_quote_without_key_has_no_header(api):
+    api.on("GET", "/v1/quote", QUOTE_RESPONSE)
+    make(api, channel="widget").quote(8453, "USDC", "1", 7565164, "SOL", sender="a", recipient="b", slippage_bps=100)
+    assert "x-api-key" not in api.last.headers
+    assert api.last.url.params["channel"] == "widget"
+    assert api.last.url.params["slippageBps"] == "100"
+    assert api.last.url.params["srcChain"] == "8453"
+
+
+def test_build_tx_submit_report_simulate(api):
+    api.on("POST", "/v1/orders", {"quoteId": "q_1", "provider": "relay", "tx": EVM_TX})
+    api.on("POST", "/v1/orders/submit", {"provider": "jupiter", "txHash": "sig"})
+    api.on("POST", "/v1/orders/q_1/submitted", {"quoteId": "q_1", "status": "submitted"})
+    api.on("POST", "/v1/simulate", {"ok": True, "vm": "evm", "gasEstimate": "21000", "tx": EVM_TX})
+    lh = make(api)
+    tx = lh.build_tx("q_1")
+    assert tx["vm"] == "evm" and tx["approval"]["amount"] == "100000000"
+    assert api.last_json() == {"quoteId": "q_1"}
+    assert lh.submit("q_1", "AAAA") == "sig"
+    assert api.last_json() == {"quoteId": "q_1", "signedTransaction": "AAAA"}
+    assert lh.report_submitted("q_1", "0xhash") == {"quoteId": "q_1", "status": "submitted"}
+    assert api.last_json() == {"txHash": "0xhash"}
+    sim = lh.simulate("q_1")
+    assert sim["ok"] and sim["gasEstimate"] == "21000"
+    assert api.last_json() == {"quoteId": "q_1"}
+
+
+def test_status_encodes_id(api):
+    api.on("GET", "/v1/orders/relay/a%2Fb", {"provider": "relay", "id": "a/b", "state": "pending"})
+    assert make(api).status("relay", "a/b")["state"] == "pending"
+
+
+def test_list_orders(api):
+    api.on("GET", "/v1/orders", {"orders": [{"quoteId": "q_1", "status": "filled", "extra": 1}], "nextCursor": "c2"})
+    page = make(api).list_orders(address="0xs", status="filled", limit=10)
+    assert page["nextCursor"] == "c2" and page["orders"][0]["extra"] == 1
+    assert dict(api.last.url.params) == {"address": "0xs", "status": "filled", "limit": "10"}
+    make(api).list_orders()
+    assert dict(api.last.url.params) == {}
+
+
+def test_api_error(api):
+    api.on("POST", "/v1/orders", {"error": {"code": "QUOTE_EXPIRED", "message": "Quote expired", "requestId": "rid",
+                                            "docsUrl": "https://docs.layerhop.com/errors/QUOTE_EXPIRED"}}, status=410)
+    with pytest.raises(LayerHopApiError) as ei:
+        make(api).build_tx("q_old")
+    e = ei.value
+    assert (e.code, e.status, e.request_id, e.message) == ("QUOTE_EXPIRED", 410, "rid", "Quote expired")
+    assert "QUOTE_EXPIRED" in str(e)
+
+
+def test_api_error_without_body(api):
+    api.on("GET", "/v1/health", handler=lambda req: httpx.Response(502, text="bad gateway", headers={"x-request-id": "h1"}))
+    with pytest.raises(LayerHopApiError) as ei:
+        make(api).health()
+    assert ei.value.code == "INTERNAL" and ei.value.status == 502 and ei.value.request_id == "h1"
+
+
+def _sequence(states):
+    it = iter(states)
+
+    def handler(req):
+        s = next(it)
+        return httpx.Response(200, json={"provider": "relay", "id": "0xh", "state": s})
+    return handler
+
+
+def test_watch_yields_changes_until_final(api, monkeypatch):
+    monkeypatch.setattr(client_mod.time, "sleep", lambda _s: None)
+    api.on("GET", "/v1/orders/relay/0xh", handler=_sequence(["unknown", "pending", "pending", "filled", "pending"]))
+    states = [s["state"] for s in make(api).watch("relay", "0xh", interval=0)]
+    assert states == ["unknown", "pending", "filled"]
+    assert len(api.requests) == 4
+
+
+def test_watch_timeout(api, monkeypatch):
+    monkeypatch.setattr(client_mod.time, "sleep", lambda _s: None)
+    api.on("GET", "/v1/orders/relay/0xh", {"provider": "relay", "id": "0xh", "state": "pending"})
+    assert [s["state"] for s in make(api).watch("relay", "0xh", timeout=0)] == []
+
+
+def test_context_manager(api):
+    api.on("GET", "/v1/health", {"ok": True})
+    with make(api) as lh:
+        assert lh.health()["ok"]
+
+
+@pytest.mark.anyio
+async def test_async_client(api):
+    api.on("GET", "/v1/chains", {"chains": [{"id": 1}]})
+    api.on("GET", "/v1/tokens", {"tokens": []})
+    api.on("GET", "/v1/health", {"ok": True})
+    api.on("GET", "/v1/quote", QUOTE_RESPONSE)
+    api.on("POST", "/v1/orders", {"tx": EVM_TX})
+    api.on("POST", "/v1/orders/submit", {"txHash": "sig"})
+    api.on("POST", "/v1/orders/q_1/submitted", {"quoteId": "q_1", "status": "submitted"})
+    api.on("POST", "/v1/simulate", {"ok": False, "vm": "evm", "error": {"code": "SIMULATION_FAILED", "message": "revert"}, "tx": EVM_TX})
+    api.on("GET", "/v1/orders", {"orders": []})
+    async with amake(api, api_key="k") as lh:
+        assert (await lh.health())["ok"]
+        assert (await lh.chains())[0]["id"] == 1
+        assert await lh.tokens(1) == []
+        q = await lh.quote("base", "USDC", "1", "solana", "SOL", sender="a", recipient="b")
+        assert q["best"]["provider"] == "relay"
+        assert api.last.headers["x-api-key"] == "k"
+        assert (await lh.build_tx("q_1"))["vm"] == "evm"
+        assert await lh.submit("q_1", "AA") == "sig"
+        assert (await lh.report_submitted("q_1", "0xh"))["status"] == "submitted"
+        assert (await lh.simulate("q_1"))["error"]["message"] == "revert"
+        assert (await lh.list_orders(address="a"))["orders"] == []
+
+
+@pytest.mark.anyio
+async def test_async_error_and_watch(api):
+    api.on("GET", "/v1/quote", {"error": {"code": "NO_ROUTE", "message": "none", "requestId": "x"}}, status=404)
+    api.on("GET", "/v1/orders/debridge/0xh", handler=_sequence(["pending", "refunded"]))
+    lh = amake(api)
+    with pytest.raises(LayerHopApiError) as ei:
+        await lh.quote("base", "USDC", "1", "solana", "SOL", sender="a", recipient="b")
+    assert ei.value.code == "NO_ROUTE"
+    states = [s["state"] async for s in lh.watch("debridge", "0xh", interval=0)]
+    assert states == ["pending", "refunded"]
+    await lh.aclose()

layerhop-0.1.0/tests/test_webhooks.py

@@ -0,0 +1,52 @@
+import hashlib
+import hmac
+import json
+
+import pytest
+
+from layerhop import WebhookSignatureError, compute_webhook_signature, construct_webhook_event, verify_webhook_signature
+
+SECRET = "whsec_test"
+BODY = json.dumps({"id": "evt_1", "type": "order.filled", "createdAt": "2026-10-17T00:00:00Z", "data": {"order": {}}})
+T = 1760000000
+
+
+def sign(body=BODY, t=T, secret=SECRET):
+    return hmac.new(secret.encode(), f"{t}.{body}".encode(), hashlib.sha256).hexdigest()
+
+
+def test_valid_signature_str_and_bytes():
+    h = f"t={T},v1={sign()}"
+    assert verify_webhook_signature(SECRET, BODY, h, now=T)
+    assert verify_webhook_signature(SECRET.encode(), BODY.encode(), h, now=T + 299)
+    assert compute_webhook_signature(SECRET, T, BODY) == sign()
+
+
+def test_rejects_tampered_body_wrong_secret_and_garbage():
+    h = f"t={T},v1={sign()}"
+    assert not verify_webhook_signature(SECRET, BODY + " ", h, now=T)
+    assert not verify_webhook_signature("other", BODY, h, now=T)
+    assert not verify_webhook_signature(SECRET, BODY, None, now=T)
+    assert not verify_webhook_signature(SECRET, BODY, "", now=T)
+    assert not verify_webhook_signature(SECRET, BODY, f"t={T}", now=T)
+    assert not verify_webhook_signature(SECRET, BODY, f"v1={sign()}", now=T)
+    assert not verify_webhook_signature(SECRET, BODY, f"t=abc,v1={sign()}", now=T)
+
+
+def test_tolerance():
+    h = f"t={T},v1={sign()}"
+    assert not verify_webhook_signature(SECRET, BODY, h, now=T + 301)
+    assert not verify_webhook_signature(SECRET, BODY, h, now=T - 301)
+    assert verify_webhook_signature(SECRET, BODY, h, now=T + 600, tolerance=600)
+
+
+def test_multiple_v1_values_any_matches():
+    h = f"t={T}, v1=deadbeef, v1={sign()}"
+    assert verify_webhook_signature(SECRET, BODY, h, now=T)
+
+
+def test_construct_event():
+    ev = construct_webhook_event(SECRET, BODY, f"t={T},v1={sign()}", now=T)
+    assert ev["type"] == "order.filled"
+    with pytest.raises(WebhookSignatureError):
+        construct_webhook_event(SECRET, BODY, f"t={T},v1=00", now=T)