🌐 Français | English

🚀 Un outil d'analyse terminal pour identifier les meilleures opportunités de flip sur le Bazaar d'Hypixel SkyBlock

🏁 Démarrage Rapide • 📖 Documentation • 🎯 Filtres • ⚙️ Paramètres

---

🏆 Ce que j'ai réussi avec cet outil

Plus d'1 MILLIARD de coins générés manuellement

Capture d'écran in-game montrant 1,000,063,498 coins dans ma bourse

En utilisant cet outil de manière consistante pour identifier les meilleures opportunités de flip, j'ai pu générer plus d'un milliard de coins sur Hypixel SkyBlock. L'outil ne fait aucune action automatique - il analyse simplement les données du Bazaar et vous présente les meilleures opportunités. Toutes les transactions sont effectuées manuellement dans le jeu.

---

📋 Description du Projet

Hypixel Bazaar Flipper est un outil d'analyse en ligne de commande qui :

• 📊 Récupère les données en temps réel du Bazaar via l'API officielle Hypixel
• 🧮 Calcule des métriques avancées : marge, liquidité, score de profitabilité
• 📈 Classe les items par opportunité de profit
• 🔍 Permet de filtrer avec des expressions logiques puissantes
• 💾 Supporte le mode hors-ligne avec mise en cache locale

Ce que cet outil n'est PAS

• ❌ Pas de bot automatique
• ❌ Pas d'achat/vente automatisé
• ❌ Ne viole pas les règles d'Hypixel
• ✅ Un outil d'aide à la décision pour le trading manuel

---

🏁 Démarrage Rapide

Prérequis

Requirement	Version	Description
Python	3.11+	Langage de programmation
uv	Latest	Gestionnaire de dépendances Python moderne
Clé API Hypixel	-	Obtenue sur developer.hypixel.net

Installation en 3 étapes

# 1. Cloner le repository
git clone https://github.com/julesgtz/hypixel-bazaar-flipper.git
cd hypixel-bazaar-flipper

# 2. Installer les dépendances
uv sync

# 3. Configurer la clé API
echo "API_KEY=votre_clé_api_ici" > .env

Obtenir une clé API Hypixel

1. Connectez-vous sur developer.hypixel.net
2. Créez une nouvelle application
3. Copiez la clé API générée
4. Collez-la dans le fichier .env

---

🎮 Utilisation

Lancement basique

uv run main.py

L'application va :

1. Récupérer les données du Bazaar via l'API Hypixel
2. Calculer les métriques pour chaque item
3. Afficher une interface terminal interactive

---

⚙️ Paramètres de Lancement

Paramètre	Forme Courte	Forme Longue	Description
Mode Offline	-o	--offline	Utilise les données mises en cache localement au lieu de l'API
Mode Debug	-d	--debug	Active les logs de niveau DEBUG pour le débogage

Exemples de commandes

# Lancement normal (récupère les données de l'API)
uv run main.py

# Mode hors-ligne (utilise le cache local data/bazaar.json)
uv run main.py --offline
uv run main.py -o

# Mode debug (logs détaillés)
uv run main.py --debug
uv run main.py -d

# Combiner les options
uv run main.py --offline --debug
uv run main.py -o -d

---

📊 Colonnes Affichées

L'interface affiche les informations suivantes pour chaque item :

Colonne	Description
Name	Nom de l'item du Bazaar
Liquidity	√(InstaBuy × InstaSell) - Mesure de l'activité de trading
Marge	Prix d'achat (Buy Order) - Prix de vente (Sell Order)
Buy Price	Prix actuel des Buy Orders (ce que vous payez)
Sell Price	Prix actuel des Sell Orders (ce que vous recevez)
Buy 7d	Volume d'InstaBuys sur les 7 derniers jours
Sell 7d	Volume d'InstaSells sur les 7 derniers jours
Marge %	Pourcentage de marge : (Marge / Sell Price) × 100
Score	Score de profitabilité calculé (voir formule ci-dessous)

Formule du Score

Score = Marge% × log(1 + Marge%) × √Liquidité

Cette formule privilégie les items avec :

• Une marge pourcentage élevée
• Un volume de trading suffisant (liquidité)
• Un bon équilibre risque/rendement

---

🎯 Système de Filtrage

L'interface inclut un champ de recherche puissant permettant de filtrer les items avec des expressions logiques.

Abréviations Disponibles

Abréviation	Nom Complet	Description
s	score	Score de profitabilité
bp	buy_price	Prix d'achat (Buy Order)
sp	sell_price	Prix de vente (Sell Order)
m	marge	Marge brute en coins
mp	marge_pct	Marge en pourcentage
l	liquidity	Liquidité
p	profit	Profit

💡 Astuce : Vous pouvez utiliser soit les abréviations (s, bp, etc.) soit les noms complets (score, buy_price, etc.)

Opérateurs Supportés

Type	Opérateurs
Comparaison	>, <, >=, <=, ==, !=
Logiques	and, or, not
Groupement	( et )

Exemples de Filtres

# Items avec un score > 10000 ET une marge % > 5%
s > 10000 and mp > 5

# Items avec un prix d'achat < 1000 OU une marge > 2000, ET une liquidité > 30000
(bp < 1000 or m > 2000) and l > 30000

# Combinaison complexe avec noms complets
(score > 1000 and buy_price < 5000) or marge_pct > 8

# Filtrer par fourchette de prix
sp > 5000 and sp < 100000

# Hautes marges uniquement
mp > 10 and l > 50000

---

📖 Comment ça Marche

Architecture

hypixel-bazaar-flipper/
├── main.py            # Point d'entrée principal
├── api.py             # Récupération et traitement des données
├── console.py         # Interface utilisateur (Textual TUI)
├── data/
│   └── bazaar.json    # Cache local des données
├── logs/
│   └── [date].log     # Logs journaliers
├── assets/            # Images et ressources
├── .env               # Configuration (clé API)
└── pyproject.toml     # Dépendances du projet

Flux de Données

graph LR
    A[API Hypixel] -->|Fetch| B[api.py]
    B -->|Process| C[Calcul des métriques]
    C -->|Score| D[Tri & Filtrage]
    D -->|Display| E[console.py TUI]
    B -.->|Cache| F[data/bazaar.json]
    F -.->|Offline| B

Loading

Étapes du Traitement

1. Récupération : Appel à l'API Hypixel /v2/skyblock/bazaar
2. Nettoyage : Filtrage des items sans données de prix
3. Calcul :
   • Marge = Buy Price - Sell Price
   • Marge % = Marge / Sell Price
   • Liquidité = √(Volume Buy × Volume Sell)
   • Score = Marge% × log(1 + Marge%) × √Liquidité
4. Cache : Sauvegarde dans data/bazaar.json
5. Affichage : Interface interactive triée par score

---

📝 Logs

Chaque exécution génère un fichier de log dans le dossier logs/ :

logs/
├── 13-01-2025.log
├── 12-01-2025.log
└── ...

Niveaux de Log

Mode	Niveau	Informations affichées
Normal	INFO	Messages principaux, erreurs
Debug (-d)	DEBUG	Tout + requêtes API, parsing, calculs

---

🔧 Dépendances

Package	Version	Utilisation
requests	≥2.32.4	Requêtes HTTP vers l'API
rich	≥14.0.0	Formatage console riche
textual	≥3.6.0	Interface TUI interactive
dotenv	≥0.9.9	Chargement des variables d'environnement

---

🗺️ Roadmap

• Interface terminal interactive
• Système de filtrage avec expressions logiques
• Algorithme de scoring
• Mode hors-ligne avec cache
• Système de logs
• Export CSV des résultats
• Alertes webhook Discord
• Interface web

---

🤝 Contribution

Les contributions sont les bienvenues ! N'hésitez pas à :

1. Fork le projet
2. Créer une branche (git checkout -b feature/AmazingFeature)
3. Commit vos changements (git commit -m 'Add AmazingFeature')
4. Push la branche (git push origin feature/AmazingFeature)
5. Ouvrir une Pull Request

---

📄 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

---

⚠️ Avertissement

Cet outil est destiné uniquement à l'analyse manuelle du Bazaar. Il ne viole aucune règle d'Hypixel car :

• Il utilise l'API officielle publique
• Il n'automatise aucune action de jeu
• Toutes les décisions de trading sont prises par l'utilisateur

Utilisez de manière responsable et à vos propres risques.

---

⭐ Si ce projet vous a aidé, n'hésitez pas à lui donner une étoile !

Made with ❤️ for the Hypixel SkyBlock community