Metadata-Version: 2.4
Name: routon-sdk
Version: 0.1.0
Summary: Python SDK for Routon Protocol — the open execution layer for AI agents in DeFi.
Project-URL: Homepage, https://github.com/Dmitrze/routon-protocol/tree/main/sdk/python
Project-URL: Repository, https://github.com/Dmitrze/routon-protocol
Project-URL: Issues, https://github.com/Dmitrze/routon-protocol/issues
Author: Routon Protocol
License: MIT
Keywords: ai-agents,arbitrum,base,defi,erc-8004,ethereum,routon,yield
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: eth-abi<6.0.0,>=5.0.0
Requires-Dist: eth-account<1.0.0,>=0.13.0
Requires-Dist: eth-utils<7.0.0,>=5.0.0
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: jcs<0.3.0,>=0.2.1
Requires-Dist: pydantic<3.0.0,>=2.7.0
Requires-Dist: web3<8.0.0,>=7.0.0
Provides-Extra: dev
Requires-Dist: datamodel-code-generator<1.0.0,>=0.26.0; extra == 'dev'
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# routon-sdk (Python)

> Python SDK for [Routon Protocol](https://github.com/Dmitrze/routon-protocol) — the open execution layer for AI agents in DeFi.

[![PyPI](https://img.shields.io/pypi/v/routon-sdk.svg)](https://pypi.org/project/routon-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE-MIT.txt)

**Status:** v0.1.0 — first usable API. Schemas regenerated mechanically from the frozen [`agent-brain/openapi.json`](../../agent-brain/openapi.json) via `datamodel-codegen`. Four audit-grade parity helpers ship byte-equivalent with TypeScript (`@routon/sdk`) and Solidity (`contracts/src/`). Live integration tests against deployed brain land in PR-A.5 (Wave 2.5 follow-up).

## Install

```bash
uv add routon-sdk
# or
pip install routon-sdk
```

## Quickstart

```python
import asyncio
from routon import RoutonAgent, RoutonAgentConfig, Intent

async def main() -> None:
    cfg = RoutonAgentConfig(
        default_chain="base",
        builder_code="0x" + "ab" * 32,  # required for free-tier endpoints
    )
    async with RoutonAgent(cfg) as agent:
        intent = Intent(
            asset="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",  # USDC
            amount="10000000000",  # 10,000 USDC (6 decimals)
            userAddress="0xUSER...",
            builderCode="0x" + "ab" * 32,
            chain="base",
        )
        best = await agent.find_best(intent)
        print(best.id, best.expectedApy.total)

asyncio.run(main())
```

## Parity helpers (audit-grade)

Four byte-equivalent helpers mirror the on-chain + agent-brain implementations:

```python
from routon import (
    compute_strategy_id,           # 5-tuple keccak vs StrategyRegistry.sol:334
    compute_attestation_typehash,  # EIP-712 vs ValidationRegistry.sol:60-61
    canonical_factors_hash,        # RFC 8785 JCS via jcs library
    encode_execute_params,         # 9-field ExecuteParams vs PrimitiveExecutor.sol:36-46
    EXECUTE_SELECTOR,              # 0x918fafc5
    EXECUTE_BATCH_SELECTOR,        # 0x062f75e9
)

sid = compute_strategy_id(
    chain_id=8453,
    protocol="aave-v3",
    asset="0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    output_asset="0x4200000000000000000000000000000000000006",
    strategy_version="0.1",
)
```

Each helper has a pinned hex regression-gate test mirroring `agent-brain/tests/`. Drift on any anchor surfaces as **HIGH** — surface and HALT.

## What this SDK does

- Wraps the **Routon Brain** API (`brain.routon.xyz`) — 11 endpoints from `agent-brain/openapi.json`.
- Validates all input/output via Pydantic v2 schemas regenerated from the frozen OpenAPI 3.1 spec.
- Ships parity helpers for cross-language byte-equivalence with TypeScript (`canonicalize`) + Solidity (`cast`).
- Python 3.12+. Async-first (`asyncio` + `httpx`).
- Fully typed, `mypy --strict` clean, `py.typed` marker shipped.

## What it does **not** do

- Custody. Routon is non-custodial. The SDK never holds keys; calldata is returned for the caller to sign.
- Send transactions on your behalf. The caller signs and broadcasts via `web3.py` / wallet of choice.

## Build & test

```bash
uv sync --extra dev
uv run pytest                                 # 39 tests (9 smoke + 30 parity)
uv run mypy --strict routon
uv run ruff check
bash scripts/regen-schemas.sh                 # committed output; CI verifies stability
```

## Versioning

- `0.0.x` — placeholder + scaffolding (Wave 0).
- `0.1.x` — first usable API; tracks Routon Standard v0.1 (Wave 3, current).
- `1.0.0` — mainnet-ready, audited contracts deployed, schema frozen.

## License

MIT — see [`../../LICENSE-MIT.txt`](../../LICENSE-MIT.txt).
