🚀 Hyperliquid Analytics Agent

Agent d’analyse technique en cours de construction autour des données Hyperliquid, avec une trajectoire orientée vers l’agrégation multichaîne on-chain et des calculs off-chain avancés.

État actuel

• Client Hyperliquid (async) : appels /info (candleSnapshot, metaAndAssetCtxs, userFills) gérés, validations Pydantic (PerpMeta, PerpAssetContext, MetaAndAssetCtxsResponse, MarketData…).
• Repository PostgreSQL : schéma persistant (candles, perp_asset_ctxs, perp_universe, margin_tables), upsert via ON CONFLICT, timestamps UTC.
• Services :
  • AnalyticsService orchestre le client Hyperliquid et le repository Postgres.
  • IndicatorService calcule les indicateurs (SMA, EMA, RSI, MACD, Bollinger, ATR, Stochastic, VWAP) en SQL Postgres.
  • AnalysisPipeline orchestre les stratégies (BaseStrategy, ex. RSI, MACD) et génère des Signal.
• Architecture Découplée (Temps Réel) :
  • scheduler ws : Ingestion WS + backfill via REST.
  • monitor run : Lecture DB + exécution des stratégies.
• CLI Click : collecte, affichage, indicateurs, scheduler, monitor.
• Tests unitaires : adaptés à Postgres (skip si Postgres local indisponible).

Installation

python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

Configuration

cp .env.example .env
# Éditer .env avec vos clés/URL Hyperliquid et Postgres

Variables principales :

• HYPERLIQUID_ANALYTICS_BASE_URL
• HYPERLIQUID_ANALYTICS_SYMBOLS_RAW
• HYPERLIQUID_ANALYTICS_POSTGRES_HOST (défaut: localhost)
• HYPERLIQUID_ANALYTICS_POSTGRES_PORT (défaut: 5432)
• HYPERLIQUID_ANALYTICS_POSTGRES_USER/PASSWORD/DB

Architecture Trading Temps Réel (Recommandée)

Pour lancer le bot en mode trading temps réel, utilisez deux terminaux séparés :

Terminal 1 : Collecteur de Données (WebSocket)
Écoute Hyperliquid et écrit les bougies en base :

docker-compose up -d  # démarre Postgres local
python -m hyperliquid_analytics.cli scheduler ws -t 1h

Terminal 2 : Analyseur de Stratégies (Monitor)
Surveille la base et déclenche les stratégies :

# Mode Production (silencieux)
python -m hyperliquid_analytics.cli monitor run -t 1h
# Mode Debug (valeurs d’indicateurs et état initial)
python -m hyperliquid_analytics.cli monitor run -t 1h --debug

Démarrage automatisé (tmux + make)

Une cible make dev-up (cf. Makefile) démarre tout en une fois :

make dev-up
# Puis attache-toi à la session tmux :
tmux attach -t hyperliquid

Ce que fait make dev-up :

• lance Postgres via docker-compose up -d
• crée une session tmux hyperliquid en 2 panes :
  • pane 0 : scheduler ws (ingestion)
  • pane 1 : monitor run --debug (analyse)

Autres Commandes utiles

# Collecter un snapshot complet
python -m hyperliquid_analytics.cli collect snapshot

# Calculer un indicateur ponctuel
python -m hyperliquid_analytics.cli show indicator rsi -s BTC -t 1h --window 14

# Afficher l'historique récent
python -m hyperliquid_analytics.cli show history -s BTC --limit 5

Tests

./venv/bin/python -m pytest

Notes :

• Les tests du repository et des indicateurs nécessitent un Postgres accessible à localhost:5432 (docker-compose up -d).
• Les tests se skippent automatiquement si Postgres n’est pas joignable.
• Installe pip install -e .[dev] avant de lancer la suite.

TODO Pipeline & Stratégies (Hyperliquid)

• Implémenter les stratégies manquantes et les brancher dans le pipeline :
  • Bollinger : prix touche/passe bande inférieure/supérieure.
  • Stochastic (K/D) : croisement en zones <20 / >80.
  • VWAP : prix croise VWAP (biais long/short).
  • SMA/EMA crossover : EMA courte croise EMA longue.
  • ATR (alertes de volatilité).
• Persister les signaux dans une table signals (Postgres) et exposer une commande show signals.
• Ajouter l’alerting (webhook/Discord/Telegram) sur les signaux générés par monitor run.

Roadmap vers un système d’analytics complet

• 🐣 Phase 1 — Hyperliquid seulement (Terminée)

  • Client async & modèles Pydantic
  • Service + CLI de collecte/lecture
  • Indicateurs techniques via SQL (PostgreSQL)
  • Scheduler d’ingestion
  • Pipeline d'analyse et Stratégies RSI/MACD
  • Architecture découplée (Ingestion vs Analyse)

• 🌐 Phase 2 — Analytics temps réel & API interne (En cours)

  • Alerting (webhook/Discord/Telegram)
  • API FastAPI exposant snapshots / indicateurs / signaux
  • WebSocket trades pour granularité tick

• 🔗 Phase 3 — Extension multichaîne & on-chain

  • Ingestion données on-chain (DEX, bridges)
  • Normalisation multi-sources

• 🚀 Phase 4 — Industrialisation

  • TimescaleDB / ClickHouse
  • Backtesting engine

---

👉 Contributions / feedback bienvenus : tests, intégrations de nouvelles sources, idées d’indicateurs. Ouvre une issue ou une PR pour en discuter ! 💬