# PoliErgaleio

> Free bilingual (EN/EL) Cyprus financial calculators and optimization tools: income tax, mortgage, capital gains, EV savings, retirement, investments and budgeting for 2026.

PoliErgaleio is a client-side React app with Supabase-backed accounts. Calculations use Cyprus tax rules (2025 and 2026), with client-side AES-256-GCM encryption for stored financial inputs. All tools are free.

## Pages

- [Home](/): Overview of all Cyprus financial calculators.
- [All Calculators](/allcalculators): Index of every PoliErgaleio tool.
- [Income Tax Calculator](/calculator): Cyprus income tax, social insurance, GESY and deductions for 2026.
- [Capital Gains Calculator](/capital-gains): Cyprus property capital gains with CPI adjustments and the 2026 lifetime exemptions for general disposals, qualifying homes and agricultural land.
- [Mortgage Planner](/mortgage-planner): Amortization schedules, overpayments and rate comparisons.
- [Mortgage Forensics](/mortgage-forensics): Reverse-engineer your bank's interest convention from a statement CSV.
- [Rent vs Buy](/rent-vs-buy): 30-year breakeven analysis comparing renting and buying.
- [EV Savings](/ev-savings): Compare electric vs petrol total cost of ownership in Cyprus.
- [Investment Comparison](/investment-comparison): Compare fees, taxes and long-term returns of investment products.
- [Monthly Expenses](/monthly-expenses): Budget tracker with disposable income and savings rate.
- [Life Insurance Optimizer](/life-insurance-flush): Tax-optimal withdrawal strategy for Cyprus life insurance policies.
- [State Pension](/state-pension): Estimate Cyprus state pension from insurance units and retirement age.
- [Stock Options](/stock-options): Cyprus stock option tax (BIK vs 8% flat 2026 scheme).
- [Company Director Optimizer](/company-director-optimizer): Cyprus LTD salary vs dividend solver for maximum net cash.
- [Retirement Planner](/retirement-planner): Deterministic retirement stress-test with Monte Carlo simulation.
- [Portfolio Tracker](/portfolio-tracker): Multi-currency portfolio performance with CAGR.
- [Net Worth Tracker](/net-worth-tracker): Combine calculator data with manual entries over time.

## Optional

- [About](/about): Project mission and team.
- [Contact](/contact): Support and feedback.
- [Release Notes](/release-notes): Latest product updates.
- [Privacy](/privacy): Privacy policy.
- [Terms](/terms): Terms of use.

## Public API & MCP

PoliErgaleio exposes its Cyprus financial calculators as a Public Calculation API, usable directly over HTTP or as an MCP (Model Context Protocol) server for AI assistants such as ChatGPT, Claude Desktop, and Cursor.

- Get a free API key: sign in and generate one from [Profile](/profile).
- MCP discovery manifest: `/.well-known/mcp.json`.
- Full documentation, connection configs, and live examples: [Developers](/developers).
- Plain-text developer reference: [`/developers.txt`](/developers.txt) (also linked from the discovery manifest).
- Authentication: send your key in the `x-api-key` header on every request. Anonymous use is allowed on the stateless calculators (10/min, 50/day, 200/week); optionally send an opaque `x-guest-id` header.
- `GET /whoami` verifies an API key: returns tier, masked key prefix, rate limits, current usage and which tools you can call (never echoes the key). Verify in the browser at https://poliergaleio.com/developers/verify. Ready-made request bundles: /poliergaleio-api.postman_collection.json, /poliergaleio-api.postman_environment.json, /poliergaleio-openapi.json (full, 32 ops), /poliergaleio-chatgpt-actions.json (ChatGPT Action 1, 19 calculators), /poliergaleio-chatgpt-user-actions.json (ChatGPT Action 2, 6 saved-calculation tools).
- Every JSON response (including 400/401/404/429 errors and MCP results) includes `requestId` and `guestId` fields, mirrored in `X-Request-Id` / `X-Guest-Id` headers (send your own to have it echoed). `GET /schemas` and `GET /schemas/{tool}` return JSON Schema 2020-12 input/output descriptors with embedded request/response `examples`, cacheable via `ETag` + `Cache-Control` (send `If-None-Match` for a 304); `GET /saved-calculations?types=&sort=&limit=&offset=&cursor=` filters, sorts (default most recent first) and pages an API key's saved calculations.
- API 2.0.0 is a breaking calculator-input release: MCP and REST use the same strict validation before builders run. Missing essentials return actionable `fieldErrors` and `hint`, never a numerical estimate. Reuse facts already given and ask only for missing inputs; schema examples are not defaults and must never be used as personal facts. Successful results disclose defaults and exclusions actually used in `structuredContent.assumptions` and result text. Reconnect MCP clients or re-import the ChatGPT Action schema; migration guide: https://poliergaleio.com/migrations/v2-0-0.
- API 3.0.0 corrects unemployment entitlement and dependant labels, EV allocation, life-policy IRR, mortgage balloon and closure cash, portfolio TWR availability, parser handoffs and zero-income budget handling. Ask for salary period and employment category, rent deposit units and stock-option approval before personalized calls. Reconnect the MCP client for current tool guidance; nullable eligibility, IRR, TWR and savings rate require client handling.
- API 3.0.1 makes the rent-deposit unit and stock-option approval clarifications explicit. API 4.0.0 introduced the explicit income-tax employment category and corrected life-insurance withdrawal accounting. API 5.0.0 corrects retirement depletion statistics, adds seeded repeatability and typed result details for investment leadership, life-insurance balances, mortgage-fit uncertainty and unemployment follow-up questions. API 6.0.0 adds strict resource-bound OAuth for saved-calculation tools and keeps anonymous access for calculators. Refresh MCP schemas or re-import ChatGPT Actions; see https://poliergaleio.com/migrations/v6-0-0. API 7.0.0 corrects retirement return handling so the supplied retirement return applies across all retirement phases and fixes `calculate_cyprus_state_pension.minimumPensionApplied` so it reports when the 85% minimum basic-pension floor raises the result. Refresh client schemas and review affected projections and pension results produced with API 6.0.0. See https://poliergaleio.com/migrations/v7-0-0.
- API 8.0.0 corrects self-employed income-tax results: the 2026 0.5% HRDA levy is included from 6 April using the official insurable-earnings basis, and official 2025/2026 occupational schedules replace outdated SI amounts. `selfEmployedHRDA` is added; affected self-employed net results change. Refresh schemas and review estimates: https://poliergaleio.com/migrations/v8-0-0.
- API 10.0.0 is a breaking correctness release: deposit interest is taxed through SDC rather than progressive PIT; taxable cryptoasset gains use an 8% flat rate in 2026; the foreign-pension flat allowance is €5,000 in 2026 (€3,420 in 2025); and eligible property CGT lifetime exemptions are €30,000/€150,000/€50,000. Foreign pension streams in retirement projections use the corrected 2026 treatment. Refresh schemas and review saved income-tax, capital-gains and retirement results. The minimum client version remains 1.0.0; no 426 upgrade response is required. See https://poliergaleio.com/migrations/v10-0-0.
- API 11.0.0 is a breaking security release: `optimize_company_director_remuneration` accepts monetary inputs only up to €1,000,000 and rejects oversized inputs before calculation; the solver is capped at 10,001 salary-allocation evaluations. Refresh cached schemas; oversized requests return 400. API-key policy is server-managed, and keyed usage remains attributed to the account after a key is deleted. See https://poliergaleio.com/migrations/v11-0-0.
- API 17.0.0 is a breaking correctness release: `plan_monthly_budget` reports cash-basis `savingsRate` after expenses and investments (it can be negative), adds `totalMonthlyOutgoings` and `currentMonthlySavings`, excludes investments from `totalMonthlyExpenses`, and clamps deficit-month savings and projections at zero. `analyze_portfolio` reports `cagr` only for a single deposit with no withdrawals and returns `cagrUnavailableReason` plus `cagr: null` otherwise; use the time-weighted return. Refresh schemas and recalculate/review affected budgets and portfolios. Minimum client version remains 1.0.0. See https://poliergaleio.com/migrations/v17-0-0.
- API 16.0.0 corrects mortgage schedule cash conservation and interest-only minimums after overpayments; rent-versus-buy uses actual costs through payoff and symmetrically invests lower-cost savings; active pension streams share personal allowances and the €180,000 GESY ceiling; life-policy surrender tax and IRR use executed withdrawals and account for self-funded tax outflows. Affected results may change. Request/output fields are unchanged; refresh schemas and recalculate affected scenarios. Minimum client version remains 1.0.0. See https://poliergaleio.com/migrations/v16-0-0.
- API 15.0.0 corrects unemployment benefit: dependant increases are added as percentage points to the 60% basic rate, and the earnings-related supplement is capped at one weekly BIE. Weekly and 156-day estimates may increase; refresh schemas and recalculate affected and saved estimates. Request/output fields are unchanged; minimum client version remains 1.0.0. See https://poliergaleio.com/migrations/v15-0-0.
- API 14.0.0 corrects state-pension income tax to use the shared 2026 pension bands and aligns projected employee SI increases with the published 2029/2034/2039 schedule. Pension estimates above €32,000 and future contribution projections may change. Request/output fields are unchanged; refresh schemas and recalculate affected estimates. Minimum client version remains 1.0.0. See https://poliergaleio.com/migrations/v14-0-0.
- API 13.1.0 adds the optional `taxYear` input to `calculate_cyprus_capital_gains` (2025 or 2026, default 2026). It selects the matching lifetime exemptions and CPI cutoff: 2025 general/main-residence/agricultural allowances are €17,086/€85,430/€25,629; 2026 allowances are €30,000/€150,000/€50,000. Existing requests remain valid. Refresh cached schemas.
- API 13.0.0 is a breaking correctness release: employee Social Insurance uses qualifying employment remuneration only. Passive rental income no longer increases employee SI; rental-only income has zero employee SI, and mixed salary/rental SI is based on salary alone. Net and income-tax deduction results may change. Refresh cached schemas and recalculate/review affected estimates and saved results. Request/output fields are unchanged and the minimum client version remains 1.0.0. See https://poliergaleio.com/migrations/v13-0-0.
- API 12.0.0 is a breaking correctness release: Article 8(21A)/(23A) deductions and the 50% threshold use qualifying employment remuneration only, not aggregate income; GESY now shares one €180,000 personal ceiling across employee, self-employed, pension and income-earner categories at their applicable rates. Mixed-income tax, GESY and net results may change. Refresh cached schemas and recalculate/review affected estimates and saved results. Request/output fields are unchanged and the minimum client version remains 1.0.0. See https://poliergaleio.com/migrations/v12-0-0.
- API 3.0.0 corrected materially unsafe or demonstrably incorrect result meanings immediately; the migration documents this narrow safety/correctness exception to the normal deprecation window.
- `GET /status` is a one-call capability probe: `{ "status": "ok", "apiVersion": "17.0.0", "minimumClientVersion": "1.0.0", "toolCount": 25, "endpoints": { "policy": {...}, "migrationsLatest": {...}, "lifecycleErrorSchema": { "available": true, "url": ".../schemas/errors/lifecycle", "appliesTo": [410, 426] }, ... } }` — each entry has `available`, `url` and a description, so a client learns in one request which lifecycle surfaces this deployment exposes. Cacheable with `ETag` / `If-None-Match`.
- `GET /policy` returns the machine-readable deprecation & sunset policy plus per-tool lifecycle status (`status`, `callable`, `sunset`, `daysUntilSunset`, `replacement`, `migrationGuide`) so agents can automate upgrades. Tools past their sunset date return `410 Gone` with `code: "tool_gone"` and a replacement; stale clients sending `X-Client-Version` get `426 Upgrade Required` with the exact `/migrations/v*` guide and section links for their version.
- `GET /migrations/latest` returns the newest migration guide for MCP clients to follow: `{ "apiVersion": "17.0.0", "version": "17.0.0", "url": "https://poliergaleio.com/migrations/v17-0-0", "sections": { "whatChanged": ".../v17-0-0#what-changed", "toolChanges": ".../v17-0-0#tool-changes", "updateSteps": ".../v17-0-0#update-steps" }, "anchors": { ...same three... }, "allGuides": [{ "version": "1.7.0", "url": "...", "summary": "...", "sections": {...} }], "migrationsIndex": "https://poliergaleio.com/migrations", "minimumClientVersion": "1.0.0" }` — cacheable with `ETag` / `If-None-Match`.
- Cache `/migrations/latest`: it returns a strong `ETag` and `Cache-Control: public, max-age=300, stale-while-revalidate=86400`. Send `If-None-Match: "<stored-etag>"` to get `304 Not Modified` with no body. Copy-paste: `curl -sD - https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/migrations/latest -o latest.json` then `curl -s -o /dev/null -w '%{http_code}\n' -H 'If-None-Match: "<stored-etag>"' https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/migrations/latest`.
- Machine-validate lifecycle errors: JSON Schema 2020-12 for the shared `410 Gone` / `426 Upgrade Required` body is downloadable at `https://poliergaleio.com/poliergaleio-lifecycle-error.schema.json` and served live (cacheable) at `GET /schemas/errors/lifecycle`. Validate with `npx ajv-cli validate -s lifecycle-error.schema.json -d error-body.json --spec=draft2020`. Reproduce a 426 with `curl -s -X POST .../tools/calculate_cyprus_income_tax -H 'X-Client-Version: 0.9.0' -H 'Content-Type: application/json' -d '{"salaryIncome":45000}'`.
- Lifecycle errors share one parseable JSON shape. `410 Gone`: `{ "error": "Tool old_tool was removed on 2026-01-01 and is no longer available.", "code": "tool_gone", "tool": "old_tool", "status": "removed", "sunset": "2026-01-01", "replacement": "new_tool", "notes": "...", "migrationGuide": ".../migrations/v1-10-0", "migrationSections": { "whatChanged": "...#what-changed", "toolChanges": "...#tool-changes", "updateSteps": "...#update-steps" }, "availableTools": [...], "hint": "...", "requestId": "...", "guestId": null }` with `Deprecation: true`, `Sunset`, `X-Migration-Guide` and `Link` headers. `426 Upgrade Required`: same `tool` / `status` / `replacement` / `migrationGuide` / `migrationSections` fields plus `code: "upgrade_required"`, `clientVersion`, `minimumClientVersion`, `apiVersion`, `updateUrl`, `migrationPath`, `latestMigrationGuide` and `migrationNotes`; `tool`/`status`/`replacement` are `null` when the path names no tool.
- Rate limits are per minute, per day and per week; every response carries `X-RateLimit-*` headers and a 429 returns `{ error, retryAfter, window, limit, tier, scope, hint }`. Keyed quota is enforced per key and against the whole account, with usage retained across key deletion — `scope: "account"` means creating new keys will not help; key creation is capped at 3 new keys per 24h. Agents chaining several tools in one turn burn one call per tool — get a free key, the anonymous 10/min budget exhausts fast. Encrypted saved calculations remain locked and are never returned in plaintext through the API.
- API keys: at most 10 active keys per account; every key carries scopes `["read", "write"]` (saved-calculation tools require a key scoped to its own account). Manage keys on [Profile](/profile) — create, rename (via the rename dialog), copy the prefix per key, revoke with confirmation; the `X / 10` active-key count updates immediately. Rotate without downtime: create → switch → revoke. Common errors: 400 validation (`fieldErrors` + `hint`), 401 invalid key, 404 unknown tool/save, 429 rate limit. Full key docs plus an AI integration diagnoser (describe the problem, get likely causes + fixes via AI Gateway) live on [Developers](/developers).

### Mobile / no desktop app

- **ChatGPT Work MCP plugin**: connect `https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/mcp`. Calculators are anonymous; saved-calculation tools request PoliErgaleio OAuth sign-in. Ask the PoliErgaleio operator to register ChatGPT's exact callback URL as a confidential client at https://auth.poliergaleio.com and enter its client ID and secret in the plugin settings.
- **ChatGPT Custom GPT**: there is no official PoliErgaleio GPT. Building your own requires a Business, Enterprise or Edu workspace (personal accounts cannot create GPTs): create a GPT, enable Actions, Action 1 — import `https://poliergaleio.com/poliergaleio-chatgpt-actions.json` (19 calculators, Authentication: None), optional Action 2 — import `https://poliergaleio.com/poliergaleio-chatgpt-user-actions.json` (6 saved-calculation tools, Authentication: OAuth), then publish and share the link. The full `https://poliergaleio.com/poliergaleio-openapi.json` has 32 operations and exceeds ChatGPT's 30-operation limit (for Copilot/Poe/REST only). On a personal account, use the Claude custom connector below instead.
- **Claude custom connector**: open claude.ai or the Claude app, go to Customize → Connectors → Add custom connector, paste `https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/mcp`, optionally add the `x-api-key` header, then enable it in a new chat.

### Available tools

- `calculate_cyprus_income_tax`: Cyprus income tax, social insurance, GESY and net salary for employee or self-employed (sole proprietor) income, with 2025/2026 rules. Employee SI and Article 8(21A)/(23A) exemptions use qualifying employment remuneration only; passive rental income does not increase employee SI. A shared €180,000 personal GESY ceiling applies alongside Minds in Cyprus Art. 8(21B), year-specific foreign-pension and cryptoasset taxation, deposit-interest SDC and prepaid settlement.
- `calculate_cyprus_state_pension`: Estimate Cyprus state (contributory) pension from insurance units, contribution years, and retirement age. Uses corrected 2026 pension tax bands and published 2029/2034/2039 employee SI phase-ins in contribution projections.
- `run_retirement_stress_test`: Deterministic and Monte Carlo retirement projection given savings, contributions, drawdown, market assumptions and optional pension streams. Active streams are aggregated before applying personal allowances and the shared €180,000 GESY cap; splitting a stream does not change net income.
- `calculate_cyprus_unemployment_benefit`: Cyprus unemployment benefit based on insurable earnings and family status. Dependant additions are percentage points on the 60% basic rate; the 50% earnings-related supplement is capped at one weekly BIE.
- `calculate_cyprus_capital_gains`: Cyprus-only Capital Gains Tax on an immovable property disposal (no jurisdiction field): CPI-indexed acquisition cost and 2025/2026 year-specific lifetime exemptions. Optional `taxYear` selects 2025 (€17,086/€85,430/€25,629) or 2026 (€30,000/€150,000/€50,000) rules; defaults to 2026. Includes 20% CGT and 0.4% property transfer fee.
- `simulate_mortgage`: Full Cyprus mortgage amortisation with payment rows that reconcile cash to principal and interest. Interest-only minimums update as principal changes; the remaining principal is due at maturity.
- `calculate_stock_options`: Employee stock option taxation in Cyprus under 2025 and 2026 rules, including vesting and benefit-in-kind caps.
- `compare_rent_vs_buy`: Rent versus buy using actual mortgage payments through payoff, with symmetric investment of the lower-cost side's savings and net-wealth paths.
- `calculate_ev_savings`: Electric vehicle versus petrol/diesel running costs, including solar and grid charging tiers and payback period.
- `compare_investment_vehicles`: Taxable versus tax-deductible investment vehicle comparison, net of AUM fees and exit tax.
- `plan_monthly_budget`: Monthly budget planning with 4-tier expense categorisation, savings rate, surplus and long-term projection.
- `analyze_portfolio`: Investment portfolio performance from transaction history — invested capital, current value, time-weighted return, CAGR and allocation, with multi-currency support. Sub-portfolios also accept holdings sleeves (`type: "holdings"` with `holdings[]`, `cashBalance`, `cashLabel`) valued from EOD closes.
- `simulate_life_insurance_flush`: Cyprus life insurance partial-surrender simulation with the 2026 tax-free safe limit. Requests above available funds are capped, and tax/IRR follow executed withdrawals; self-funded surrender taxes are included in household cash flows.
- `audit_mortgage_statement`: Forensic audit of a Cyprus mortgage statement that infers the bank's interest convention and quantifies any interest overcharge.
- `optimize_company_director_remuneration`: Cyprus LTD company-director salary-vs-dividend optimizer — optimal split with corporate tax, personal taxes, employer contributions (with per-fund breakdown) and net cash. Monetary inputs are capped at €1,000,000 and solver work is bounded to 10,001 allocation evaluations. Accepts optional annualCorporateAdminCost (Cap. 113 audit/compliance, default 2000); the solver stays within the solvency-bounded maxAffordableSalary.
- Migration guide (self-employed → LTD, no new tool): `/calculator` (self-employed) shows an incorporation card only when `optimalLTD_net − sole_net > max(€500, 2% × sole_net)`; button goes to `/company-director-optimizer?from=self-employed&turnover=<n>&expenses=<n>&adminCost=2000&taxYear=<2025|2026>&nonDom=<0|1>` (shareable; non-numeric ignored, negatives clamped to 0). Optimizer page shows a 3-column matrix (Sole | Selected LTD | Optimal LTD) with Cap. 113 admin note; saved-compare at `/compare?type=company-director&left=&right=`; cross-type income-tax ↔ director renders a comparable turnover/expenses/net-cash matrix.
- `get_pension_reference_data`: Lookup official Cyprus pension reference tables (insurable earnings ceilings, pension points, statutory ages) by year.
- `parse_pension_statement`: Extract structured pension contribution history from pasted Cyprus Social Insurance statement text.
- `list_saved_calculations`: List a user's saved calculations by type (metadata only; encrypted contents are never exposed).
- `load_saved_calculation`: Load one previously saved unencrypted calculation belonging to the authenticated API key's user (encrypted saves return locked: true — open those on the site).
- `save_calculation`: Save a calculator scenario (unencrypted, results computed server-side) to the authenticated user's history.
- `update_calculation`: Rename a save and/or replace its inputs with recomputed results.
- `delete_saved_calculation`: Delete one owned save (works on encrypted saves too).
- `compare_saved_calculations`: Field-level diff of two owned saves (inputs + results) with numeric deltas.
- `parse_portfolio_csv`: Pasted broker CSV into `analyze_portfolio` transactions.
- `parse_mortgage_statement_text`: Pasted bank statement rows into `audit_mortgage_statement` inputs.

OAuth API 6.0.0: saved-data tokens are opaque, issued by https://auth.poliergaleio.com with saved_calculations scope and the exact MCP or REST audience. Supabase session tokens are rejected. Re-register clients and reconnect. API keys and public calculators remain available. See https://poliergaleio.com/migrations/v6-0-0.