almanak 1.0.9
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
Requires Python: <3.12,>=3.11

# 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 that enables technical users to develop, test, and deploy autonomous agents for DeFi operations. Built on top of the Almanak Platform, it provides a comprehensive framework for creating sophisticated trading strategies and automated portfolio management solutions.

## Features

- **Agent-Based Modeling**: Realistic simulation of complex DeFi systems and market interactions
- **State Machine Architecture**: Robust framework for implementing complex trading strategies
- **Non-Custodial Design**: Full control over your funds through Safe smart accounts
- **Permissioned Execution**: Fine-grained access control through Zodiac Roles Modifier
- **Multi-Chain Support**: Currently supports Arbitrum and Base, with Ethereum integration coming soon
- **Protocol Integration**: Native support for Uniswap V3, with Aave V3 integration planned

## Installation

```bash
pip install almanak
```

## Quick Start

1. **Get Your API Key**
   - Login to [Almanak Platform](https://app.almanak.co/) with your Web3 wallet
   - Generate an API key from your User Profile
   - Save your API key securely - it cannot be displayed again

2. **Authenticate**

   ```bash
   almanak auth
   ```

3. **Download an Example Strategy**

   ```bash
   almanak strat example --strategy-name tutorial_uniswap_swap
   ```

4. **Test Your Strategy**

   ```bash
   cd tutorial_uniswap_swap
   almanak strat test
   ```

## Core Components

### Strategies

Strategies are Python applications that define automated decision-making logic for your DeFi operations. They:

- Operate as state machines for complex decision trees
- Run on Almanak's high-reliability infrastructure
- Maintain privacy through encryption
- Abstract away low-level blockchain interactions

### Agents

Agents are autonomous software applications that:

- Execute strategies on your behalf
- Interact with on-chain protocols through permissioned access
- Monitor market conditions and wallet states
- Handle transaction formation and execution

### Wallets

Almanak uses a secure wallet architecture:

- Non-custodial Safe smart accounts
- Zodiac Roles Modifier for permission management
- Encrypted Agent EOAs for transaction signing
- Full user control over funds

## Supported Features

### Actions

- Token transfers
- Token swaps
- Liquidity provision
- Position management
- Token approvals
- Wrapping/unwrapping ETH

### Networks

- Arbitrum
- Base
- Ethereum (coming soon)

### Protocols

- Uniswap V3
- Aave V3 (coming soon)

## Security

- All strategy code is encrypted at rest and in transit
- Agent EOA private keys are encrypted and never accessible to humans
- Fine-grained permission controls through Zodiac Roles Modifier
- Non-custodial design ensures users maintain full control of funds

## Documentation

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

## Support

- [Discord](https://discord.gg/c4jY28WrEB)
- [Telegram](https://t.me/+G1O9NFuz-AAzYmQy)
- [Twitter](https://x.com/Almanak__)