layerhop 0.1.0__py3-none-any.whl

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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+layerhop/__init__.py,sha256=8mHLoAk5DwER3gXGm2dmbea7-NazR84LCJUaoVY33XM,1508
+layerhop/client.py,sha256=WofTtkVGb0DhbsAcNCck8BxsLUg6qsPghxfdEo4BA0I,11730
+layerhop/errors.py,sha256=FGVXzcrBZEzoqPjVOC05me3aIOI8DABIaYX-G2vh6eg,975
+layerhop/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+layerhop/types.py,sha256=GOEF98kv2PzPMGhJJ8ee9FTn1sQUSx0S70VghLOXE_A,3334
+layerhop/webhooks.py,sha256=kVqJ3tEMjj64-XzrveUo60lxNtDPEGw7WEGOlj5DeUA,2823
+layerhop-0.1.0.dist-info/METADATA,sha256=O80vkAC-6jlVfNFi4TQE1BHVWy5uDpasXFdU7_LBNZg,6464
+layerhop-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+layerhop-0.1.0.dist-info/licenses/LICENSE,sha256=_J_y1GmXeNcSDq6I16y09E3ihiV7U6v9q2ECFYAYtXI,1065
+layerhop-0.1.0.dist-info/RECORD,,

layerhop-0.1.0.dist-info/WHEEL

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

layerhop-0.1.0.dist-info/licenses/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.