Metadata-Version: 2.4
Name: almanak
Version: 2.9.0
Summary: A powerful Python SDK for developing and deploying autonomous DeFi agents. Features agent-based modeling, state machine architecture, and non-custodial execution through Safe smart accounts
License-File: LICENSE
Author: engineering@almanak.co
Requires-Python: >=3.12
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Provides-Extra: dev
Requires-Dist: PyYAML (>=6.0.1)
Requires-Dist: aiohttp (>=3.11.11,<4.0.0)
Requires-Dist: asgi-lifespan (>=2.1.0) ; extra == "dev"
Requires-Dist: asyncpg (>=0.29.0)
Requires-Dist: click (>=8.1.8,<9.0.0)
Requires-Dist: eth-abi (>=5.0.0)
Requires-Dist: eth-account (>=0.10.0)
Requires-Dist: fastapi (>=0.128.0)
Requires-Dist: grpcio (>=1.76.0)
Requires-Dist: grpcio-health-checking (>=1.76.0)
Requires-Dist: grpcio-reflection (>=1.76.0)
Requires-Dist: grpcio-tools (>=1.76.0)
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: matplotlib (>=3.7.0)
Requires-Dist: md-click-2 (>=0.0.1,<0.0.2) ; extra == "dev"
Requires-Dist: mkdocs (>=1.6.1) ; extra == "dev"
Requires-Dist: mkdocs-llmstxt (>=0.5.0) ; extra == "dev"
Requires-Dist: mkdocs-material (>=9.7.0) ; extra == "dev"
Requires-Dist: mkdocs-static-i18n (>=1.2.0) ; extra == "dev"
Requires-Dist: mkdocstrings[python] (>=0.29.0) ; extra == "dev"
Requires-Dist: mypy (>=1.19.1,<2.0.0) ; extra == "dev"
Requires-Dist: mypy-protobuf (>=3.6.0) ; extra == "dev"
Requires-Dist: nest_asyncio (>=1.6.0)
Requires-Dist: optuna (>=3.5.0)
Requires-Dist: pandas (>=2.2.3,<4.0.0)
Requires-Dist: plotly (>=5.18.0)
Requires-Dist: prometheus-client (>=0.20.0)
Requires-Dist: pydantic (>=2.10.6,<3.0.0)
Requires-Dist: pydantic-settings (>=2.0.0)
Requires-Dist: pyright (>=1.1.390)
Requires-Dist: pytest (>=8.4.1) ; extra == "dev"
Requires-Dist: pytest-asyncio (>=0.25.0) ; extra == "dev"
Requires-Dist: pytest-cov (>=6.0) ; extra == "dev"
Requires-Dist: pytest-timeout (>=2.3.1) ; extra == "dev"
Requires-Dist: pytest-xdist (>=3.5.0) ; extra == "dev"
Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
Requires-Dist: python-kraken-sdk (>=3.2.7)
Requires-Dist: pytz (>=2023.4)
Requires-Dist: requests (>=2.32.3,<3.0.0)
Requires-Dist: retry (>=0.9.2,<0.10.0)
Requires-Dist: ruff (>=0.9.10,<0.15.0) ; extra == "dev"
Requires-Dist: setuptools (>=61) ; extra == "dev"
Requires-Dist: simple-term-menu (>=1.6.4,<2.0.0)
Requires-Dist: solders (>=0.21.0)
Requires-Dist: streamlit (>=1.44.1,<2.0.0)
Requires-Dist: structlog (>=24.1.0)
Requires-Dist: tqdm (>=4.66.0)
Requires-Dist: twine (>=6.1.0,<7.0.0) ; extra == "dev"
Requires-Dist: types-PyYAML (>=6.0.0) ; extra == "dev"
Requires-Dist: types-protobuf (>=5.0.0) ; extra == "dev"
Requires-Dist: types-pytz (>=2024.1.0) ; extra == "dev"
Requires-Dist: types-requests (>=2.32.0) ; extra == "dev"
Requires-Dist: types-retry (>=0.9.0) ; extra == "dev"
Requires-Dist: web3 (>=6.15.1,<8.0.0)
Requires-Dist: wheel (==0.46.3) ; extra == "dev"
Description-Content-Type: text/markdown

# Almanak SDK

[![PyPI version](https://badge.fury.io/py/almanak.svg)](https://badge.fury.io/py/almanak)

The Almanak SDK is a powerful Python library for developing, testing, and deploying autonomous DeFi agents. Built on an intent-based architecture, it provides a comprehensive framework for creating sophisticated trading strategies with minimal boilerplate.

## Features

- **Intent-Based Architecture**: Express trading logic as high-level intents (Swap, LP, Borrow, etc.) - the framework handles compilation and execution
- **Gateway Security**: All external access mediated through secure gRPC gateway
- **Three-Tier State Management**: Automatic persistence with HOT/WARM/COLD tiers
- **Comprehensive Backtesting**: PnL simulation, paper trading on Anvil forks, and parameter sweeps
- **Multi-Chain Support**: Ethereum, Arbitrum, Optimism, Base, Avalanche, Polygon, BSC, Sonic, Blast, Mantle, Berachain
- **Protocol Integration**: Uniswap V3, Aave V3, Morpho Blue, GMX V2, Lido, Ethena, Polymarket, Kraken, and more
- **Non-Custodial Design**: Full control over your funds through Safe smart accounts

## Installation

```bash
pipx install almanak
```

**Using an AI coding agent?** Teach it the SDK in one command:

```bash
almanak agent install
```

Auto-detects your platform (Claude Code, Codex, Cursor, Copilot, and 6 more) and installs the strategy builder skill.

## Quick Start

1. **Create a New Strategy** (scaffolds a self-contained Python project with `pyproject.toml`, `.venv/`, `uv.lock`)
   ```bash
   almanak strat new
   ```

2. **Test on a Local Anvil Fork**
   ```bash
   cd my_strategy
   uv run almanak strat run --network anvil --once
   ```

## Writing a Strategy

Strategies use an intent-based architecture. Implement the `decide()` method to return an intent:

```python
from almanak import IntentStrategy, SwapIntent, HoldIntent, MarketSnapshot

class MyStrategy(IntentStrategy):
    def decide(self, market: MarketSnapshot) -> Intent:
        eth_price = market.prices.get("ETH")
        usdc_balance = market.balances.get("USDC")

        if eth_price < 2000 and usdc_balance > 1000:
            return SwapIntent(
                token_in="USDC",
                token_out="ETH",
                amount=1000,
                slippage=0.005,
            )
        return HoldIntent(reason="Waiting for better conditions")
```

## Supported Networks

Ethereum, Arbitrum, Optimism, Base, Avalanche, Polygon, BSC, Sonic, Plasma, Blast, Mantle, Berachain

## Supported Protocols

- **DEXs**: Uniswap V3, SushiSwap V3, PancakeSwap V3, TraderJoe V2, Aerodrome, Curve, Balancer
- **Lending**: Aave V3, Morpho Blue, Compound V3, Spark
- **Liquid Staking**: Lido, Ethena
- **Yield**: Pendle
- **Perpetuals**: GMX V2, Hyperliquid
- **Prediction Markets**: Polymarket
- **CEX Integration**: Kraken
- **Aggregators**: Enso, LiFi

## Contributing

See the [Contributing Guide](https://github.com/almanak-co/almanak-sdk/blob/main/CONTRIBUTING.md) to get started.

## Documentation

For detailed documentation, visit [sdk.docs.almanak.co](https://sdk.docs.almanak.co/)

## Support

- [Discord](https://discord.gg/yuCMvQv3rN)
- [Telegram](https://t.me/AlmanakAgents)
- [Twitter](https://x.com/almanak)

