Revolut PIT-38 Tax Calculation Skill

Revolut PIT-38 Tax Calculation Skill

Overview

This skill processes a Revolut consolidated brokerage statement (PDF) and an NBP average exchange rate table (CSV) to produce tax-ready figures for Polish PIT-38 filing, including the PIT/ZG attachment for foreign-sourced income.

Revolut, as a foreign broker (Revolut Securities Europe UAB, Lithuania), does not issue a PIT-8C. The taxpayer must manually calculate all amounts in PLN and file them. This skill automates that calculation.

Required Inputs

1. Revolut Consolidated Statement (PDF) — downloaded from the Revolut app under Invest → More → Documents. Contains sells summary, dividend details, cost basis (FIFO), and exchange rates used by Revolut (which are NOT the rates to use for tax purposes). If input is missing — DO NOT perform any actions; request the user to provide it.

2. NBP Average Exchange Rate Table (CSV) — already bundled with this skill at ./resources/kursy.csv (relative to this SKILL.md file). Always use this file directly — do NOT ask the user to provide an NBP rate table. The file covers the full tax year 2025 and contains columns: date, USD rate, EUR rate.

Key Tax Rules

Before starting, read resources/pit38-rules.md for the complete set of Polish tax rules that govern this calculation. The critical points are:

• All foreign currency amounts must be converted to PLN using the NBP average exchange rate from the last business day preceding the transaction date (Art. 11a ust. 1 ustawy o PIT).
• Revolut's own PLN conversions shown in the statement use different rates and cannot be used for PIT-38. Always recalculate using NBP rates.
• Stock sales use FIFO (First In, First Out) matching — Revolut already applies FIFO in its consolidated statement, so the cost basis and proceeds per transaction can be taken directly.
• Capital gains tax rate is 19% flat (Art. 30b ustawy o PIT).
• Dividend tax rate is 19% flat, with credit for withholding tax paid abroad.
• Foreign income requires PIT/ZG attachment, filed per country.

Workflow

Step 1: Parse Inputs

Read resources/revolut-statement-format.md for the exact structure of Revolut's PDF and how to extract data from it.

Revolut PDF: Extract two transaction tables:

• Sells table — columns: Date of Purchase, Date of Sale, Security name, Symbol/ISIN, Country, Qty, Cost basis (USD), Gross proceeds (USD), Gross PnL (USD), Fees (USD)
• Dividends table — columns: Date, Security name, Symbol/ISIN, Country, Gross amount (USD), Withholding tax (USD), Net amount (USD)

The PDF already contains PLN equivalents and Revolut's exchange rates — ignore these. Extract only the USD (or EUR) amounts and recalculate PLN values yourself.

NBP CSV: Always load from ./resources/kursy.csv (path relative to this SKILL.md). Parse into a date→rate lookup dictionary. Handle Polish number formatting (comma as decimal separator). The CSV has header and footer rows to skip (non-date rows).

Important: If the Revolut statement contains transactions with purchase dates from a prior year, ./resources/kursy.csv will not contain rates for those dates. In this case:

• Use the rate stated in the Revolut PDF as a fallback and flag it prominently with a note to verify against the actual NBP table for that year
• Do NOT ask the user to provide an NBP file — just flag the affected transactions

Step 2: Calculate PLN Values

For each transaction, determine the correct NBP rate:

def get_nbp_rate_before(date, rates_dict):
    """Get NBP average rate from the last business day BEFORE the given date."""
    d = date - timedelta(days=1)
    while d not in rates_dict:
        d -= timedelta(days=1)
        if (date - d).days > 10:
            raise ValueError(f"No NBP rate found within 10 days before {date}")
    return rates_dict[d], d

For stock sales:

• Przychód (income) = gross proceeds × NBP rate before sale date
• Koszt nabycia (acquisition cost) = cost basis × NBP rate before purchase date
• Opłaty (fees) = fees × NBP rate before sale date
• Koszty uzyskania przychodu (deductible costs) = koszt nabycia + opłaty
• Dochód (profit) = przychód − koszty uzyskania przychodu

For dividends:

• Przychód brutto = gross dividend × NBP rate before dividend date
• Podatek zagraniczny = withholding tax × NBP rate before dividend date

Step 3: Aggregate by Category and Country

Group results for PIT-38 sections:

PIT-38 Section	Content
Section C/E	Capital gains from stock sales (przychód, koszty, dochód)
Section F	Dividend income (przychód brutto, podatek zagraniczny, podatek do zapłaty)

Group results for PIT/ZG attachments — one per country:

• Typically USA (US-listed stocks) and possibly Netherlands (NL — e.g. Stellantis), Ireland (IE — e.g. some ETFs), or other jurisdictions.

Step 4: Calculate Tax

Capital gains (Section C/E):

podatek = ROUND(dochód × 0.19, 0)  # rounded to full PLN

Dividends (Section F):

podatek_PL = ROUND(przychód_brutto × 0.19, 0)
odliczenie = min(podatek_zagraniczny, podatek_PL)  # cannot exceed PL tax
do_zapłaty = podatek_PL − odliczenie

Step 4b: Run the Calculation Script

After extracting data from the Revolut PDF, write two JSON files and run the calculation script:

sells.json — array of stock sale records:

[
  {
    "name": "Fox Corporation (FOXA)",
    "country": "US",
    "currency": "USD",
    "purchase_date": "2024-07-08",
    "sale_date": "2025-03-10",
    "qty": "2",
    "cost_usd": "69.46",
    "proceeds_usd": "109.47",
    "fees_usd": "1.05",
    "cost_rate_override": "3.941"
  }
]

cost_rate_override is optional — only include when purchase_date falls outside the NBP CSV date range. Use the Revolut-stated rate as fallback and flag it prominently in the output.

dividends.json — array of dividend records:

[
  {
    "date": "2025-03-27",
    "name": "Fox Corporation",
    "symbol": "FOXA",
    "country": "US",
    "currency": "USD",
    "gross_usd": "0.77",
    "tax_usd": "0.12"
  }
]

All numeric amounts must be strings (not JSON numbers) to preserve decimal precision. Dates must be ISO 8601: "YYYY-MM-DD". For empty sections (no sells or no dividends), pass [].

Run:

python scripts/calculate_pit.py \
    --nbp resources/kursy.csv \
    --sells sells.json \
    --dividends dividends.json

The script outputs a single JSON object to stdout. Capture and parse it — all further output (XLSX, PDF) is generated from this structured data.

Step 5: Produce Output

Generate two deliverables (use the xlsx and pdf skills as appropriate):

1. XLSX workbook with three sheets:

   • "Sprzedaż akcji" — full transaction table with NBP rates, PLN values, PIT-38 summary box
   • "Dywidendy" — full dividend table with subtotals by country, PIT-38 summary box
   • "Podsumowanie PIT" — consolidated view of all amounts for PIT-38 + PIT/ZG

2. PDF report — print-ready version with the same three sections, formatted with tables and highlighted summary boxes showing amounts to enter in PIT-38.

Both outputs should include:

• Clear labels mapping each amount to the corresponding PIT-38 field/section
• Warnings about any rates taken from Revolut rather than NBP
• A reminder that Revolut data must be combined with PIT-8C from other brokers before filing
• A disclaimer that this is not tax advice

Important Caveats to Always Include

1. This is not tax advice. Always include a disclaimer.
2. Revolut rates ≠ NBP rates. Never use Revolut's PLN values for tax purposes.
3. Multi-broker aggregation. PIT-38 is filed once per year combining all brokers. Remind the user to add data from Polish brokers (which issue PIT-8C) before submitting.
4. Prior-year purchase rates. Flag any transaction where the purchase date falls outside the NBP CSV date range.
5. PIT/ZG per country. Each country with foreign income needs a separate PIT/ZG attachment.
6. W-8BEN treaty rates. Withholding tax rates depend on the user's W-8BEN status. The statement reflects what was actually withheld; the user should verify this is correct.
7. Fractional shares. Revolut supports fractional share trading. FIFO rules apply identically to fractional quantities — Revolut handles this in its consolidated statement.
8. Rounding. Final tax amounts on PIT-38 are rounded to full PLN (no grosze).

Edge Cases

• No sells, only dividends: Skip Section C/E, produce only Section F + PIT/ZG
• No dividends, only sells: Skip Section F, produce only Section C/E + PIT/ZG
• Multiple currencies (USD + EUR): Apply the correct NBP rate column for each currency
• Stellantis (NL) dividends: These are Dutch-source, requiring separate PIT/ZG for Netherlands
• Zero withholding tax (e.g. NVIDIA small dividends): Include in total, tax = $0
• Corporate actions: Revolut may list "Unprocessed Positions" — flag these for manual review

Reference Files

File	When to Read
resources/pit38-rules.md	Always — contains Polish tax law specifics
resources/revolut-statement-format.md	When parsing the Revolut PDF
./resources/kursy.csv	NBP mean exchange rates — bundled, always use this directly
scripts/pit_lib.py	Reference for calculation logic (NBP lookup, PLN conversion, tax math)
scripts/calculate_pit.py	CLI runner — call this with sells.json + dividends.json to get JSON results