Un sistema avanzato per il rilevamento e l'esecuzione automatica di opportunità di arbitraggio su exchange di criptovalute, implementato in Python con aggiornamenti dei prezzi in tempo reale, algoritmi di ottimizzazione dei percorsi e supporto per modalità DRY RUN per test sicuri.
Questo sistema monitora continuamente i prezzi delle criptovalute su Binance (ed altri exchange supportati da CCXT) per identificare automaticamente opportunità di arbitraggio triangolare - dove è possibile ottenere profitto scambiando attraverso una sequenza di tre o più valute e ritornando alla valuta di partenza con un guadagno netto.
Caratteristiche chiave:
- ✅ Rilevamento automatico cicli di arbitraggio
- ✅ Esecuzione automatica o simulata (DRY RUN)
- ✅ Calcolo accurato con taker fee (0.1% default)
- ✅ Logging completo di tutti i trade
- ✅ Rate limiting intelligente per evitare ban
USDT → BTC → ETH → USDT
1000 USDT → 0.008 BTC → 0.12 ETH → 1003.5 USDT
Profitto: 3.5 USDT (0.35%)
- Polling Intelligente: Sistema multi-thread che aggiorna i prezzi con rate limiting automatico
- Gestione Rate Limit: Integrazione CCXT con protezione dai limiti API
- Prioritizzazione Simboli: Focus su coppie USDT/BTC per massimizzare le opportunità di arbitraggio
- Batch Processing: Richieste raggruppate in batch da 10 simboli con delay di 2s tra batch
- Cache Thread-Safe: Sistema di caching con lock per accesso concorrente sicuro
- Matrice Cross-Rate: Costruzione dinamica di tutti i tassi di cambio possibili
- Calcolo Precision: Simulazione realistica con taker fee (0.1%) e spread bid/ask
- DFS Cycle Detection: Ricerca cicli di lunghezza 3-4 con depth-first search
- BFS Path Finding: Ricerca percorsi ottimali tra valute con breadth-first search
- 🔵 DRY RUN Mode: Simulazione completa senza ordini reali (default:
dry_run=True)- Calcola profitti teorici
- Applica fee e rate realistici
- Zero rischio per test
- Output marcato con
[DRY RUN]
- 🔴 Live Trading Mode: Esecuzione reale su exchange (
dry_run=False)- Ordini market via CCXT
- Logging automatico in
logs/trades.json - Tracking completo con order ID
- Calcolo profitto effettivo vs atteso
- Taker Fee: 0.1% (0.001) applicata ad ogni trade
- Fee Calculation:
fee_amount = trade_amount * 0.001 - Final Amount:
amount_after = amount_before * (1 - 0.001) - Total Fees: Somma di tutte le fee del ciclo (tipicamente 0.3% per cicli triangolari)
- Profitto Netto: Calcolato dopo aver sottratto tutte le fee
- Logging Colorato: Output chiaro e leggibile con diversi livelli di log
- Statistiche Real-time: Monitoraggio performance e stato del sistema
- Opportunità Ranking: Classificazione automatica per profittabilità
- Trade History: Log permanente in JSON con timestamp, profitti, order IDs
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ ┌──────────────────┐
│ CCXT │ │ Cross-Rate │ │ Arbitrage │ │ Arbitrage │
│ Interface │───▶│ Matrix │───▶│ Detector │───▶│ Trade │
│ │ │ │ │ │ │ │
│ • Rate Limiting │ │ • Path Finding │ │ • Cycle Detect │ │ • 🔵 DRY RUN │
│ • Multi-thread │ │ • Graph Builder │ │ • Profit Calc │ │ • 🔴 Live Trade │
│ • Price Caching │ │ • Rate Updates │ │ • Ranking │ │ • Fee: 0.1% │
│ • Batch Process │ │ • Fee: 0.001 │ │ • Monitoring │ │ • JSON Logging │
└─────────────────┘ └──────────────────┘ └─────────────────┘ └──────────────────┘
- Gestisce la connessione all'exchange tramite la libreria CCXT
- Polling intelligente: Fetch ticker con rate limiting automatico
- Cache thread-safe: RLock per accesso concorrente sicuro
- Batch processing: 10 simboli per batch, 2s delay tra batch, 0.1s tra richieste
- Prioritizzazione simboli: 2/3 USDT, 1/3 BTC per arbitraggio triangolare
- Callbacks: Sistema di notifica per aggiornamenti prezzi
- Costruzione grafo: Nodi = valute, archi = tassi di cambio con fee
- ExchangeRate dataclass:
rate,spread,timestamp,source_symbol,fee=0.001 - BFS pathfinding: Trova percorsi ottimali tra valute (max 3 hop)
- DFS cycle detection: Ricerca cicli di lunghezza 3-4
- Calcolo profitto:
new_amount = current_amount * rate.rate fee_amount = new_amount * 0.001 # Taker fee final_amount = new_amount - fee_amount profit_ratio = (final_amount - initial_amount) / initial_amount
- Trade side detection: Determina automaticamente BUY/SELL in base a symbol format
-
🔵 DRY RUN Mode (
dry_run=True- DEFAULT):- Simula trades senza esecuzione reale
- Output marcato con
[DRY RUN] - Usa rate e fee da
cross_rate_matrix - Calcola
filled_amountteorico:new_amount * (1 - fee) - Order ID:
DRY_RUN_1,DRY_RUN_2, etc. - Zero rischio - perfetto per test
-
🔴 Live Trading Mode (
dry_run=False):- Esegue ordini market reali via
ccxt.create_market_order() - Richiede API key/secret valide
- Order ID reale dall'exchange
- Logging automatico in
logs/trades.json - Tracking: timestamp, cycle, amounts, profit, order IDs
- Esegue ordini market reali via
-
Calcolo amount corretto:
# Applica conversion rate new_amount = current_amount * step['rate'] # Applica taker fee (0.1%) next_amount = new_amount * (1 - 0.001) # Aggiorna amount per step successivo current_amount = next_amount
- Orchestratore principale del sistema
- Coordina aggiornamenti prezzi e ricerca arbitraggio
- Check arbitraggio ogni 5 secondi
- Integrazione con
ArbitrageTradeper esecuzione - Gestisce callbacks e notifiche
- Statistiche real-time ogni 30 secondi
- Sistema di logging avanzato con colori
- Supporto per file e console simultaneo
- Livelli configurabili (DEBUG, INFO, WARNING, ERROR)
- Singleton pattern per consistenza globale
Python 3.8+
pip (package manager)# Clona il repository
git clone <repository-url>
cd arbitrage-detector
# Installa le dipendenze
pip install -r requirements.txtccxt>=2.9.0 # Connettori exchange
websockets>=11.0.2 # WebSocket support (futuro)# Esegui con parametri default (Binance, 80 simboli)
# Modalità DRY RUN automatica - nessun trade reale
python realtime_arbitrage.py
# Esegui con parametri personalizzati
python realtime_arbitrage.py --exchange binance --limit 20--exchange/-e: Exchange da utilizzare (default: binance)--limit/-l: Numero massimo di simboli da analizzare (default: 80)
# In arbitrage_trade.py o realtime_arbitrage.py
trader.execute_cycle(cycle, initial_amount=100.0, dry_run=True) # ← DEFAULTCaratteristiche:
- ✅ Nessun ordine reale eseguito
- ✅ Zero rischio finanziario
- ✅ Test completo della logica
- ✅ Output marcato
[DRY RUN] - ✅ Calcoli identici al live trading
- ✅ Applica taker fee (0.1%) realistiche
- ✅ Perfetto per sviluppo e test
# Imposta API credentials
export EXCHANGE_API_KEY="your_api_key_here"
export EXCHANGE_API_SECRET="your_api_secret_here"
# Modifica realtime_arbitrage.py per live trading
# Cambia dry_run=False in execute_cycle()Caratteristiche:
⚠️ Esegue ordini REALI⚠️ Usa fondi REALI⚠️ Rischio di perdita- ✅ Logging automatico in
logs/trades.json - ✅ Order ID reali dall'exchange
- ✅ Profit tracking accurato
- Rate Limiting Intelligente: CCXT
enableRateLimit=True - Caching Multi-thread:
RLockper accesso thread-safe - Batch Processing: 10 simboli/batch, 2s delay tra batch
- Prioritizzazione: 2/3 USDT pairs, 1/3 BTC pairs
- Callbacks: Sistema di notifica non-blocking per aggiornamenti
- Simboli Monitorati: Numero di coppie di trading attive
- Frequenza Aggiornamenti: Rate di aggiornamento prezzi (aggiornamenti/secondo)
- Latenza Media: Tempo medio tra aggiornamento prezzo e rilevamento
- Errori Rate Limit: Monitoraggio errori API
- Opportunità Rilevate: Numero di cicli profittevoli trovati
- Profitto Medio: Profitto percentuale medio delle opportunità
- Durata Opportunità: Quanto durano le opportunità prima di scomparire
- Success Rate: Percentuale di opportunità effettivamente eseguibili
✅ Durante sviluppo e test ✅ Per validare la logica di trading ✅ Per verificare calcoli di profitto ✅ Prima di rischiare capitale reale ✅ Per testare nuovi exchange o simboli
- Fee per trade: 0.1% (0.001)
- Fee ciclo triangolare: ~0.3% (3 trade)
- Profitto minimo necessario: >0.3% per break-even
Esempio Calcolo:
Arbitraggio trovato: +0.5% profit teorico
Taker fees totali: -0.3%
Profitto netto: +0.2% (marginale)
Con slippage: potenzialmente negativo!
- Latenza: Delays di rete rendono obsolete le opportunità
- Slippage: Prezzo effettivo diverso da quello visualizzato
- Market Impact: Ordini grandi muovono i prezzi
- Capitale Minimo: Piccoli importi non coprono le fee
- Rate Limits: API throttling può causare fallimenti
- Network Issues: Connessione instabile = ordini parziali
# Step 1: DRY RUN con dati reali
python realtime_arbitrage.py -l 20
# Step 2: Verificare profitti > 0.1%
# Controllare logs/arbitrage_realtime.log
# Step 3: Test con importi minimi in live
# Modificare initial_amount a 10 USDT
# Step 4: Monitorare logs/trades.json
# Verificare profitti effettivi vs attesi# Usa variabili d'ambiente per sicurezza
export EXCHANGE_API_KEY="your_key"
export EXCHANGE_API_SECRET="your_secret"
# NON committare mai API keys in git!
echo "*.key" >> .gitignore
echo "*.secret" >> .gitignore- Importo massimo: Non più del 1-2% del capitale totale
- Stop loss: Chiudi il sistema se perdite > X%
- Profit target: Considera di fermarti dopo profitto Y%
- Monitoring: Log ogni trade e controlla regolarmente
- WebSocket: Latenza <50ms invece di ~2s con polling
- Multi-exchange: Arbitraggio cross-exchange
- Dynamic fees: Adatta alle fee reali dell'exchange
- Order types: Usa limit orders per ridurre slippage
- Position sizing: Calcola amount ottimale per simbolo
from logger import init_logger
# Configurazione custom
init_logger(
level="DEBUG",
log_file="logs/my_arbitrage.log",
console=True,
format_string="%(asctime)s [%(levelname)s] %(message)s"
)# In realtime_arbitrage.py
cycles = self.cross_rate_matrix.find_arbitrage_cycles(
base_currency="USDT",
min_profit_threshold=0.0005 # 0.05% minimum profit
)# Il sistema supporta tutti gli exchange CCXT
detector = RealTimeArbitrageDetector(
exchange_id='kucoin', # o 'kraken', 'okx', etc.
limit_markets=50
)arbitrage-detector/
├── realtime_arbitrage.py # Sistema principale detection + orchestration
├── arbitrage_trade.py # 🔵 DRY RUN / 🔴 Live trading executor
├── ccxt_interface.py # Interface CCXT con rate limiting
├── cross_rate_matrix.py # Algoritmi arbitraggio + fee calculation
├── logger.py # Sistema logging colorato
├── config.py # Configurazione CLI arguments
├── requirements.txt # Dipendenze Python
├── README.md # Questo file
├── test_arbitrage_cycle.py # Test script per verificare compatibilità
└── logs/
├── arbitrage_realtime.log # Log sistema
└── trades.json # Log trade eseguiti (solo live mode)
[
{
"timestamp": "2025-10-16T15:45:30.123456",
"exchange": "binance",
"cycle": ["USDT", "BTC", "ETH", "USDT"],
"initial_amount": 100.0,
"initial_currency": "USDT",
"final_amount": 100.68923,
"final_currency": "USDT",
"profit_percentage": 0.6892,
"profit_amount": 0.68923,
"expected_profit": 0.7148,
"steps": [
{
"step_number": 1,
"symbol": "BTC/USDT",
"side": "buy",
"amount": 0.00222,
"filled_amount": 0.0022195,
"average_price": 0.00002221,
"order_id": "123456789"
},
// ... altri step
]
}
]- WebSocket Real: Implementazione WebSocket nativi per latenza ultra-bassa
- Multi-Exchange: Arbitraggio cross-exchange
- Machine Learning: Predizione durata opportunità
- GUI Dashboard: Interface grafica per monitoraggio
- Mobile Alerts: Notifiche push per opportunità ad alto profitto
- Auto-Trading: Esecuzione automatica con risk management
- Fork il repository
- Crea un branch per la tua feature (
git checkout -b feature/AmazingFeature) - Commit le modifiche (
git commit -m 'Add some AmazingFeature') - Push al branch (
git push origin feature/AmazingFeature) - Apri una Pull Request
Questo software è fornito SOLO A SCOPO EDUCATIVO E DI RICERCA.
- ❌ Il trading di criptovalute comporta RISCHI SIGNIFICATIVI
- ❌ Puoi PERDERE TUTTO il capitale investito
- ❌ Le opportunità di arbitraggio sono RARE e BREVI
- ❌ Le TAKER FEE (0.1% per trade) erodono i profitti
- ❌ Lo SLIPPAGE può rendere non profittevoli gli arbitraggi
- ❌ I prezzi cambiano RAPIDAMENTE (secondi)
- ✋ Gli autori NON SONO RESPONSABILI per perdite finanziarie
- ✋ NESSUNA GARANZIA di profitto
- ✋ Il sistema può avere BUG o ERRORI
- ✋ Usa SEMPRE la modalità DRY RUN per test
- ✋ Non investire più di quanto puoi permetterti di perdere
- 📋 Consulta un consulente finanziario qualificato
- 📋 Verifica la legalità del trading automatico nella tua giurisdizione
- 📋 Rispetta i termini di servizio degli exchange
- 📋 Dichiara i profitti alle autorità fiscali competenti
- ✅ Usa DRY RUN per almeno 1 settimana
- ✅ Testa con importi minimi ($10-20)
- ✅ Monitora ogni singolo trade
- ✅ Verifica che profitti > fee + slippage
- ✅ NON aumentare il capitale senza test prolungati
🔵 SEMPRE PREFERIRE DRY RUN PER TEST E SVILUPPO 🔵
Questo progetto è distribuito sotto licenza MIT. Vedi il file LICENSE per dettagli.