Metadata-Version: 2.5
Name: biatec-router
Version: 1.0.1
Summary: Python client for Biatec Router, a DEX aggregator API for the Algorand blockchain
Project-URL: Homepage, https://router.biatec.io
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://router.biatec.io), 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.
