Skip to content

Getting Started

This guide walks you through installing the Almanak SDK, configuring your environment, and running your first strategy.

Installation

pip install almanak

Or with uv:

uv pip install almanak

Environment Variables

Set the following environment variables before running strategies:

Variable Required Description
ALCHEMY_API_KEY Yes RPC access and Anvil fork testing
ALMANAK_PRIVATE_KEY Yes Private key for transaction signing
ALMANAK_API_KEY Optional Platform API access
GATEWAY_HOST Optional Gateway hostname (default: localhost)
GATEWAY_PORT Optional Gateway gRPC port (default: 50051)

Create a .env file in your project root:

ALCHEMY_API_KEY=your_alchemy_key
ALMANAK_PRIVATE_KEY=your_private_key

Create Your First Strategy

Use the CLI to scaffold a new strategy:

almanak strat new

This creates a strategy directory with:

  • strategy.py - Your strategy implementation
  • config.json - Chain, protocol, and token configuration
  • .env - Environment variables

Run Your Strategy

A managed gateway is auto-started in the background:

cd my_strategy
almanak strat run --once

Run on a Local Anvil Fork

For testing without real transactions:

almanak strat run --network anvil --once

This auto-starts both Anvil (forking mainnet via your Alchemy key) and the gateway.

Dry Run

To simulate without submitting transactions:

almanak strat run --dry-run --once

Strategy Structure

A strategy implements the decide() method, which receives a MarketSnapshot and returns an Intent:

from almanak import IntentStrategy, SwapIntent, HoldIntent, MarketSnapshot, Intent

class MyStrategy(IntentStrategy):
    def decide(self, market: MarketSnapshot) -> Intent:
        price = market.prices.get("ETH")
        balance = market.balances.get("USDC")

        if price < 2000 and balance > 500:
            return SwapIntent(
                token_in="USDC",
                token_out="ETH",
                amount=500,
                slippage=0.005,
            )
        return HoldIntent(reason="No opportunity")

Available Intents

Intent Description
SwapIntent Token swaps on DEXs
HoldIntent No action, wait for next cycle
LPOpenIntent Open liquidity position
LPCloseIntent Close liquidity position
BorrowIntent Borrow from lending protocols
RepayIntent Repay borrowed assets
SupplyIntent Supply to lending protocols
WithdrawIntent Withdraw from lending protocols
StakeIntent Stake tokens
UnstakeIntent Unstake tokens
PerpOpenIntent Open perpetuals position
PerpCloseIntent Close perpetuals position
FlashLoanIntent Flash loan operations
PredictionBuyIntent Buy prediction market shares
PredictionSellIntent Sell prediction market shares
PredictionRedeemIntent Redeem prediction market winnings

Next Steps