almanak-strategy-builder

Files (1)

• SKILL.md

SKILL.md (first lines)

# Almanak Strategy Builder

You are helping a quant build DeFi strategies using the Almanak SDK.
Strategies are Python classes that return Intent objects. The framework handles
compilation to transactions, execution, and state management.

<!-- almanak-sdk-start: security-model -->

## Security Model

This file is **documentation for AI coding assistants** - it contains no executable code or live credentials.

The Almanak SDK uses a **gateway-isolated architecture**:
- Strategy containers have **no direct access** to secrets, RPC endpoints, or external APIs.
- All external access is mediated through a gRPC gateway sidecar.
- In production, secrets are injected by the platform secret manager into the gateway - never into the strategy container.
- The `.env` file referenced below is for **local development only** and is never deployed to production environments.
- Private keys in `.env` are used solely for local Anvil fork testing and have no access to mainnet funds in production.

See the [Gateway](#gateway) section for details.

<!-- almanak-sdk-end: security-model -->

**IMPORTANT — Zodiac permissions auto-generation**: Whenever you create a new
strategy or modify `strategy.py` in a way that changes protocols, intent types,
tokens, or chains, you MUST regenerate the Zodiac Roles permission manifest
by running `almanak strat permissions -o permissions.json`
from the strategy directory. The file MUST be named exactly `permissions.json`
— the platform deploy pipeline hardcodes this filename. This ensures the Safe
wallet permissions stay in sync with the strategy's actual contract interactions.
Always do this as a final step after writing or editing strategy code.

<!-- almanak-sdk-start: quick-start -->

## Quick Start

```bash
# Install the CLI globally
pipx install almanak

# Scaffold a new strategy (creates a self-contained Python project)
almanak strat new --template ta_swap --name my_rsi --chain arbitrum

# Run on local Anvil fork (auto-starts gateway + Anvil)
cd my_rsi
almanak strat run --network anvil --once

# Run a single iteration on mainnet
almanak strat run --once

# Browse and copy a working demo strategy
almanak strat demo
```

Each scaffolded strategy is a **self-contained Python project** with its own
`pyproject.toml`, `.venv/`, and `uv.lock`. The same files drive both local
development and the platform's cloud Docker build.

**Strategy project structure:**

```
my_strategy/
  strategy.py        # IntentStrategy subclass with decide() method
  config.json        # Runtime parameters (tokens, thresholds, funding)
  pyproject.toml     # Dependencies + [tool.almanak] metadata
  uv.lock            # Locked dependencies (created by uv sync)
  .venv/             # Per-strategy virtual environment
  .env               # Local dev credentials (not deployed; see Security Model)
  .gitignore         # Git ignore rules
  .python-version    # Python version pin (3.12)
  __init__.py        # Package exports
  tests/             # Test scaffold
  AGENTS.md          # AI agent guide
```

**pyproject.toml example:**

```toml
[project]
name = "my-strategy"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "almanak>=2.15.0",
]

[tool.almanak.run]
interval = 60
```

The `[tool.almanak.run]` section is required — it sets the execution interval (in seconds)
for the strategy loop in production. Always include it when writing pyproject.toml manually.

**Adding dependencies:**

```bash
uv add pandas-ta          # Updates pyproject.toml + uv.lock + .venv/
uv run pytest tests/ -v   # Run tests in the strategy's venv
```

For Anvil testing, add `anvil_funding` to `config.json` so your wallet is auto-funded on fork start
(see [Configuration](#configuration) below).

```python
# strategy.py
from decimal import Decimal
from almanak import MarketSnapshot
from almanak.framework.strategies import IntentStrategy, almanak_strategy
from almanak.framework.intents import Intent

@almanak_strategy(
    name="my_strategy",
    version="1.0.0",
    supported_chains=["arbitrum"],
    supported_protocols=["uniswap_v3"],
    intent_types=["SWAP", "HOLD"],
    default_chain="arbitrum",
)
class MyStrategy(IntentStrategy):

From almanak-co/sdk, Apache-2.0.