# Almanak SDK

> Almanak SDK is an open-source Python framework for developing, testing, and deploying autonomous DeFi agents with an intent-based architecture.

## Installation

```
pip install almanak
```

Requires Python 3.12+.

## Key Concepts

- **Strategies**: Python classes that implement a `decide()` method returning a list of intents.
- **Intents**: High-level trading operations (Swap, LP, Borrow, etc.) that compile to optimized transactions.
- **Gateway**: Security architecture where strategy containers run with no secrets and no internet access. All external operations go through a controlled gRPC sidecar.
- **Backtesting**: PnL simulation, Monte Carlo analysis, parameter sweeps, and paper trading on Anvil forks.

## Example: Strategy Definition (Python)

class MyStrategy(Strategy):
    """Rebalancing strategy maintaining 50/50 allocation."""

    def configure(self):
        self.token_a = self.config["token_a"]
        self.token_b = self.config["token_b"]
        self.threshold = self.config["rebalance_threshold"]

    async def decide(self, state: StrategyState):
        prices = state.prices
        portfolio = state.portfolio

        ratio = portfolio.value(self.token_a) / portfolio.total_value()

        if abs(ratio - 0.5) > self.threshold:
            return [
                Swap(
                    from_token=self.token_a if ratio > 0.5 else self.token_b,
                    to_token=self.token_b if ratio > 0.5 else self.token_a,
                    amount_pct=abs(ratio - 0.5) * 100,
                )
            ]
        return []

## CLI Commands

- `almanak strat new` - Scaffold a new strategy from a template
- `almanak strat run --network anvil --once` - Run on a local Anvil fork
- `almanak strat run --dashboard` - Run with live monitoring dashboard
- `almanak strat backtest pnl` - Run PnL backtesting
- `almanak strat backtest montecarlo` - Run Monte Carlo analysis

## Supported Protocols & Chains

12 chains including Ethereum, Base, Avalanche, Arbitrum, BNB Smart Chain, and more.
20+ protocol connectors including Uniswap, Aave, Morpho, GMX, Polymarket, and more.

## Almanak Code

Terminal-based AI coding agent for developing and debugging strategies. Supports Claude, GPT-4, persistent sessions, and built-in tools.

## Links

- [SDK Documentation](https://docs.almanak.co)
- [Getting Started](https://docs.almanak.co/getting-started.html)
- [GitHub](https://github.com/almanak-co/sdk)
- [Platform](https://app.almanak.co)
- [Terms & Privacy Policy](https://almanak.co/tcpp-algo-theory-inc.pdf)

## Community

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

## Company

Almanak is built by Algo Theory INC.
Website: https://almanak.co