almanak 2.20.0

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

Almanak SDK

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

pipx install almanak

Optional features ship as extras:

pipx install 'almanak[dashboard,backtest]'   # web dashboard + backtest charts/optimization

Extra	Enables
dashboard	almanak dashboard and the strategy/backtest web dashboards (streamlit, plotly)
backtest	backtest chart export and almanak strat backtest optimize (matplotlib, plotly, optuna)
code	Python LSP for almanak code (pyright)

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

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)

   almanak strat new
   

2. Test on a Local Anvil Fork

   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:

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 to get started.

Documentation

For detailed documentation, visit sdk.docs.almanak.co

Support

• Discord
• Telegram
• Twitter