biatec-router 1.0.0__tar.gz

biatec_router-1.0.0/.gitignore

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

biatec_router-1.0.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: biatec-router
+Version: 1.0.0
+Summary: Python client for Biatec Router, a DEX aggregator API for the Algorand blockchain
+Project-URL: Homepage, https://github.com/scholtz/BiatecRouter
+Project-URL: Documentation, https://router.biatec.io/developers
+Project-URL: Repository, https://github.com/scholtz/BiatecRouter
+Project-URL: Issues, https://github.com/scholtz/BiatecRouter/issues
+Author-email: Biatec <scholtzandcojsa@gmail.com>
+License-Expression: MIT
+Keywords: aggregator,algorand,amm,biatec,dex,swap
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: py-algorand-sdk>=2.6.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: responses>=0.25.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# biatec-router (Python)
+
+Python client for [Biatec Router](https://github.com/scholtz/BiatecRouter), a DEX aggregator API for the Algorand blockchain.
+
+At the time of writing it is the most efficient DEX aggregator on Algorand as it routes trades across Pact.Fi, Tinyman **and** Biatec DEX - the first concentrated-liquidity AMM on Algorand, which other aggregators don't support.
+
+This mirrors the [`biatec-router` npm package](https://www.npmjs.com/package/biatec-router) for Python developers: a thin HTTP client plus an ARC-14 authentication helper. It does not sign or submit transactions for you - you decode, sign and send the transaction group with [`py-algorand-sdk`](https://pypi.org/project/py-algorand-sdk/) as shown below.
+
+## Install
+
+```bash
+pip install biatec-router
+```
+
+## Authentication
+
+Every endpoint requires an `Authorization` header carrying a signed [ARC-0014](https://arc.algorand.foundation/ARCs/arc-0014) transaction for the realm `BiatecRouter#ARC14`. The transaction is a zero-amount payment with the realm in the note field - it is never submitted to the network, it only proves control of an Algorand account.
+
+```python
+from algosdk.v2client import algod
+from biatec_router import build_auth_header, RouterClient
+
+algod_client = algod.AlgodClient("", "https://mainnet-api.4160.nodely.dev")
+suggested_params = algod_client.suggested_params()
+
+# private_key from mnemonic.to_private_key(...), ARC-76, or however you manage keys
+auth_header = build_auth_header(private_key, suggested_params)
+
+router = RouterClient(
+    base_url="https://router.api.biatec.io",  # or https://testnet.router.api.biatec.io
+    auth_header=auth_header,
+)
+```
+
+## Request a quote
+
+```python
+output_amount = router.quote(from_asset=0, to_asset=31566704, amount=5_000_000)
+print(output_amount)  # estimated USDC (base units) for 5 ALGO
+
+routes = router.route(from_asset=0, to_asset=31566704, amount=5_000_000, max_routes=1)
+print(routes)
+```
+
+## Execute a swap
+
+**Always set `receive_minimum` when executing to protect your funds. Never use `0` outside of a preview.**
+
+```python
+import algosdk
+from algosdk import transaction
+
+response = router.route_txs(
+    sender=account_address,
+    from_asset=0,
+    to_asset=31566704,
+    swap_amount=5_000_000,
+    receive_minimum=4_900_000,
+    routes_count=1,
+    max_hops=3,
+)
+
+route = response["routes"][0]
+if not route.get("txsToSign"):
+    raise RuntimeError("No transactions to sign in the route.")
+
+# Decode, group and sign
+txns = [algosdk.encoding.msgpack_decode(b64) for b64 in route["txsToSign"]]
+group_id = transaction.calculate_group_id(txns)
+for txn in txns:
+    txn.group = group_id
+
+signed = [txn.sign(private_key) for txn in txns]
+txid = algod_client.send_transactions(signed)
+algosdk.transaction.wait_for_confirmation(algod_client, txid, 4)
+```
+
+## API
+
+- `RouterClient(base_url=..., auth_header=..., timeout=30.0)`
+  - `.quote(from_asset, to_asset, amount) -> int`
+  - `.route(from_asset, to_asset, amount, max_routes=1) -> list[dict]`
+  - `.route_txs(sender, from_asset, to_asset, swap_amount, receive_minimum, routes_count=1, max_hops=3) -> dict`
+  - `.stats() -> dict`
+  - `.snapshot() -> dict`
+  - Raises `biatec_router.RouterApiError` (with `.status_code` / `.body`) on non-2xx responses.
+- `build_auth_header(private_key, suggested_params, realm="BiatecRouter#ARC14", sender=None) -> str`
+- `make_arc14_transaction(sender, suggested_params, realm="BiatecRouter#ARC14")` / `make_arc14_auth_header(signed_txn)` - lower-level building blocks if you sign with something other than a raw private key (e.g. a wallet or `AccountTransactionSigner`).
+
+## Development
+
+```bash
+cd python
+pip install -e ".[dev]"
+pytest
+```
+
+See [`docs/PYPI_CICD.md`](../docs/PYPI_CICD.md) in the repository root for how releases are published to PyPI.

biatec_router-1.0.0/README.md

@@ -0,0 +1,98 @@
+# biatec-router (Python)
+
+Python client for [Biatec Router](https://github.com/scholtz/BiatecRouter), a DEX aggregator API for the Algorand blockchain.
+
+At the time of writing it is the most efficient DEX aggregator on Algorand as it routes trades across Pact.Fi, Tinyman **and** Biatec DEX - the first concentrated-liquidity AMM on Algorand, which other aggregators don't support.
+
+This mirrors the [`biatec-router` npm package](https://www.npmjs.com/package/biatec-router) for Python developers: a thin HTTP client plus an ARC-14 authentication helper. It does not sign or submit transactions for you - you decode, sign and send the transaction group with [`py-algorand-sdk`](https://pypi.org/project/py-algorand-sdk/) as shown below.
+
+## Install
+
+```bash
+pip install biatec-router
+```
+
+## Authentication
+
+Every endpoint requires an `Authorization` header carrying a signed [ARC-0014](https://arc.algorand.foundation/ARCs/arc-0014) transaction for the realm `BiatecRouter#ARC14`. The transaction is a zero-amount payment with the realm in the note field - it is never submitted to the network, it only proves control of an Algorand account.
+
+```python
+from algosdk.v2client import algod
+from biatec_router import build_auth_header, RouterClient
+
+algod_client = algod.AlgodClient("", "https://mainnet-api.4160.nodely.dev")
+suggested_params = algod_client.suggested_params()
+
+# private_key from mnemonic.to_private_key(...), ARC-76, or however you manage keys
+auth_header = build_auth_header(private_key, suggested_params)
+
+router = RouterClient(
+    base_url="https://router.api.biatec.io",  # or https://testnet.router.api.biatec.io
+    auth_header=auth_header,
+)
+```
+
+## Request a quote
+
+```python
+output_amount = router.quote(from_asset=0, to_asset=31566704, amount=5_000_000)
+print(output_amount)  # estimated USDC (base units) for 5 ALGO
+
+routes = router.route(from_asset=0, to_asset=31566704, amount=5_000_000, max_routes=1)
+print(routes)
+```
+
+## Execute a swap
+
+**Always set `receive_minimum` when executing to protect your funds. Never use `0` outside of a preview.**
+
+```python
+import algosdk
+from algosdk import transaction
+
+response = router.route_txs(
+    sender=account_address,
+    from_asset=0,
+    to_asset=31566704,
+    swap_amount=5_000_000,
+    receive_minimum=4_900_000,
+    routes_count=1,
+    max_hops=3,
+)
+
+route = response["routes"][0]
+if not route.get("txsToSign"):
+    raise RuntimeError("No transactions to sign in the route.")
+
+# Decode, group and sign
+txns = [algosdk.encoding.msgpack_decode(b64) for b64 in route["txsToSign"]]
+group_id = transaction.calculate_group_id(txns)
+for txn in txns:
+    txn.group = group_id
+
+signed = [txn.sign(private_key) for txn in txns]
+txid = algod_client.send_transactions(signed)
+algosdk.transaction.wait_for_confirmation(algod_client, txid, 4)
+```
+
+## API
+
+- `RouterClient(base_url=..., auth_header=..., timeout=30.0)`
+  - `.quote(from_asset, to_asset, amount) -> int`
+  - `.route(from_asset, to_asset, amount, max_routes=1) -> list[dict]`
+  - `.route_txs(sender, from_asset, to_asset, swap_amount, receive_minimum, routes_count=1, max_hops=3) -> dict`
+  - `.stats() -> dict`
+  - `.snapshot() -> dict`
+  - Raises `biatec_router.RouterApiError` (with `.status_code` / `.body`) on non-2xx responses.
+- `build_auth_header(private_key, suggested_params, realm="BiatecRouter#ARC14", sender=None) -> str`
+- `make_arc14_transaction(sender, suggested_params, realm="BiatecRouter#ARC14")` / `make_arc14_auth_header(signed_txn)` - lower-level building blocks if you sign with something other than a raw private key (e.g. a wallet or `AccountTransactionSigner`).
+
+## Development
+
+```bash
+cd python
+pip install -e ".[dev]"
+pytest
+```
+
+See [`docs/PYPI_CICD.md`](../docs/PYPI_CICD.md) in the repository root for how releases are published to PyPI.

biatec_router-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "biatec-router"
+version = "1.0.0"
+description = "Python client for Biatec Router, a DEX aggregator API for the Algorand blockchain"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Biatec", email = "scholtzandcojsa@gmail.com" }]
+keywords = ["algorand", "dex", "aggregator", "swap", "biatec", "amm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "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",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["py-algorand-sdk>=2.6.0", "requests>=2.31.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0", "responses>=0.25.0", "build>=1.2.0", "twine>=5.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/scholtz/BiatecRouter"
+Documentation = "https://router.biatec.io/developers"
+Repository = "https://github.com/scholtz/BiatecRouter"
+Issues = "https://github.com/scholtz/BiatecRouter/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/biatec_router"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

biatec_router-1.0.0/src/biatec_router/__init__.py

@@ -0,0 +1,16 @@
+"""Biatec Router - Python client for the Algorand DEX aggregator API."""
+
+from .auth import ARC14_REALM, build_auth_header, make_arc14_auth_header, make_arc14_transaction
+from .client import DEFAULT_BASE_URL, RouterApiError, RouterClient
+
+__all__ = [
+    "ARC14_REALM",
+    "build_auth_header",
+    "make_arc14_auth_header",
+    "make_arc14_transaction",
+    "DEFAULT_BASE_URL",
+    "RouterApiError",
+    "RouterClient",
+]
+
+__version__ = "1.0.0"

biatec_router-1.0.0/src/biatec_router/auth.py

@@ -0,0 +1,62 @@
+"""ARC-14 authentication helpers.
+
+Biatec Router requires every request to carry an ``Authorization`` header
+built from a signed, never-submitted, zero-amount Algorand payment
+transaction whose note field is the realm string (ARC-0014). This module
+builds that transaction and the resulting header.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from algosdk import encoding
+from algosdk.transaction import PaymentTxn, SuggestedParams
+from algosdk.account import address_from_private_key
+
+#: Realm Biatec Router accepts. ``BiatecScan#ARC14`` and ``BiatecDEX#ARC14``
+#: are also accepted by the API but this is the canonical one for the router.
+ARC14_REALM = "BiatecRouter#ARC14"
+
+
+def make_arc14_transaction(
+    sender: str,
+    suggested_params: SuggestedParams,
+    realm: str = ARC14_REALM,
+) -> PaymentTxn:
+    """Build the (unsigned) zero-amount ARC-14 auth transaction for ``sender``.
+
+    The transaction is never sent to the network - it only proves control of
+    the Algorand account and carries the realm in its note field.
+    """
+    return PaymentTxn(
+        sender=sender,
+        sp=suggested_params,
+        receiver=sender,
+        amt=0,
+        note=realm.encode("utf-8"),
+    )
+
+
+def make_arc14_auth_header(signed_txn) -> str:
+    """Encode a signed ARC-14 transaction as the ``Authorization`` header value."""
+    return "SigTx " + encoding.msgpack_encode(signed_txn)
+
+
+def build_auth_header(
+    private_key: str,
+    suggested_params: SuggestedParams,
+    realm: str = ARC14_REALM,
+    sender: Optional[str] = None,
+) -> str:
+    """Sign the ARC-14 transaction with ``private_key`` and return the header value.
+
+    Convenience wrapper around :func:`make_arc14_transaction` and
+    :func:`make_arc14_auth_header` for the common case of holding the
+    account's private key directly (e.g. from ``algosdk.mnemonic.to_private_key``
+    or an ARC-76 derived key).
+    """
+    addr = sender or address_from_private_key(private_key)
+    txn = make_arc14_transaction(addr, suggested_params, realm)
+    signed = txn.sign(private_key)
+    return make_arc14_auth_header(signed)

biatec_router-1.0.0/src/biatec_router/client.py

@@ -0,0 +1,137 @@
+"""HTTP client for the Biatec Router REST API."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import requests
+
+DEFAULT_BASE_URL = "https://router.api.biatec.io"
+
+
+class RouterApiError(Exception):
+    """Raised when the Biatec Router API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, body: Any):
+        self.status_code = status_code
+        self.body = body
+        super().__init__(f"Biatec Router API error {status_code}: {body}")
+
+
+class RouterClient:
+    """Thin wrapper around the Biatec Router HTTP API.
+
+    Parameters
+    ----------
+    base_url:
+        Router instance to call. Defaults to the mainnet production API.
+        Use ``https://testnet.router.api.biatec.io`` for testnet.
+    auth_header:
+        Value of the ``Authorization`` header (``"SigTx <...>"``), typically
+        produced by :func:`biatec_router.auth.build_auth_header`. Can also be
+        set later via :attr:`auth_header` if the signed transaction is only
+        available after construction.
+    timeout:
+        Per-request timeout in seconds.
+    session:
+        Optional pre-configured :class:`requests.Session` to reuse connection
+        pooling across multiple clients.
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        auth_header: Optional[str] = None,
+        timeout: float = 30.0,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.auth_header = auth_header
+        self.timeout = timeout
+        self._session = session or requests.Session()
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {"Accept": "application/json"}
+        if self.auth_header:
+            headers["Authorization"] = self.auth_header
+        return headers
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        response = self._session.request(
+            method,
+            f"{self.base_url}{path}",
+            headers=self._headers(),
+            timeout=self.timeout,
+            **kwargs,
+        )
+        if not response.ok:
+            try:
+                body: Any = response.json()
+            except ValueError:
+                body = response.text
+            raise RouterApiError(response.status_code, body)
+        if not response.content:
+            return None
+        return response.json()
+
+    def quote(self, from_asset: int, to_asset: int, amount: int) -> int:
+        """Best output amount (base units) for swapping ``amount`` of ``from_asset``."""
+        return self._request(
+            "GET",
+            "/api/v1/router/quote",
+            params={"fromAsset": from_asset, "toAsset": to_asset, "amount": amount},
+        )
+
+    def route(
+        self,
+        from_asset: int,
+        to_asset: int,
+        amount: int,
+        max_routes: int = 1,
+    ) -> List[Dict[str, Any]]:
+        """Detailed route(s) including hops, pool splits and network fee."""
+        return self._request(
+            "GET",
+            "/api/v1/router/route",
+            params={
+                "fromAsset": from_asset,
+                "toAsset": to_asset,
+                "amount": amount,
+                "maxRoutes": max_routes,
+            },
+        )
+
+    def route_txs(
+        self,
+        sender: str,
+        from_asset: int,
+        to_asset: int,
+        swap_amount: int,
+        receive_minimum: int,
+        routes_count: int = 1,
+        max_hops: int = 3,
+    ) -> Dict[str, Any]:
+        """Best route plus unsigned transactions built for ``sender``, ready to sign.
+
+        ``receive_minimum`` is enforced on-chain and should always reflect
+        your slippage tolerance - never call this with ``0`` outside of a
+        preview, since that disables slippage protection.
+        """
+        body = {
+            "sender": sender,
+            "fromAsset": from_asset,
+            "toAsset": to_asset,
+            "swapAmount": swap_amount,
+            "receiveMinimum": receive_minimum,
+            "routesCount": routes_count,
+            "maxHops": max_hops,
+        }
+        return self._request("POST", "/api/v1/router/routeTxs", json=body)
+
+    def stats(self) -> Dict[str, Any]:
+        """Live instance statistics: pools indexed, request counters, uptime."""
+        return self._request("GET", "/api/v1/router/stats")
+
+    def snapshot(self) -> Dict[str, Any]:
+        """Export of all pools and aggregated pools currently held in memory."""
+        return self._request("GET", "/api/v1/router/snapshot")

biatec_router-1.0.0/tests/test_auth.py

@@ -0,0 +1,36 @@
+from algosdk.account import generate_account
+from algosdk.transaction import SuggestedParams
+
+from biatec_router.auth import ARC14_REALM, build_auth_header, make_arc14_transaction
+
+GENESIS_HASH = "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="
+
+
+def _suggested_params() -> SuggestedParams:
+    return SuggestedParams(fee=0, first=1, last=1000, gh=GENESIS_HASH, flat_fee=True)
+
+
+def test_make_arc14_transaction_is_zero_amount_with_realm_note():
+    _, addr = generate_account()
+    txn = make_arc14_transaction(addr, _suggested_params())
+
+    assert txn.sender == addr
+    assert txn.receiver == addr
+    assert txn.amt == 0
+    assert txn.note == ARC14_REALM.encode("utf-8")
+
+
+def test_build_auth_header_has_sigtx_prefix():
+    sk, addr = generate_account()
+    header = build_auth_header(sk, _suggested_params(), sender=addr)
+
+    assert header.startswith("SigTx ")
+    assert len(header) > len("SigTx ")
+
+
+def test_build_auth_header_derives_sender_from_private_key():
+    sk, addr = generate_account()
+    header_explicit = build_auth_header(sk, _suggested_params(), sender=addr)
+    header_derived = build_auth_header(sk, _suggested_params())
+
+    assert header_explicit == header_derived

biatec_router-1.0.0/tests/test_client.py

@@ -0,0 +1,73 @@
+import pytest
+import responses
+
+from biatec_router.client import RouterApiError, RouterClient
+
+BASE_URL = "https://testnet.router.api.biatec.io"
+
+
+@pytest.fixture
+def client() -> RouterClient:
+    return RouterClient(base_url=BASE_URL, auth_header="SigTx abc123")
+
+
+@responses.activate
+def test_quote_sends_auth_header_and_query_params(client: RouterClient):
+    responses.add(
+        responses.GET,
+        f"{BASE_URL}/api/v1/router/quote",
+        json=4987120,
+        status=200,
+    )
+
+    result = client.quote(from_asset=0, to_asset=31566704, amount=5_000_000)
+
+    assert result == 4987120
+    sent = responses.calls[0].request
+    assert sent.headers["Authorization"] == "SigTx abc123"
+    assert "fromAsset=0" in sent.url
+    assert "toAsset=31566704" in sent.url
+    assert "amount=5000000" in sent.url
+
+
+@responses.activate
+def test_route_txs_posts_json_body(client: RouterClient):
+    responses.add(
+        responses.POST,
+        f"{BASE_URL}/api/v1/router/routeTxs",
+        json={"routes": [{"txsToSign": ["AAA"]}]},
+        status=200,
+    )
+
+    result = client.route_txs(
+        sender="SENDERADDRESS",
+        from_asset=0,
+        to_asset=31566704,
+        swap_amount=5_000_000,
+        receive_minimum=4_900_000,
+    )
+
+    assert result["routes"][0]["txsToSign"] == ["AAA"]
+    sent_body = responses.calls[0].request.body
+    assert b'"receiveMinimum": 4900000' in sent_body or b'"receiveMinimum":4900000' in sent_body
+
+
+@responses.activate
+def test_non_ok_response_raises_router_api_error(client: RouterClient):
+    responses.add(
+        responses.GET,
+        f"{BASE_URL}/api/v1/router/stats",
+        json={"error": "unauthorized"},
+        status=401,
+    )
+
+    with pytest.raises(RouterApiError) as excinfo:
+        client.stats()
+
+    assert excinfo.value.status_code == 401
+    assert excinfo.value.body == {"error": "unauthorized"}
+
+
+def test_base_url_trailing_slash_is_stripped():
+    client = RouterClient(base_url="https://router.api.biatec.io/")
+    assert client.base_url == "https://router.api.biatec.io"