L'unico software necessario è Python (gratuito, python.org).
brew install python3chmod +x Avvia_CriptoTaxWebApp.command.command → Apri (prima volta) → conferma.Doppio click su Avvia_CriptoTaxWebApp.bat. Si apre una finestra nera con i log. Dopo qualche secondo il browser si apre automaticamente su http://127.0.0.1:8000.
data/ per non lasciare i tuoi dati sulla chiavetta.Doppio click su Avvia_CriptoTaxWebApp.command. Si apre il Terminale con i log e parte il browser su http://127.0.0.1:8000. Per fermare: chiudi il Terminale (o premi Ctrl+C).
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000
poi apri il browser su http://127.0.0.1:8000.
L'inizializzazione del database (resetta le tabelle di app.db) avviene SOLO all'avvio del server (FastAPI lifespan). Non importare app.main dentro i tuoi script per richiamare le funzioni di calcolo: l'import è sicuro e NON ripulisce il database, ma gli script esterni che usano app.internal per analisi/backup NON devono lanciare init_db() da soli, altrimenti cancellano i dati caricati nella sessione in corso.
.csv, .tsv, .txt, .xlsx, .xls). Puoi caricare insieme trades, depositi, prelievi e acquisti con carta: l'app riconosce il formato di ogni file, lo adatta e li unisce eliminando i duplicati.
Carica SEMPRE il file degli acquisti (BUY), cioè i movimenti con cui hai comprato le cripto con euro/carta. Senza di essi il costo di carico (LIFO) risulta pari a zero e la plusvalenza calcolata non è reale. Includi quindi anche:
L'app riconosce nativamente, tra gli altri, questi formati:
Da esportare: Wallet → Transaction History → Trade (o: Trade → Session → Esporta storico).
Colonne attese: No, Time, Trade type, Role, Market, Deal price, Deal amount, Total, Fee.
Se l'exchange non esporta i movimenti d'acquisto, aggiungili manualmente al file personalizzato (vedi sotto) con type=buy:
time,type,asset,quantity,usdt 2025-03-14 10:00:00,buy,USDT,186.50,186.50
Tutti questi file si caricano INSIEME ai trades in un unico upload.
Nota sul calcolo: il metodo LIFO usa l'intero storico caricato (anni precedenti inclusi) come inventario, così anche le vendite di inizio anno usano il reale costo di carico e non un costo pari a zero.
Da esportare: Orders → Trade History (storico reale, NON l'estratto conto depositi).
Colonne attese: Date(UTC), Market, Type, Amount, Total.
Nota: il download ufficiale è un file ZIP contenente «Order» e «Trade». Usa il file TRADE (.csv), non Order. Decomprimi lo ZIP prima di caricare.
Da esportare: Reports → Generate report → type «Transactions» → file .csv o .tsv.
Colonne attese: Timestamp, Transaction Type, Asset, Quantity Transacted, USD Subtotal.
Attenzione: il report Coinbase contiene righe «Rewards Income», «Learning Reward», «Send», «Buy», «Sell», ecc. Tutte vengono riconosciute; le vendite/acquisti entrano nel calcolo, le ricompense vengono solo registrate.
Da esportare: History → Trades → Export (CSV «Trades»).
Colonne attese: time, pair, type, amount, total (oppure le intestazioni che produce l'export: txid, dtime, type, pair, cost, vol, fee).
Nota: se esporti «Ledger» invece di «Trades» il report può contenere molte righe non di trading (stake, fee, transfer) che l'app riconosce come tipi generici.
Da esportare: il report del wallet con tutti i movimenti (Trezor Suite: Account → History/Export CSV). L'export è per singolo account/coin: se fai uno swap per es. USDT → BTC comparirà una riga SENT sull'account USDT e una RECV sull'account BTC. Carica ENTRAMBI i file.
Colonne attese: Timestamp, Date, Time, Type (SENT/RECV/SELF), Transaction ID, Fee, Fee unit, Address, Label, Amount, Amount unit, Fiat (USD), ...
Riconoscimento:
SENT → prelievo neutro (nessun realizzo) se è un semplice trasferimento verso un portafoglio tuo;RECV → deposito neutro;SELF → movimento tra indirizzi tuoi: ignorato.Specifica su QUAL è lavorato con la colonna «Amount unit» e il controvalore è preso da «Fiat (USD)» (o, se manca, calcolato).
Caso tipico: hai convertito 500 USDT → 0,008 BTC direttamente dentro Trezor (o Ledger). Il CSV registra solo SENT/RECV neutri e senza un intervento la plusvalenza sull'USDT venduto NON verrebbe calcolata.
Cosa fare:
Da NON usare per i semplici trasferimenti tra i TUOI portafogli (exchange → wallet): quelli restano neutri e non vanno registrati come swap.
Perché è necessario: dal punto di vista fiscale NON tutte le conversioni cripto-cripto sono neutre. La neutralità vale solo per le permute «in prospettiva di investimento» tra attività con medesime caratteristiche e funzioni (es. BTC ↔ ETH, Circolare AdE 30/E/2023, par. 5.4.5). La conversione verso stablecoin/aziendali (USDT/USDC) o token di moneta elettronica (EMT) realizza invece una plusvalenza tassabile al momento dello scambio; con l'avvento di DAC8 (D.Lgs. 194/2025) questi swap saranno segnalati all'Agenzia delle Entrate, quindi vanno dichiarati correttamente.
Se paghi un prodotto/servizio direttamente col wallet (es. BTC spesi dal Trezor per comprare un bene), per il fisco non è un trasferimento: è una VENDITA che realizza una plusvalenza/minusvalenza al valore in € del bene alla data del pagamento.
Nell'app (riquadro «REGISTRA UNA CESSIONE»):
I trasferimenti tra i TUOI portafogli NON sono cessioni: restano neutri.
L'app tenta il riconoscimento automatico cercando le colonne per parole chiave: time/data, pair/asset/coin/market, type/side, amount/quantity, total/usdt/value, fee/commission. Basta che esistano le colonne con quei nomi (o simili).
Crea un CSV con queste 5 colonne (o usa quello già presente in data/):
time,type,asset,quantity,usdt
esempi di riga:
2025-03-14 10:00:00, buy, BTC, 0.001, 88.50 2025-03-14 11:30:00, sell, BTC, 0.0005, 47.00
Dove:
time = data/ora nel formato AAAAMMGG o AAAA-MM-GGtype = buy / sell / deposit / withdrawalasset = simbolo dell'asset (es. BTC, ETH, MLN)quantity = quantità negoziatausdt = controvalore in dollari (solo per i calcoli)Prima di caricare assicurati che:
Puoi caricare PIÙ FILE INSIEME (trades + depositi + prelievi + acquisti): l'app riconosce il formato di ciascuno, li adatta e li unisce eliminando i duplicati. Ogni nuovo upload si AGGIUNGE ai dati già presenti (lo storico degli anni precedenti viene così conservato): i duplicati identici vengono scartati, quindi puoi ricaricare tranquillamente lo stesso file.
Prepara tutti i file delle operazioni come descritto nella sezione 3 qui sopra («Preparare i file CSV»): trades, depositi, prelievi e acquisti con carta/euro.
In ogni caso le nuove operazioni si AGGIUNGONO a quelle già caricate in precedenza (i duplicati identici vengono eliminati): si può ripetere l'upload di uno stesso file senza il rischio di azzerare lo storico.
L'elaborazione avviene in 2 passaggi:
app/services/tax_report.py).
Nel form di upload (Passo 1) puoi inserire nome, cognome e codice fiscale (facoltativi). Vengono mostrati nell'anteprima, nella sezione «Dati del Contribuente» del report e nella copertina del PDF per il commercialista.
IMPORTANTE: i dati NON vengono salvati su disco: sono tenuti solo in memoria (RAM) e si azzerano automaticamente a OGNI avvio dell'app, come le transazioni.
Nel Passo 1 (preview), prima di calcolare il report, trovi il campo «Minusvalenze pregresse non compensate (€)». Inserisci qui l'importo delle minusvalenze realizzate in anni precedenti e non ancora compensate: viene sottratto dall'imponibile positivo dell'anno PRIMA del calcolo dell'imposta.
Ordine di calcolo (importante): dal guadagno netto dell'anno si applica prima la franchigia di €2.000 (solo fino al 2024) e solo sull'eventuale imponibile residuo si scontano le minusvalenze pregresse. Di conseguenza un guadagno annuo sotto i €2.000 non consuma le minusvalenze pregresse: la perdita resta interamente riportabile agli anni successivi.
Nel report compaiono la voce «Minusvalenze pregresse compensate» e la voce inequivocabile «MINUSVALENZE DA SCONTARE» (il residuo ancora da scontare: va reinserito l'anno successivo nel campo «Minusvalenze pregresse non compensate»).
Le minusvalenze sono compensabili SENZA limiti di tempo dal 2025 (L. 207/2024) e nei 4 anni successivi per quelle realizzate fino al 2024.
Attenzione al riporto cumulativo: il valore «MINUSVALENZE DA SCONTARE» del report è già il totale cumulato. Ogni anno va reinserito solo quel numero, senza sommarlo a mano a quelli degli anni precedenti (altrimenti si sconterebbero più minusvalenze del dovuto).
| Anno | Cosa inserisci nel campo | Risultato netto anno | Compensate | MINUSVALENZE DA SCONTARE (residuo) |
|---|---|---|---|---|
| 2022 | 0 € | −30 € | 0 € | 30 € |
| 2023 | 30 € | −30 € | 0 € | 60 € |
| 2024 | 60 € | +100 € | 0 € | 60 € |
| 2025 | 60 € | +3.000 € | 60 € | 0 € |
Nel 2023 reinserisci 30 €: si somma alla nuova perdita di 30 € e il residuo diventa 60 €. Nel 2024 reinserisci 60 € — non 90 € — perché il 60 contiene già i 30 € del 2022. Attenzione: il guadagno del 2024 (+100 €) è sotto la franchigia di €2.000, quindi non si paga imposta e le pregresse NON si consumano (restano 60 €). Solo nel 2025 (nessuna franchigia) i 60 € vengono effettivamente scontati. Ogni anno si riporta solo il valore «MINUSVALENZE DA SCONTARE» dell'anno precedente.
Dopo il Passo 2, nella pagina del report c'è il pulsante «Scarica PDF per Commercialista». Il PDF contiene:
Questo PDF è pensato direttamente per il commercialista per la compilazione della dichiarazione (Redditi / 730).
| Problema | Soluzione |
|---|---|
| «Python non trovato» | Installa Python e spunta «Add Python to PATH» (Windows); su macOS reinstallalo. Riavvia il launcher. |
| Il browser non si apre | Apri manualmente http://127.0.0.1:8000. |
| Porta 8000 già occupata | Chiudi l'altra istanza, oppure avvia manualmente con un'altra porta: python -m uvicorn app.main:app --port 8001 e apri http://127.0.0.1:8001. |
| «Formato CSV non supportato» | Il CSV deve contenere almeno le colonne time/date, pair/market, type/side, amount. Esporta il Trade History, non un estratto conto. |
| Nessuna transazione per l'anno scelto | Verifica che l'anno fiscale selezionato corrisponda alle date presenti nel CSV. |
| Primo avvio molto lento | È normale, pip sta scaricando le librerie. Attendi il messaggio «Uvicorn running». |
Per stimare il valore del portafoglio (Quadro RW / IC) l'app consulta i prezzi storici in quest'ordine:
Se non ricorda un prezzo usa il valore 1 EUR solo come ultima risorsa, e lo segnala nei log.
Windows: apri Avvia_CriptoTaxWebApp.bat con il Blocco note e, prima della riga che avvia uvicorn, aggiungi:
set CRYPTOCOMPARE_API_KEY=TuaChiave set FIXER_API_KEY=TuaChiaveFixer
Apple: apri Avvia_CriptoTaxWebApp.command con un editor e aggiungi prima dell'avvio:
export CRYPTOCOMPARE_API_KEY="TuaChiave" export FIXER_API_KEY="TuaChiaveFixer"
Dove le ottieni (gratuite):
Senza chiavi l'app funziona comunque (CoinGecko + Gate.io + dal tuo storico acquisti). Le chiavi servono solo per avere prezzi ancora più completi.
Questa sezione è pensata per chi diffonde l'app tramite chiavetta USB (es. a parenti o conoscenti) e per chi la riceve.
data/ (dentro la cartella dell'app) prima di estrarre la chiavetta. Così non restano dati personali neppure come file.data/ dopo ogni utilizzo (vedi punto 1).data/ se contiene prezzi già scaricati.git pull per portare l'ultima versione (se il progetto è distribuito come repository).GUIDA_USO.txt o con un nome diverso dai file descritti nella sezione 5, potrebbe essere una versione contraffatta: NON usarla e avvisa chi te l'ha consegnata.