Installation | Quick Start | Strategies | Backtesting | Docs

English | 中文 | Français | Español

Almanak is an intent-based Python framework for developing, testing, and deploying autonomous DeFi strategies. Express trading logic as high-level intents - the framework handles compilation, execution, and state management across 12 chains and 20+ protocols.

• Intent-Based Architecture: Express trading logic as high-level intents (Swap, LP, Borrow, etc.) - the framework handles compilation and execution
• Three-Tier State Management: Automatic persistence with HOT/WARM/COLD tiers for reliability
• 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
• Agentic DeFAI Trading: Build autonomous LLM-driven agents with 29 built-in tools and policy-enforced safety (BYO LLM API key)
• Production-Ready: Built-in alerting, stuck detection, emergency management, and canary deployments

pipx install almanak

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

almanak agent install

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

1. Create a New Strategy (scaffolds a self-contained Python project with pyproject.toml, .venv/, uv.lock)

   almanak strat new

2. Test Your Strategy

   A managed gateway is auto-started in the background when you run a strategy. Use --dashboard to launch a live monitoring dashboard alongside execution:

   uv run almanak strat run -d strategies/demo/uniswap_lp --network anvil --dashboard --once

   This single command auto-starts Anvil + gateway, opens the dashboard in your browser, and runs one iteration of the strategy.

New here? Start with the uniswap_rsi demo strategy - a fully commented tutorial that walks through RSI-based trading on Uniswap V3.

Strategies implement the decide() method, which receives a MarketSnapshot and returns an Intent (or None to skip the cycle):

from decimal import Decimal
from almanak.framework.intents import Intent
from almanak.framework.strategies import IntentStrategy, MarketSnapshot

class MyStrategy(IntentStrategy):
    """A simple mean-reversion strategy."""

    def decide(self, market: MarketSnapshot) -> Intent | None:
        eth_price = market.price("ETH")
        usdc = market.balance("USDC")

        if eth_price < Decimal("2000") and usdc.balance_usd > Decimal("500"):
            return Intent.swap(
                from_token="USDC",
                to_token="ETH",
                amount_usd=Decimal("500"),
            )
        return Intent.hold(reason="Waiting for better conditions")

# Gateway (auto-started by strat run, or start standalone)
almanak gateway                # Start standalone gateway server
almanak gateway --network anvil  # Start standalone for local Anvil testing

# Direct DeFi actions (no strategy files needed)
almanak ax price ETH                           # Get token price
almanak ax balance USDC --chain base           # Check wallet balance
almanak ax swap USDC ETH 100 --dry-run         # Simulate a swap
almanak ax swap USDC ETH 100                   # Execute after confirmation
almanak ax -n "swap 5 USDC to WETH on base"   # Natural language mode

# Strategy development
almanak strat new              # Create new strategy from template
almanak strat run --once       # Run single iteration (auto-starts gateway)
almanak strat run --network anvil --once  # Run on local Anvil fork (auto-starts Anvil + gateway)
almanak strat run --network anvil --dashboard  # Run with live dashboard

# Backtesting
almanak strat backtest pnl     # Historical price simulation
almanak strat backtest sweep   # Parameter optimization
almanak strat backtest paper   # Paper trading on Anvil

# Advanced backtesting
almanak strat backtest monte-carlo  # Statistical robustness analysis
almanak strat backtest optimize     # Bayesian parameter optimization
almanak strat backtest scenario     # Crisis scenario stress testing
almanak strat backtest dashboard    # Interactive results dashboard

The SDK provides a dual-engine backtesting system for institutional-grade strategy validation:

from almanak.framework.backtesting import PnLBacktester, PnLBacktestConfig
from datetime import datetime, UTC
from decimal import Decimal

config = PnLBacktestConfig(
    start_time=datetime(2024, 1, 1, tzinfo=UTC),
    end_time=datetime(2024, 6, 1, tzinfo=UTC),
    initial_capital_usd=Decimal("10000"),
)

backtester = PnLBacktester(data_provider, fee_models, slippage_models)
result = await backtester.backtest(strategy, config)

print(f"Total Return: {result.metrics.total_return_pct:.2f}%")
print(f"Sharpe Ratio: {result.metrics.sharpe_ratio:.2f}")
print(f"Max Drawdown: {result.metrics.max_drawdown_pct:.2f}%")

# Historical PnL backtest
almanak strat backtest pnl -s my_strategy --start 2024-01-01 --end 2024-06-01

# Parameter sweep optimization
almanak strat backtest sweep -s my_strategy --param "window:10,20,30"

# Paper trading on Anvil fork
almanak strat backtest paper start -s my_strategy --chain arbitrum

# Monte Carlo simulation (1000 price paths)
almanak strat backtest monte-carlo -s my_strategy --n-paths 1000

# Crisis scenario stress testing
almanak strat backtest scenario -s my_strategy --scenario terra_collapse

Complete runnable examples are available in examples/:

python examples/backtest_ta_strategy.py      # RSI mean reversion
python examples/backtest_lp_strategy.py      # Concentrated LP
python examples/backtest_looping_strategy.py # Leveraged yield

For complete documentation, see almanak/framework/backtesting/README.md.

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

• 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

The SDK includes educational demo strategies to help you learn:

Run any demo with:

cd strategies/demo/<strategy_name>
uv run almanak strat run --once --dry-run

almanak/
  framework/           # V2 Strategy Framework
    strategies/        # IntentStrategy base class
    intents/           # Intent vocabulary & compiler
    state/             # Three-tier state management
    execution/         # Transaction orchestration
    backtesting/       # PnL, paper trading, sweeps
    connectors/        # Protocol adapters
    data/              # Price oracles, indicators
    alerting/          # Slack/Telegram notifications
    services/          # Stuck detection, emergency mgmt
  transaction_builder/ # Low-level tx building
  core/                # Enums, models, utilities
  cli/                 # Command-line interface

• 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

All strategies run through a gateway-only architecture for security:

• Gateway Sidecar: Holds all secrets (API keys, private keys), exposes controlled gRPC API
• Strategy Container: Runs user code with no secrets and no internet access

This ensures strategy code cannot access secrets directly - all external access is mediated through the gateway.

# Run your strategy (auto-starts gateway in background)
cd my_strategy
almanak strat run --once

# Or run a standalone gateway for shared use
almanak gateway

# For full container isolation (production-like)
docker-compose -f deploy/docker/docker-compose.yml up

For more details, visit docs.almanak.co.

Supercharge your strategy development with AI agent support. The Almanak strategy builder skill teaches AI coding agents (Claude Code, Codex, Cursor, Copilot, and others) how to write strategies using the SDK.

# Claude Code / Codex / any skills.sh-compatible agent
npx skills add almanak-co/almanak-sdk

# Or via the Almanak CLI (auto-detects your agent platform)
almanak agent install

Once installed, your agent understands the full intent vocabulary, market data API, backtesting tools, and CLI commands. Just describe what you want to build.

The SDK also supports LLM-driven autonomous agents. Instead of writing decide() logic, you write a system prompt and let the LLM reason over market data and call tools.

Requirements: Your own LLM API key (OpenAI, Anthropic, or any OpenAI-compatible provider).

# Smoke test with mock LLM (no API key needed)
python examples/agentic/agent_swap/run.py --once --mock

# Run with real LLM
AGENT_LLM_API_KEY=sk-... python examples/agentic/agent_swap/run.py --once

The almanak ax CLI also supports a natural language mode that uses the same LLM infrastructure for one-shot DeFi actions without writing strategy files:

AGENT_LLM_API_KEY=sk-... almanak ax -n "swap 5 USDC to WETH on base"
AGENT_LLM_API_KEY=sk-... almanak ax -n "what's the price of ETH?"

See Agentic Trading docs for the full guide, or browse the 4 working examples.

We welcome contributions. See CONTRIBUTING.md for development setup, coding standards, and the PR process.

• Code of Conduct
• Security Policy

For detailed documentation, visit docs.almanak.co

• Discord
• Telegram
• Twitter