Premiers pas¶

Ce guide vous accompagne dans l'installation du SDK Almanak, la création de votre première stratégie et son exécution locale sur un fork Anvil -- sans portefeuille ni clés API.

Prérequis¶

Python 3.12+
uv (gestionnaire de paquets Python) :

curl -LsSf https://astral.sh/uv/install.sh | sh

Foundry (fournit Anvil pour les tests sur fork local) :

curl -L https://foundry.paradigm.xyz | bash
foundryup

Installation¶

pipx install almanak

Ou avec uv :

uv tool install almanak

Cela installe le CLI almanak globalement. Chaque stratégie créée a aussi almanak comme dépendance locale dans son propre .venv/ -- ce modèle à double installation est standard (comme CrewAI, Dagster, etc.).

Vous utilisez un agent de codage IA ? Enseignez-lui le SDK en une commande :

almanak agent install

Cela détecte automatiquement votre plateforme (Claude Code, Codex, Cursor, Copilot et 6 autres) et installe la compétence de construction de stratégies.

1. Obtenir une stratégie¶

Option A : Copier une démo fonctionnelle (recommandé pour les débutants)¶

almanak strat demo

Cela affiche un menu interactif de 13 stratégies de démonstration fonctionnelles. Choisissez-en une et elle est copiée dans votre répertoire courant, prête à être exécutée. Vous pouvez aussi ignorer le menu :

almanak strat demo --name uniswap_rsi

Option B : Créer à partir d'un modèle¶

almanak strat new

Suivez les invites interactives pour choisir un modèle, une chaîne et un nom. Cela crée un projet Python autonome contenant :

strategy.py - Votre implémentation de stratégie avec la méthode decide()
config.json - Configuration de la chaîne, du protocole et des paramètres
pyproject.toml - Dépendances et métadonnées [tool.almanak]
uv.lock - Dépendances verrouillées (créé par uv sync)
.venv/ - Environnement virtuel par stratégie (créé par uv sync)
.env - Variables d'environnement (remplissez vos clés plus tard)
.gitignore - Règles d'exclusion Git
.python-version - Version Python épinglée (3.12)
__init__.py - Exports du package
tests/ - Échafaudage de tests
AGENTS.md - Guide pour agents IA

Le scaffold exécute uv sync automatiquement pour installer les dépendances. Pour ajouter des paquets supplémentaires :

uv add pandas-ta          # Met à jour pyproject.toml + uv.lock + .venv/
uv run pytest tests/ -v   # Exécuter les tests dans le venv de la stratégie

2. Exécuter sur un fork Anvil local¶

Le moyen le plus rapide de tester votre stratégie -- pas de clés de portefeuille, pas de fonds réels, aucun risque :

cd my_strategy
almanak strat run --network anvil --once

Cette commande effectue automatiquement :

Démarre un fork Anvil de la chaîne spécifiée dans votre config.json (les RPC publics gratuits sont utilisés par défaut)
Utilise un portefeuille Anvil par défaut -- pas besoin de ALMANAK_PRIVATE_KEY
Démarre la passerelle sidecar en arrière-plan
Finance votre portefeuille avec les tokens listés dans anvil_funding (voir ci-dessous)
Exécute une itération de la méthode decide() de votre stratégie

Financement du portefeuille sur Anvil¶

Ajoutez un bloc anvil_funding à votre config.json pour financer automatiquement votre portefeuille au démarrage du fork :

{
    "anvil_funding": {
        "ETH": 10,
        "USDC": 10000,
        "WETH": 5
    }
}

Les tokens natifs (ETH, AVAX, etc.) sont financés via anvil_setBalance. Les tokens ERC-20 sont financés par manipulation des slots de stockage. Cela se produit automatiquement à chaque démarrage du fork.

Meilleures performances RPC (optionnel)¶

Les RPC publics gratuits fonctionnent mais sont limités en débit. Pour un forking plus rapide, définissez une clé Alchemy dans votre .env :

ALCHEMY_API_KEY=your_alchemy_key

Cela construit automatiquement les URLs RPC pour toutes les chaînes supportées. N'importe quel fournisseur fonctionne -- consultez Variables d'environnement pour l'ordre de priorité complet.

3. Exécuter sur le réseau principal¶

Warning

L'exécution sur le réseau principal utilise des fonds réels. Commencez avec de petits montants et utilisez un portefeuille dédié.

Pour exécuter sur des chaînes en production, vous avez besoin d'une clé privée de portefeuille dans votre .env :

# .env
ALMANAK_PRIVATE_KEY=0xYOUR_PRIVATE_KEY

# Accès RPC (choisissez un)
ALCHEMY_API_KEY=your_alchemy_key
# ou : RPC_URL=https://your-rpc-provider.com/v1/your-key

Puis exécutez sans le flag --network anvil :

almanak strat run --once

Tip

Testez d'abord avec --dry-run pour simuler sans soumettre de transactions :

almanak strat run --dry-run --once

Consultez Variables d'environnement pour la liste complète des options de configuration, y compris les clés API spécifiques aux protocoles.

Structure d'une stratégie¶

Une stratégie implémente la méthode decide(), qui reçoit un MarketSnapshot et retourne un Intent :

from decimal import Decimal
from almanak import IntentStrategy, Intent, MarketSnapshot

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

        if price < Decimal("2000") and balance.balance_usd > Decimal("500"):
            return Intent.swap(
                from_token="USDC",
                to_token="ETH",
                amount_usd=Decimal("500"),
            )
        return Intent.hold(reason="Pas d'opportunité")

Intentions disponibles¶

Intention	Description
`SwapIntent`	Échanges de tokens sur les DEX
`HoldIntent`	Pas d'action, attendre le prochain cycle
`LPOpenIntent`	Ouvrir une position de liquidité
`LPCloseIntent`	Fermer une position de liquidité
`BorrowIntent`	Emprunter auprès de protocoles de prêt
`RepayIntent`	Rembourser les actifs empruntés
`SupplyIntent`	Fournir aux protocoles de prêt
`WithdrawIntent`	Retirer des protocoles de prêt
`StakeIntent`	Staker des tokens
`UnstakeIntent`	Unstaker des tokens
`PerpOpenIntent`	Ouvrir une position de perpétuels
`PerpCloseIntent`	Fermer une position de perpétuels
`FlashLoanIntent`	Opérations de prêt flash
`CollectFeesIntent`	Collecter les frais LP
`PredictionBuyIntent`	Acheter des parts de marché prédictif
`PredictionSellIntent`	Vendre des parts de marché prédictif
`PredictionRedeemIntent`	Racheter les gains de marché prédictif
`VaultDepositIntent`	Déposer dans un coffre
`VaultRedeemIntent`	Racheter depuis un coffre
`BridgeIntent`	Transférer des tokens entre chaînes
`EnsureBalanceIntent`	Meta-intent qui se résout en `BridgeIntent` ou `HoldIntent` pour assurer un solde minimum de tokens sur la chaîne cible

Génération du manifeste de permissions (portefeuilles Safe)¶

Lors du déploiement d'une stratégie via un portefeuille Safe avec des restrictions Zodiac Roles, l'agent a besoin d'un ensemble explicite de permissions de contrats. Le SDK peut générer ce manifeste automatiquement en inspectant quels contrats et sélecteurs de fonctions les intents de votre stratégie compilent :

# Depuis le répertoire de la stratégie
almanak strat permissions

# Répertoire explicite
almanak strat permissions -d strategies/demo/uniswap_rsi

# Spécifier la chaîne
almanak strat permissions --chain base

# Écrire dans un fichier
almanak strat permissions -o permissions.json

La commande lit supported_protocols et intent_types depuis votre décorateur @almanak_strategy, compile des intents synthétiques via le vrai compilateur, et extrait l'ensemble minimal d'adresses de contrats et de sélecteurs de fonctions nécessaires. La sortie est un manifeste JSON applicable à un module Zodiac Roles. Si la stratégie supporte plusieurs chaînes, la sortie est un tableau JSON avec un manifeste par chaîne ; utilisez --chain pour générer pour une seule chaîne.

Uniquement pour les déploiements Safe/Zodiac

Les manifestes de permissions ne sont nécessaires que lors de l'exécution via un portefeuille Safe avec Zodiac Roles. Pour les tests Anvil locaux ou l'exécution par clé directe, aucune permission n'est requise.

Prochaines étapes¶

Variables d'environnement - Toutes les options de configuration
Référence API - Documentation complète de l'API Python
Référence CLI - Toutes les commandes CLI
API Passerelle - Services gRPC de la passerelle