@xpr-agents/openclaw 0.3.1 → 0.4.0

package/skills/tax/src/index.ts

@@ -0,0 +1,1985 @@
+/**
+ * Tax Skill — Crypto tax reporting for XPR Network
+ *
+ * All tools are read-only (query APIs + calculate).
+ * Region system: pass `region` param (default "NZ") to any tool.
+ * Adding a new region = adding an entry to REGIONS.
+ */
+
+// ── Types ────────────────────────────────────────
+
+interface ToolDef {
+  name: string;
+  description: string;
+  parameters: { type: 'object'; required?: string[]; properties: Record<string, unknown> };
+  handler: (params: any) => Promise<unknown>;
+}
+
+interface SkillApi {
+  registerTool(tool: ToolDef): void;
+  getConfig(): Record<string, unknown>;
+}
+
+// ── Region Configuration ─────────────────────────
+
+interface RegionConfig {
+  name: string;
+  code: string;
+  currency: string;
+  tax_year: { start_month: number; start_day: number };
+  cost_basis_methods: string[];
+  has_capital_gains: boolean;
+  brackets: Array<{ limit: number; rate: number }>;
+  disclaimer: string;
+}
+
+const REGIONS: Record<string, RegionConfig> = {
+  NZ: {
+    name: 'New Zealand',
+    code: 'NZ',
+    currency: 'NZD',
+    tax_year: { start_month: 4, start_day: 1 },
+    cost_basis_methods: ['fifo', 'average'],
+    has_capital_gains: false,
+    brackets: [
+      { limit: 14000, rate: 0.105 },
+      { limit: 48000, rate: 0.175 },
+      { limit: 70000, rate: 0.30 },
+      { limit: 180000, rate: 0.33 },
+      { limit: Infinity, rate: 0.39 },
+    ],
+    disclaimer: 'Estimate only. Consult a NZ tax professional. IRD requires 7 years of records.',
+  },
+  US: {
+    name: 'United States',
+    code: 'US',
+    currency: 'USD',
+    tax_year: { start_month: 1, start_day: 1 },
+    cost_basis_methods: ['fifo', 'average'],
+    has_capital_gains: true,
+    brackets: [
+      { limit: 11600, rate: 0.10 },
+      { limit: 47150, rate: 0.12 },
+      { limit: 100525, rate: 0.22 },
+      { limit: 191950, rate: 0.24 },
+      { limit: 243725, rate: 0.32 },
+      { limit: 609350, rate: 0.35 },
+      { limit: Infinity, rate: 0.37 },
+    ],
+    disclaimer: 'Estimate only — uses 2024 Single filer federal brackets. Does not include state taxes, NIIT (3.8%), or long-term capital gains rates. Short-term gains (<1 year hold) are taxed as ordinary income. Consult a US CPA or tax professional. IRS requires records for 3+ years.',
+  },
+};
+
+function getRegion(code?: string): RegionConfig {
+  const key = (code || 'NZ').toUpperCase();
+  const region = REGIONS[key];
+  if (!region) {
+    throw new Error(`Unsupported region "${key}". Supported: ${Object.keys(REGIONS).join(', ')}`);
+  }
+  return region;
+}
+
+// ── Tax Year Helpers ─────────────────────────────
+
+function getTaxYearDates(taxYear: number, region: RegionConfig): { start: string; end: string } {
+  const { start_month, start_day } = region.tax_year;
+  // Tax year "2025" in NZ = Apr 1, 2024 – Mar 31, 2025
+  const startYear = start_month > 1 ? taxYear - 1 : taxYear;
+  const endYear = start_month > 1 ? taxYear : taxYear + 1;
+  const endMonth = start_month - 1 || 12;
+  const endDay = new Date(endYear, endMonth, 0).getDate(); // last day of end month
+
+  const start = `${startYear}-${String(start_month).padStart(2, '0')}-${String(start_day).padStart(2, '0')}T00:00:00.000Z`;
+  const end = `${endYear}-${String(endMonth).padStart(2, '0')}-${String(endDay).padStart(2, '0')}T23:59:59.999Z`;
+  return { start, end };
+}
+
+// ── HTTP Helpers ─────────────────────────────────
+
+const HTTP_TIMEOUT = 20000;
+
+async function httpGet(url: string, headers?: Record<string, string>): Promise<any> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), HTTP_TIMEOUT);
+  try {
+    const resp = await fetch(url, { signal: controller.signal, headers });
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => '');
+      throw new Error(`HTTP GET ${url} failed (${resp.status}): ${text.slice(0, 200)}`);
+    }
+    return resp;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function httpGetJson(url: string, headers?: Record<string, string>): Promise<any> {
+  const resp = await httpGet(url, headers);
+  return resp.json();
+}
+
+async function httpGetText(url: string): Promise<string> {
+  const resp = await httpGet(url);
+  return resp.text();
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// ── CoinGecko ────────────────────────────────────
+
+// Auto-detect API key tier: Pro key starts with "CG-", Demo key otherwise
+function getCoinGeckoConfig(): { baseUrl: string; headers: Record<string, string>; hasKey: boolean } {
+  const apiKey = process.env.COINGECKO_API_KEY || '';
+  if (!apiKey) {
+    return { baseUrl: 'https://api.coingecko.com/api/v3', headers: {}, hasKey: false };
+  }
+  if (apiKey.startsWith('CG-')) {
+    // Pro API key
+    return {
+      baseUrl: 'https://pro-api.coingecko.com/api/v3',
+      headers: { 'x-cg-pro-api-key': apiKey },
+      hasKey: true,
+    };
+  }
+  // Demo API key (free tier with key)
+  return {
+    baseUrl: 'https://api.coingecko.com/api/v3',
+    headers: { 'x-cg-demo-api-key': apiKey },
+    hasKey: true,
+  };
+}
+
+const COINGECKO_BASE = getCoinGeckoConfig().baseUrl;
+
+const TOKEN_TO_COINGECKO: Record<string, string> = {
+  XPR: 'proton',
+  XBTC: 'bitcoin',
+  XETH: 'ethereum',
+  XDOGE: 'dogecoin',
+  METAL: 'metal-blockchain',
+  XUSDC: 'usd-coin',
+  XMD: 'usd-coin',
+  XXRP: 'ripple',
+  XLTC: 'litecoin',
+  XHBAR: 'hedera-hashgraph',
+  LOAN: 'proton-loan',
+  SLOAN: 'proton-loan',
+};
+
+const STABLECOINS = new Set(['XUSDC', 'XMD', 'USDT']);
+
+// CoinGecko fetch with API key headers
+async function cgFetch(path: string): Promise<any> {
+  const cg = getCoinGeckoConfig();
+  return httpGetJson(`${cg.baseUrl}${path}`, cg.headers);
+}
+
+// Persistent rate cache: "SYMBOL:YYYY-MM-DD" → rate
+// Historical prices are immutable — once fetched they never change.
+// Stored as JSON file so rates survive container restarts.
+import * as fs from 'fs';
+import * as path from 'path';
+
+const RATE_CACHE_FILE = process.env.RATE_CACHE_PATH || path.join(process.cwd(), 'data', 'rate-cache.json');
+const rateCache = new Map<string, number>();
+let rateCacheDirty = false;
+
+function loadRateCache(): void {
+  try {
+    if (fs.existsSync(RATE_CACHE_FILE)) {
+      const data = JSON.parse(fs.readFileSync(RATE_CACHE_FILE, 'utf-8'));
+      for (const [k, v] of Object.entries(data)) {
+        if (typeof v === 'number' && v > 0) rateCache.set(k, v);
+      }
+      console.log(`[tax] Loaded ${rateCache.size} cached rates from ${RATE_CACHE_FILE}`);
+    }
+  } catch { /* start fresh */ }
+}
+
+function saveRateCache(): void {
+  if (!rateCacheDirty) return;
+  try {
+    const dir = path.dirname(RATE_CACHE_FILE);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const obj: Record<string, number> = {};
+    for (const [k, v] of rateCache) obj[k] = v;
+    fs.writeFileSync(RATE_CACHE_FILE, JSON.stringify(obj));
+    rateCacheDirty = false;
+  } catch (err) {
+    console.error(`[tax] Failed to save rate cache:`, err);
+  }
+}
+
+function cacheRate(key: string, rate: number): void {
+  // Only cache historical date rates (not "current")
+  if (key.includes(':current') || rate <= 0) return;
+  rateCache.set(key, rate);
+  rateCacheDirty = true;
+}
+
+// Load on startup
+loadRateCache();
+
+// ── CSV Parser ───────────────────────────────────
+
+function parseCSV(csv: string): Array<Record<string, string>> {
+  const lines = csv.trim().split('\n');
+  if (lines.length < 2) return [];
+  const headers = lines[0].split(',').map(h => h.trim().replace(/^"|"$/g, ''));
+  const rows: Array<Record<string, string>> = [];
+  for (let i = 1; i < lines.length; i++) {
+    const values = lines[i].split(',').map(v => v.trim().replace(/^"|"$/g, ''));
+    const row: Record<string, string> = {};
+    for (let j = 0; j < headers.length; j++) {
+      row[headers[j]] = values[j] || '';
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+
+// ── Transfer Categorization ──────────────────────
+
+interface CategorizedTransfer {
+  category: string;
+  from: string;
+  to: string;
+  amount: number;
+  symbol: string;
+  memo: string;
+  timestamp: string;
+  tx_id: string;
+  direction: 'incoming' | 'outgoing';
+}
+
+function categorizeTransfer(
+  account: string,
+  from: string,
+  to: string,
+  amount: number,
+  symbol: string,
+  memo: string,
+): string {
+  const memoLower = (memo || '').toLowerCase();
+  const isIncoming = to === account;
+  const counterparty = isIncoming ? from : to;
+
+  // Staking rewards (block production + community fund)
+  if (isIncoming && (from === 'eosio' || from === 'eosio.vpay' || from === 'eosio.bpay' || from === 'cfund.proton')) {
+    return 'staking_reward';
+  }
+
+  // Lending (lending.loan)
+  if (counterparty === 'lending.loan') {
+    if (isIncoming) {
+      if (memoLower.includes('interest') || memoLower.includes('reward') || memoLower.includes('yield')) {
+        return 'lending_interest';
+      }
+      return 'lending_withdrawal';
+    }
+    return 'lending_deposit';
+  }
+
+  // Swaps (proton.swaps)
+  if (counterparty === 'proton.swaps') {
+    return isIncoming ? 'swap_withdrawal' : 'swap_deposit';
+  }
+
+  // Long staking XPR (longstaking contract)
+  if (counterparty === 'longstaking') {
+    return isIncoming ? 'long_unstake' : 'long_stake';
+  }
+
+  // LOAN staking (lock.token + yield.farms)
+  if (counterparty === 'lock.token' || counterparty === 'yield.farms') {
+    return isIncoming ? 'loan_unstake' : 'loan_stake';
+  }
+
+  // DEX (Metal X)
+  if (counterparty === 'dex' || counterparty === 'metalx') {
+    return isIncoming ? 'dex_withdrawal' : 'dex_deposit';
+  }
+
+  // NFT marketplace
+  if (counterparty === 'atomicmarket') {
+    return isIncoming ? 'nft_sale' : 'nft_purchase';
+  }
+
+  // Agent escrow
+  if (counterparty === 'agentescrow') {
+    return 'escrow';
+  }
+
+  // Burned tokens — disposal at zero value = realized loss
+  if (to === 'eosio.null') {
+    return 'burn';
+  }
+
+  return 'transfer';
+}
+
+// ── Gains Calculation ────────────────────────────
+
+interface TradeEvent {
+  type: 'trade';
+  date: string;
+  buy_amount: number;
+  buy_currency: string;
+  sell_amount: number;
+  sell_currency: string;
+  fee?: number;
+  fee_currency?: string;
+  tx_id?: string;
+}
+
+interface TransferEvent {
+  type: 'transfer';
+  date: string;
+  category: string;
+  amount: number;
+  symbol: string;
+  direction: 'incoming' | 'outgoing';
+  tx_id?: string;
+}
+
+interface Disposal {
+  date: string;
+  asset: string;
+  amount: number;
+  proceeds_local: number;
+  cost_basis_local: number;
+  gain_loss_local: number;
+  method: string;
+  tx_id?: string;
+}
+
+interface IncomeEvent {
+  date: string;
+  category: string;
+  asset: string;
+  amount: number;
+  value_local: number;
+  tx_id?: string;
+}
+
+interface GainsResult {
+  disposals: Disposal[];
+  income_events: IncomeEvent[];
+  summary: {
+    total_proceeds: number;
+    total_cost_basis: number;
+    total_gains: number;
+    total_losses: number;
+    net_gain_loss: number;
+    total_income: number;
+    grand_total_taxable: number;
+  };
+  remaining_lots: Record<string, Array<{ amount: number; cost_per_unit: number; date: string }>>;
+  method: string;
+  currency: string;
+}
+
+type RateMap = Record<string, number>; // "SYMBOL:YYYY-MM-DD" → local currency rate
+
+function dateKey(date: string): string {
+  return date.slice(0, 10); // YYYY-MM-DD
+}
+
+function getRate(rates: RateMap, symbol: string, date: string): number {
+  const key = `${symbol}:${dateKey(date)}`;
+  return rates[key] || rates[`${symbol}:current`] || 0;
+}
+
+// Income categories: these incoming transfers are taxable income
+const INCOME_CATEGORIES = new Set([
+  'staking_reward', 'lending_interest', 'nft_sale',
+]);
+
+// Long staking is special: only the EXCESS over what was staked is income.
+// We track deposits and only count the surplus on unstake.
+// Same for loan staking.
+const LONG_STAKE_INCOME = new Set(['long_unstake', 'loan_unstake']);
+
+// DeFi movements: not taxable events (moving between own wallets/protocols)
+const DEFI_MOVE_CATEGORIES = new Set([
+  'lending_deposit', 'lending_withdrawal',
+  'swap_deposit', 'swap_withdrawal',
+  'long_stake', 'long_unstake',
+  'loan_stake', 'loan_unstake',
+  'dex_deposit', 'dex_withdrawal',
+  'escrow',
+]);
+
+function calculateGainsFIFO(
+  trades: TradeEvent[],
+  transfers: TransferEvent[],
+  rates: RateMap,
+  currency: string,
+): GainsResult {
+  // Lot queues: asset → [{ amount, cost_per_unit, date }]
+  const lots: Record<string, Array<{ amount: number; cost_per_unit: number; date: string }>> = {};
+  const disposals: Disposal[] = [];
+  const incomeEvents: IncomeEvent[] = [];
+
+  // Track long staking / loan staking deposits per symbol to compute excess on unstake
+  const stakeDeposits: Record<string, number> = {}; // "long:SYMBOL" or "loan:SYMBOL" → total staked
+
+  function addLot(asset: string, amount: number, costPerUnit: number, date: string): void {
+    if (!lots[asset]) lots[asset] = [];
+    lots[asset].push({ amount, cost_per_unit: costPerUnit, date });
+  }
+
+  function consumeLots(asset: string, amount: number): number {
+    const queue = lots[asset] || [];
+    let remaining = amount;
+    let totalCost = 0;
+    while (remaining > 0 && queue.length > 0) {
+      const lot = queue[0];
+      if (lot.amount <= remaining) {
+        totalCost += lot.amount * lot.cost_per_unit;
+        remaining -= lot.amount;
+        queue.shift();
+      } else {
+        totalCost += remaining * lot.cost_per_unit;
+        lot.amount -= remaining;
+        remaining = 0;
+      }
+    }
+    return totalCost;
+  }
+
+  // Merge and sort all events chronologically
+  const events: Array<{ date: string; event: TradeEvent | TransferEvent }> = [
+    ...trades.map(t => ({ date: t.date, event: t })),
+    ...transfers.map(t => ({ date: t.date, event: t })),
+  ];
+  events.sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
+
+  let totalProceeds = 0;
+  let totalCostBasis = 0;
+  let totalGains = 0;
+  let totalLosses = 0;
+  let totalIncome = 0;
+
+  for (const { event } of events) {
+    if (event.type === 'trade') {
+      const trade = event as TradeEvent;
+      const buyRate = getRate(rates, trade.buy_currency, trade.date);
+      const sellRate = getRate(rates, trade.sell_currency, trade.date);
+
+      // Disposal of sell currency
+      const proceeds = trade.sell_amount * sellRate;
+      const costBasis = consumeLots(trade.sell_currency, trade.sell_amount);
+      const gainLoss = proceeds - costBasis;
+
+      disposals.push({
+        date: trade.date,
+        asset: trade.sell_currency,
+        amount: trade.sell_amount,
+        proceeds_local: proceeds,
+        cost_basis_local: costBasis,
+        gain_loss_local: gainLoss,
+        method: 'fifo',
+        tx_id: trade.tx_id,
+      });
+
+      totalProceeds += proceeds;
+      totalCostBasis += costBasis;
+      if (gainLoss > 0) totalGains += gainLoss;
+      else totalLosses += Math.abs(gainLoss);
+
+      // Acquisition of buy currency
+      addLot(trade.buy_currency, trade.buy_amount, buyRate, trade.date);
+
+    } else {
+      const xfer = event as TransferEvent;
+      const rate = getRate(rates, xfer.symbol, xfer.date);
+
+      if (xfer.direction === 'incoming') {
+        // Income categories: record as income + create cost basis lot
+        if (INCOME_CATEGORIES.has(xfer.category)) {
+          const value = xfer.amount * rate;
+          incomeEvents.push({
+            date: xfer.date,
+            category: xfer.category,
+            asset: xfer.symbol,
+            amount: xfer.amount,
+            value_local: value,
+            tx_id: xfer.tx_id,
+          });
+          totalIncome += value;
+          addLot(xfer.symbol, xfer.amount, rate, xfer.date);
+
+        } else if (LONG_STAKE_INCOME.has(xfer.category)) {
+          // Long staking / loan staking unstake — only the EXCESS over deposits is income
+          // (e.g. stake 100 XPR, unstake 150 XPR → income of 50 XPR)
+          const stakeKey = xfer.category === 'long_unstake' ? `long:${xfer.symbol}` : `loan:${xfer.symbol}`;
+          const deposited = stakeDeposits[stakeKey] || 0;
+          const excess = Math.max(0, xfer.amount - deposited);
+
+          // Reduce tracked deposits by the principal portion returned
+          stakeDeposits[stakeKey] = Math.max(0, deposited - (xfer.amount - excess));
+
+          if (excess > 0) {
+            const value = excess * rate;
+            incomeEvents.push({
+              date: xfer.date,
+              category: xfer.category === 'long_unstake' ? 'long_staking_reward' : 'loan_staking_reward',
+              asset: xfer.symbol,
+              amount: excess,
+              value_local: value,
+              tx_id: xfer.tx_id,
+            });
+            totalIncome += value;
+          }
+          // Full amount returns as cost basis (principal at original cost, excess at current rate)
+          addLot(xfer.symbol, xfer.amount, rate, xfer.date);
+
+        } else if (!DEFI_MOVE_CATEGORIES.has(xfer.category)) {
+          // Regular incoming transfer — cost basis acquisition
+          addLot(xfer.symbol, xfer.amount, rate, xfer.date);
+        }
+        // DeFi moves (deposit/withdrawal) are not taxable events
+      } else {
+        // Outgoing transfer
+
+        // Track long staking / loan staking deposits for excess calculation
+        if (xfer.category === 'long_stake') {
+          const key = `long:${xfer.symbol}`;
+          stakeDeposits[key] = (stakeDeposits[key] || 0) + xfer.amount;
+        } else if (xfer.category === 'loan_stake') {
+          const key = `loan:${xfer.symbol}`;
+          stakeDeposits[key] = (stakeDeposits[key] || 0) + xfer.amount;
+        }
+
+        // Burn = disposal at zero proceeds (realized loss)
+        if (xfer.category === 'burn') {
+          const costBasis = consumeLots(xfer.symbol, xfer.amount);
+          disposals.push({
+            date: xfer.date,
+            asset: xfer.symbol,
+            amount: xfer.amount,
+            proceeds_local: 0,
+            cost_basis_local: costBasis,
+            gain_loss_local: -costBasis,
+            method: 'fifo',
+            tx_id: xfer.tx_id,
+          });
+          totalCostBasis += costBasis;
+          totalLosses += costBasis;
+        } else if (!DEFI_MOVE_CATEGORIES.has(xfer.category)) {
+          // Disposal (sending to someone else)
+          const proceeds = xfer.amount * rate;
+          const costBasis = consumeLots(xfer.symbol, xfer.amount);
+          const gainLoss = proceeds - costBasis;
+
+          disposals.push({
+            date: xfer.date,
+            asset: xfer.symbol,
+            amount: xfer.amount,
+            proceeds_local: proceeds,
+            cost_basis_local: costBasis,
+            gain_loss_local: gainLoss,
+            method: 'fifo',
+            tx_id: xfer.tx_id,
+          });
+
+          totalProceeds += proceeds;
+          totalCostBasis += costBasis;
+          if (gainLoss > 0) totalGains += gainLoss;
+          else totalLosses += Math.abs(gainLoss);
+        }
+      }
+    }
+  }
+
+  return {
+    disposals,
+    income_events: incomeEvents,
+    summary: {
+      total_proceeds: round2(totalProceeds),
+      total_cost_basis: round2(totalCostBasis),
+      total_gains: round2(totalGains),
+      total_losses: round2(totalLosses),
+      net_gain_loss: round2(totalGains - totalLosses),
+      total_income: round2(totalIncome),
+      grand_total_taxable: round2(totalGains - totalLosses + totalIncome),
+    },
+    remaining_lots: lots,
+    method: 'fifo',
+    currency,
+  };
+}
+
+function calculateGainsAverage(
+  trades: TradeEvent[],
+  transfers: TransferEvent[],
+  rates: RateMap,
+  currency: string,
+): GainsResult {
+  // Average cost per asset
+  const holdings: Record<string, { total_amount: number; total_cost: number }> = {};
+  const disposals: Disposal[] = [];
+  const incomeEvents: IncomeEvent[] = [];
+
+  // Track long staking / loan staking deposits per symbol to compute excess on unstake
+  const stakeDeposits: Record<string, number> = {};
+
+  function addHolding(asset: string, amount: number, cost: number): void {
+    if (!holdings[asset]) holdings[asset] = { total_amount: 0, total_cost: 0 };
+    holdings[asset].total_amount += amount;
+    holdings[asset].total_cost += cost;
+  }
+
+  function avgCostPerUnit(asset: string): number {
+    const h = holdings[asset];
+    if (!h || h.total_amount <= 0) return 0;
+    return h.total_cost / h.total_amount;
+  }
+
+  function consumeAvg(asset: string, amount: number): number {
+    const h = holdings[asset];
+    if (!h || h.total_amount <= 0) return 0;
+    const costPerUnit = h.total_cost / h.total_amount;
+    const consumed = Math.min(amount, h.total_amount);
+    const cost = consumed * costPerUnit;
+    h.total_amount -= consumed;
+    h.total_cost -= cost;
+    return cost;
+  }
+
+  const events: Array<{ date: string; event: TradeEvent | TransferEvent }> = [
+    ...trades.map(t => ({ date: t.date, event: t })),
+    ...transfers.map(t => ({ date: t.date, event: t })),
+  ];
+  events.sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
+
+  let totalProceeds = 0;
+  let totalCostBasis = 0;
+  let totalGains = 0;
+  let totalLosses = 0;
+  let totalIncome = 0;
+
+  for (const { event } of events) {
+    if (event.type === 'trade') {
+      const trade = event as TradeEvent;
+      const buyRate = getRate(rates, trade.buy_currency, trade.date);
+      const sellRate = getRate(rates, trade.sell_currency, trade.date);
+
+      const proceeds = trade.sell_amount * sellRate;
+      const costBasis = consumeAvg(trade.sell_currency, trade.sell_amount);
+      const gainLoss = proceeds - costBasis;
+
+      disposals.push({
+        date: trade.date,
+        asset: trade.sell_currency,
+        amount: trade.sell_amount,
+        proceeds_local: proceeds,
+        cost_basis_local: costBasis,
+        gain_loss_local: gainLoss,
+        method: 'average',
+        tx_id: trade.tx_id,
+      });
+
+      totalProceeds += proceeds;
+      totalCostBasis += costBasis;
+      if (gainLoss > 0) totalGains += gainLoss;
+      else totalLosses += Math.abs(gainLoss);
+
+      addHolding(trade.buy_currency, trade.buy_amount, trade.buy_amount * buyRate);
+
+    } else {
+      const xfer = event as TransferEvent;
+      const rate = getRate(rates, xfer.symbol, xfer.date);
+
+      if (xfer.direction === 'incoming') {
+        if (INCOME_CATEGORIES.has(xfer.category)) {
+          const value = xfer.amount * rate;
+          incomeEvents.push({
+            date: xfer.date,
+            category: xfer.category,
+            asset: xfer.symbol,
+            amount: xfer.amount,
+            value_local: value,
+            tx_id: xfer.tx_id,
+          });
+          totalIncome += value;
+          addHolding(xfer.symbol, xfer.amount, value);
+
+        } else if (LONG_STAKE_INCOME.has(xfer.category)) {
+          // Long staking / loan staking unstake — only the EXCESS over deposits is income
+          const stakeKey = xfer.category === 'long_unstake' ? `long:${xfer.symbol}` : `loan:${xfer.symbol}`;
+          const deposited = stakeDeposits[stakeKey] || 0;
+          const excess = Math.max(0, xfer.amount - deposited);
+          stakeDeposits[stakeKey] = Math.max(0, deposited - (xfer.amount - excess));
+
+          if (excess > 0) {
+            const value = excess * rate;
+            incomeEvents.push({
+              date: xfer.date,
+              category: xfer.category === 'long_unstake' ? 'long_staking_reward' : 'loan_staking_reward',
+              asset: xfer.symbol,
+              amount: excess,
+              value_local: value,
+              tx_id: xfer.tx_id,
+            });
+            totalIncome += value;
+          }
+          addHolding(xfer.symbol, xfer.amount, xfer.amount * rate);
+
+        } else if (!DEFI_MOVE_CATEGORIES.has(xfer.category)) {
+          addHolding(xfer.symbol, xfer.amount, xfer.amount * rate);
+        }
+      } else {
+        // Track staking deposits
+        if (xfer.category === 'long_stake') {
+          stakeDeposits[`long:${xfer.symbol}`] = (stakeDeposits[`long:${xfer.symbol}`] || 0) + xfer.amount;
+        } else if (xfer.category === 'loan_stake') {
+          stakeDeposits[`loan:${xfer.symbol}`] = (stakeDeposits[`loan:${xfer.symbol}`] || 0) + xfer.amount;
+        }
+
+        // Burn = disposal at zero proceeds (realized loss)
+        if (xfer.category === 'burn') {
+          const costBasis = consumeAvg(xfer.symbol, xfer.amount);
+          disposals.push({
+            date: xfer.date,
+            asset: xfer.symbol,
+            amount: xfer.amount,
+            proceeds_local: 0,
+            cost_basis_local: costBasis,
+            gain_loss_local: -costBasis,
+            method: 'average',
+            tx_id: xfer.tx_id,
+          });
+          totalCostBasis += costBasis;
+          totalLosses += costBasis;
+        } else if (!DEFI_MOVE_CATEGORIES.has(xfer.category)) {
+          const proceeds = xfer.amount * rate;
+          const costBasis = consumeAvg(xfer.symbol, xfer.amount);
+          const gainLoss = proceeds - costBasis;
+
+          disposals.push({
+            date: xfer.date,
+            asset: xfer.symbol,
+            amount: xfer.amount,
+            proceeds_local: proceeds,
+            cost_basis_local: costBasis,
+            gain_loss_local: gainLoss,
+            method: 'average',
+            tx_id: xfer.tx_id,
+          });
+
+          totalProceeds += proceeds;
+          totalCostBasis += costBasis;
+          if (gainLoss > 0) totalGains += gainLoss;
+          else totalLosses += Math.abs(gainLoss);
+        }
+      }
+    }
+  }
+
+  // Convert remaining holdings to lot-like format
+  const remainingLots: Record<string, Array<{ amount: number; cost_per_unit: number; date: string }>> = {};
+  for (const [asset, h] of Object.entries(holdings)) {
+    if (h.total_amount > 0) {
+      remainingLots[asset] = [{ amount: h.total_amount, cost_per_unit: avgCostPerUnit(asset), date: 'average' }];
+    }
+  }
+
+  return {
+    disposals,
+    income_events: incomeEvents,
+    summary: {
+      total_proceeds: round2(totalProceeds),
+      total_cost_basis: round2(totalCostBasis),
+      total_gains: round2(totalGains),
+      total_losses: round2(totalLosses),
+      net_gain_loss: round2(totalGains - totalLosses),
+      total_income: round2(totalIncome),
+      grand_total_taxable: round2(totalGains - totalLosses + totalIncome),
+    },
+    remaining_lots: remainingLots,
+    method: 'average',
+    currency,
+  };
+}
+
+function round2(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+// ── Tax Bracket Calculation ──────────────────────
+
+function calculateTax(taxableIncome: number, region: RegionConfig): Array<{ bracket: string; income: number; rate: number; tax: number }> {
+  const result: Array<{ bracket: string; income: number; rate: number; tax: number }> = [];
+  let remaining = taxableIncome;
+  let prevLimit = 0;
+
+  for (const { limit, rate } of region.brackets) {
+    if (remaining <= 0) break;
+    const bracketSize = limit === Infinity ? remaining : Math.min(remaining, limit - prevLimit);
+    if (bracketSize <= 0) {
+      prevLimit = limit;
+      continue;
+    }
+    const tax = bracketSize * rate;
+    const bracketLabel = limit === Infinity
+      ? `$${prevLimit.toLocaleString()}+`
+      : `$${prevLimit.toLocaleString()} – $${limit.toLocaleString()}`;
+    result.push({ bracket: bracketLabel, income: round2(bracketSize), rate, tax: round2(tax) });
+    remaining -= bracketSize;
+    prevLimit = limit;
+  }
+
+  return result;
+}
+
+// ── Balance Markdown Formatter ───────────────────
+
+function formatBalancesMarkdown(balances: any): string {
+  if (!balances || balances.error) {
+    return `*Data unavailable${balances?.error ? `: ${balances.error}` : ''}*`;
+  }
+
+  // Handle both grouped format { liquid: [], staked: [] } and flat API response { balances: [] }
+  let grouped: Record<string, any[]>;
+  if (balances.liquid || balances.staked || balances.lending || balances.yield_farm) {
+    grouped = balances;
+  } else if (Array.isArray(balances.balances)) {
+    grouped = { liquid: [], staked: [], lending: [], yield_farm: [] };
+    for (const item of balances.balances) {
+      const t = (item.type || 'liquid').toLowerCase().replace(/ /g, '_');
+      const bucket = grouped[t] || (grouped[t] = []);
+      bucket.push(item);
+    }
+  } else {
+    return '*No balances found*';
+  }
+
+  const lines: string[] = [];
+
+  const formatGroup = (name: string, items: any[]) => {
+    if (!Array.isArray(items) || items.length === 0) return;
+    lines.push(`**${name}:**`);
+    lines.push('');
+    lines.push('| Token | Amount |');
+    lines.push('|-------|-------:|');
+    for (const item of items) {
+      if (typeof item === 'string') {
+        lines.push(`| ${item.split(' ')[1] || '?'} | ${item} |`);
+      } else {
+        const sym = item.currency || item.symbol || '?';
+        const display = item.display || item.amount || item.quantity || item.balance || '?';
+        lines.push(`| ${sym} | ${display} |`);
+      }
+    }
+    lines.push('');
+  };
+
+  formatGroup('Liquid', grouped.liquid);
+  formatGroup('Staked', grouped.staked);
+  formatGroup('Lending', grouped.lending);
+  formatGroup('Yield Farm', grouped.yield_farm);
+
+  return lines.length > 0 ? lines.join('\n') : '*No balances found*';
+}
+
+// ── Skill Entry Point ────────────────────────────
+
+export default function taxSkill(api: SkillApi): void {
+  const SALTANT_BASE = 'https://api-xprnetwork-main.saltant.io';
+  const METALX_TAX_BASE = 'https://dex.api.mainnet.metalx.com';
+
+  // ════════════════════════════════════════════════
+  // 1. tax_get_balances
+  // ════════════════════════════════════════════════
+
+  api.registerTool({
+    name: 'tax_get_balances',
+    description: 'Get token balances at a specific date (or now). Returns liquid, staked, lending (with underlying), and yield farm balances. Uses mainnet Saltant historical balance API.',
+    parameters: {
+      type: 'object',
+      required: ['account'],
+      properties: {
+        account: { type: 'string', description: 'XPR Network account name' },
+        date: { type: 'string', description: 'ISO 8601 date for historical snapshot (default: now). E.g. "2025-03-31T23:59:59Z"' },
+      },
+    },
+    handler: async ({ account, date }: { account: string; date?: string }) => {
+      if (!account || typeof account !== 'string') {
+        return { error: 'account parameter is required' };
+      }
+
+      try {
+        let url = `${SALTANT_BASE}/v2/state/get_balance?account=${encodeURIComponent(account)}`;
+        if (date) {
+          url += `&datetime=${encodeURIComponent(date)}`;
+        }
+
+        const data = await httpGetJson(url);
+
+        // API returns { balances: [{ type, symbol, amount, ... }] } — group by type
+        const rawBalances: any[] = data.balances || data.liquid || [];
+        const balances: Record<string, any[]> = {
+          liquid: [],
+          staked: [],
+          lending: [],
+          yield_farm: [],
+        };
+
+        const tokenSet = new Set<string>();
+        for (const item of rawBalances) {
+          const balType = (item.type || 'liquid').toLowerCase().replace(/ /g, '_');
+          const sym = item.currency || item.symbol || '';
+          if (sym) tokenSet.add(sym);
+          const bucket = balances[balType] || (balances[balType] = []);
+          bucket.push(item);
+        }
+
+        return {
+          account,
+          date: date || new Date().toISOString(),
+          balances,
+          tokens_found: tokenSet.size,
+          token_list: [...tokenSet].sort(),
+        };
+      } catch (err: any) {
+        return { error: `Failed to fetch balances: ${err.message}` };
+      }
+    },
+  });
+
+  // ════════════════════════════════════════════════
+  // 2. tax_get_dex_trades
+  // ════════════════════════════════════════════════
+
+  api.registerTool({
+    name: 'tax_get_dex_trades',
+    description: 'Get Metal X DEX trading history for an account. Returns all trades with buy/sell amounts, currencies, fees, and dates. Date filtering is client-side on the full export.',
+    parameters: {
+      type: 'object',
+      required: ['account'],
+      properties: {
+        account: { type: 'string', description: 'XPR Network account name' },
+        start_date: { type: 'string', description: 'Filter trades after this ISO date (inclusive)' },
+        end_date: { type: 'string', description: 'Filter trades before this ISO date (inclusive)' },
+      },
+    },
+    handler: async ({ account, start_date, end_date }: {
+      account: string; start_date?: string; end_date?: string;
+    }) => {
+      if (!account || typeof account !== 'string') {
+        return { error: 'account parameter is required' };
+      }
+
+      try {
+        const url = `${METALX_TAX_BASE}/dex/v1/tax/user?account=${encodeURIComponent(account)}`;
+        const csvText = await httpGetText(url);
+
+        if (!csvText || csvText.trim().length === 0) {
+          return { trades: [], total: 0, note: 'No trading history found' };
+        }
+
+        const rows = parseCSV(csvText);
+        if (rows.length === 0) {
+          return { trades: [], total: 0, note: 'CSV parsed but no data rows found' };
+        }
+
+        // Map CSV columns to trade objects
+        // Expected columns: Type, Buy Amount, Buy Currency, Sell Amount, Sell Currency, Fee, Fee Currency, Date, Tx-ID
+        // Filter to only "Trade" rows — Withdrawal/Income/Deposit are handled by tax_get_transfers
+        let trades = rows
+          .filter(row => (row['Type'] || row['type'] || '').toLowerCase() === 'trade')
+          .map(row => ({
+            type: row['Type'] || row['type'] || '',
+            buy_amount: parseFloat(row['Buy Amount'] || row['buy_amount'] || '0'),
+            buy_currency: row['Buy Currency'] || row['buy_currency'] || '',
+            sell_amount: parseFloat(row['Sell Amount'] || row['sell_amount'] || '0'),
+            sell_currency: row['Sell Currency'] || row['sell_currency'] || '',
+            fee: parseFloat(row['Fee'] || row['fee'] || '0'),
+            fee_currency: row['Fee Currency'] || row['fee_currency'] || '',
+            date: row['Date'] || row['date'] || '',
+            tx_id: row['Tx-ID'] || row['TxId'] || row['txid'] || row['tx_id'] || '',
+          }));
+
+        // Client-side date filtering
+        if (start_date) {
+          const startMs = new Date(start_date).getTime();
+          trades = trades.filter(t => new Date(t.date).getTime() >= startMs);
+        }
+        if (end_date) {
+          const endMs = new Date(end_date).getTime();
+          trades = trades.filter(t => new Date(t.date).getTime() <= endMs);
+        }
+
+        // Volume summary
+        const volumeByCurrency: Record<string, number> = {};
+        for (const t of trades) {
+          if (t.sell_currency) {
+            volumeByCurrency[t.sell_currency] = (volumeByCurrency[t.sell_currency] || 0) + t.sell_amount;
+          }
+        }
+
+        return {
+          trades,
+          total: trades.length,
+          volume_by_currency: volumeByCurrency,
+          date_range: trades.length > 0
+            ? { earliest: trades[0].date, latest: trades[trades.length - 1].date }
+            : null,
+        };
+      } catch (err: any) {
+        return { error: `Failed to fetch DEX trades: ${err.message}` };
+      }
+    },
+  });
+
+  // ════════════════════════════════════════════════
+  // 3. tax_get_transfers
+  // ════════════════════════════════════════════════
+
+  api.registerTool({
+    name: 'tax_get_transfers',
+    description: 'Get on-chain transfer history with automatic categorization. Categories: staking_reward, lending_deposit/withdrawal/interest, swap_deposit/withdrawal, long_stake/unstake, loan_stake/unstake, dex_deposit/withdrawal, nft_sale/purchase, burn, escrow, transfer. Paginated from Hyperion.',
+    parameters: {
+      type: 'object',
+      required: ['account'],
+      properties: {
+        account: { type: 'string', description: 'XPR Network account name' },
+        start_date: { type: 'string', description: 'Filter after this ISO date' },
+        end_date: { type: 'string', description: 'Filter before this ISO date' },
+        max_results: { type: 'number', description: 'Max transfers to return (default 1000, max 5000)' },
+      },
+    },
+    handler: async ({ account, start_date, end_date, max_results }: {
+      account: string; start_date?: string; end_date?: string; max_results?: number;
+    }) => {
+      if (!account || typeof account !== 'string') {
+        return { error: 'account parameter is required' };
+      }
+
+      const limit = Math.min(max_results || 1000, 5000);
+      const pageSize = 100;
+      const allTransfers: CategorizedTransfer[] = [];
+
+      try {
+        let skip = 0;
+        let hasMore = true;
+
+        while (hasMore && allTransfers.length < limit) {
+          let url = `${SALTANT_BASE}/v2/history/get_actions?account=${encodeURIComponent(account)}&act.name=transfer&limit=100&sort=asc&skip=${skip}`;
+          if (start_date) url += `&after=${encodeURIComponent(start_date)}`;
+          if (end_date) url += `&before=${encodeURIComponent(end_date)}`;
+
+          const data = await httpGetJson(url);
+          const actions: any[] = data.actions || [];
+
+          if (actions.length === 0) {
+            hasMore = false;
+            break;
+          }
+
+          for (const action of actions) {
+            if (allTransfers.length >= limit) break;
+
+            const act = action.act?.data || {};
+            const from = act.from || '';
+            const to = act.to || '';
+            const memo = act.memo || '';
+
+            // Parse amount: "100.0000 XPR" → { amount: 100, symbol: "XPR" }
+            const quantityStr = act.quantity || '0 UNKNOWN';
+            const parts = quantityStr.split(' ');
+            const amount = parseFloat(parts[0]) || 0;
+            const symbol = parts[1] || 'UNKNOWN';
+
+            if (amount === 0) continue;
+
+            const category = categorizeTransfer(account, from, to, amount, symbol, memo);
+            const direction: 'incoming' | 'outgoing' = to === account ? 'incoming' : 'outgoing';
+            const timestamp = action['@timestamp'] || action.timestamp || '';
+
+            allTransfers.push({
+              category,
+              from,
+              to,
+              amount,
+              symbol,
+              memo,
+              timestamp,
+              tx_id: action.trx_id || '',
+              direction,
+            });
+          }
+
+          skip += actions.length;
+          if (actions.length < pageSize) hasMore = false;
+        }
+
+        // Summary by category
+        const byCategory: Record<string, number> = {};
+        const bySymbol: Record<string, { incoming: number; outgoing: number }> = {};
+        for (const t of allTransfers) {
+          byCategory[t.category] = (byCategory[t.category] || 0) + 1;
+          if (!bySymbol[t.symbol]) bySymbol[t.symbol] = { incoming: 0, outgoing: 0 };
+          bySymbol[t.symbol][t.direction] += t.amount;
+        }
+
+        return {
+          transfers: allTransfers,
+          total: allTransfers.length,
+          summary_by_category: byCategory,
+          summary_by_symbol: bySymbol,
+          truncated: allTransfers.length >= limit,
+        };
+      } catch (err: any) {
+        return { error: `Failed to fetch transfers: ${err.message}` };
+      }
+    },
+  });
+
+  // ════════════════════════════════════════════════
+  // 4. tax_get_rates
+  // ════════════════════════════════════════════════
+
+  api.registerTool({
+    name: 'tax_get_rates',
+    description: 'Get local currency conversion rates for crypto tokens. Uses CoinGecko for major tokens, forex for stablecoins. Supports current and historical rates. Returns a map of "SYMBOL:date" → rate.',
+    parameters: {
+      type: 'object',
+      required: ['symbols'],
+      properties: {
+        symbols: {
+          type: 'array',
+          description: 'Array of token symbols to get rates for, e.g. ["XPR", "XUSDC", "XBTC"]',
+        },
+        date: { type: 'string', description: 'ISO date for historical rate (default: current). E.g. "2025-03-31"' },
+        region: { type: 'string', description: 'Region code: "NZ" (default, NZD) or "US" (USD)' },
+      },
+    },
+    handler: async ({ symbols, date, region }: {
+      symbols: string[]; date?: string; region?: string;
+    }) => {
+      if (!Array.isArray(symbols) || symbols.length === 0) {
+        return { error: 'symbols must be a non-empty array of token symbols' };
+      }
+
+      const regionConfig = getRegion(region);
+      const currency = regionConfig.currency.toLowerCase();
+      const rates: Record<string, number> = {};
+      const errors: string[] = [];
+
+      // Separate stablecoins from others
+      const stableSymbols = symbols.filter(s => STABLECOINS.has(s.toUpperCase()));
+      const cryptoSymbols = symbols.filter(s => !STABLECOINS.has(s.toUpperCase()));
+
+      // Get USD → local forex rate upfront (needed for stablecoins AND USD fallback)
+      let forexRate = 1;
+      if (currency !== 'usd') {
+        try {
+          const forexData = await cgFetch(`/simple/price?ids=usd-coin&vs_currencies=${currency}`);
+          forexRate = forexData['usd-coin']?.[currency] || 1;
+        } catch (err: any) {
+          errors.push(`Forex rate error: ${err.message}`);
+        }
+      }
+
+      // 1. Handle stablecoins via forex rate (USD → local)
+      if (stableSymbols.length > 0) {
+        const dk = date ? dateKey(date) : 'current';
+        for (const sym of stableSymbols) {
+          const key = `${sym.toUpperCase()}:${dk}`;
+          rates[key] = forexRate;
+        }
+      }
+
+      // 2. Handle crypto tokens via CoinGecko
+      if (cryptoSymbols.length > 0) {
+        if (date) {
+          // Historical: one request per token (CoinGecko /coins/{id}/history)
+          const d = new Date(date);
+          const ddMmYyyy = `${String(d.getUTCDate()).padStart(2, '0')}-${String(d.getUTCMonth() + 1).padStart(2, '0')}-${d.getUTCFullYear()}`;
+
+          for (const sym of cryptoSymbols) {
+            const upper = sym.toUpperCase();
+            const cacheKey = `${upper}:${dateKey(date)}`;
+
+            if (rateCache.has(cacheKey)) {
+              rates[cacheKey] = rateCache.get(cacheKey)!;
+              continue;
+            }
+
+            const cgId = TOKEN_TO_COINGECKO[upper];
+            if (!cgId) {
+              errors.push(`No CoinGecko mapping for ${upper}`);
+              continue;
+            }
+
+            try {
+              const histData = await cgFetch(`/coins/${cgId}/history?date=${ddMmYyyy}`);
+              // Prefer local currency price; if unavailable, use USD × forex rate
+              let price = histData?.market_data?.current_price?.[currency] || 0;
+              if (!price) {
+                const usdPrice = histData?.market_data?.current_price?.usd || 0;
+                price = usdPrice * forexRate;
+              }
+              rates[cacheKey] = price;
+              cacheRate(cacheKey, price);
+            } catch (err: any) {
+              errors.push(`CoinGecko history error for ${upper}: ${err.message}`);
+            }
+
+            await sleep(getCoinGeckoConfig().hasKey ? 100 : 200); // Rate limit (faster with key)
+          }
+        } else {
+          // Current: batch request
+          const cgIds = cryptoSymbols
+            .map(s => TOKEN_TO_COINGECKO[s.toUpperCase()])
+            .filter(Boolean);
+
+          if (cgIds.length > 0) {
+            try {
+              const batchData = await cgFetch(`/simple/price?ids=${cgIds.join(',')}&vs_currencies=${currency},usd`);
+
+              for (const sym of cryptoSymbols) {
+                const upper = sym.toUpperCase();
+                const cgId = TOKEN_TO_COINGECKO[upper];
+                if (!cgId) continue;
+                // Prefer local currency; if unavailable, use USD × forex rate
+                let price = batchData[cgId]?.[currency] || 0;
+                if (!price) {
+                  price = (batchData[cgId]?.usd || 0) * forexRate;
+                }
+                rates[`${upper}:current`] = price;
+              }
+            } catch (err: any) {
+              errors.push(`CoinGecko batch error: ${err.message}`);
+            }
+          }
+
+          // Map symbols without CoinGecko IDs
+          for (const sym of cryptoSymbols) {
+            const upper = sym.toUpperCase();
+            if (!TOKEN_TO_COINGECKO[upper] && !rates[`${upper}:current`]) {
+              errors.push(`No CoinGecko mapping for ${upper} — price unavailable`);
+            }
+          }
+        }
+      }
+
+      saveRateCache();
+
+      return {
+        rates,
+        currency: regionConfig.currency,
+        date: date || 'current',
+        errors: errors.length > 0 ? errors : undefined,
+      };
+    },
+  });
+
+  // ════════════════════════════════════════════════
+  // 5. tax_calculate_gains
+  // ════════════════════════════════════════════════
+
+  api.registerTool({
+    name: 'tax_calculate_gains',
+    description: 'Calculate taxable gains/losses using FIFO or Average Cost method. Takes pre-fetched trades, transfers, and rates. Returns disposals, income events, and summary with total taxable income.',
+    parameters: {
+      type: 'object',
+      required: ['trades', 'transfers', 'rates'],
+      properties: {
+        trades: {
+          type: 'array',
+          description: 'Array of DEX trades from tax_get_dex_trades',
+        },
+        transfers: {
+          type: 'array',
+          description: 'Array of categorized transfers from tax_get_transfers',
+        },
+        rates: {
+          type: 'object',
+          description: 'Rate map from tax_get_rates: {"SYMBOL:YYYY-MM-DD": rate}',
+        },
+        method: { type: 'string', description: '"fifo" (default) or "average"' },
+        region: { type: 'string', description: 'Region code: "NZ" (default) or "US"' },
+      },
+    },
+    handler: async ({ trades, transfers, rates, method, region }: {
+      trades: any[]; transfers: any[]; rates: Record<string, number>;
+      method?: string; region?: string;
+    }) => {
+      const regionConfig = getRegion(region);
+      const costMethod = (method || 'fifo').toLowerCase();
+
+      if (!regionConfig.cost_basis_methods.includes(costMethod)) {
+        return { error: `Method "${costMethod}" not supported for ${regionConfig.code}. Supported: ${regionConfig.cost_basis_methods.join(', ')}` };
+      }
+
+      // Normalize trade objects
+      const tradeEvents: TradeEvent[] = (trades || []).map((t: any) => ({
+        type: 'trade' as const,
+        date: t.date || '',
+        buy_amount: parseFloat(t.buy_amount) || 0,
+        buy_currency: t.buy_currency || '',
+        sell_amount: parseFloat(t.sell_amount) || 0,
+        sell_currency: t.sell_currency || '',
+        fee: parseFloat(t.fee) || 0,
+        fee_currency: t.fee_currency || '',
+        tx_id: t.tx_id || '',
+      }));
+
+      // Normalize transfer objects
+      const transferEvents: TransferEvent[] = (transfers || []).map((t: any) => ({
+        type: 'transfer' as const,
+        date: t.timestamp || t.date || '',
+        category: t.category || 'transfer',
+        amount: parseFloat(t.amount) || 0,
+        symbol: t.symbol || '',
+        direction: t.direction || 'incoming',
+        tx_id: t.tx_id || '',
+      }));
+
+      const result = costMethod === 'average'
+        ? calculateGainsAverage(tradeEvents, transferEvents, rates, regionConfig.currency)
+        : calculateGainsFIFO(tradeEvents, transferEvents, rates, regionConfig.currency);
+
+      return result;
+    },
+  });
+
+  // ════════════════════════════════════════════════
+  // 6. tax_generate_report
+  // ════════════════════════════════════════════════
+
+  api.registerTool({
+    name: 'tax_generate_report',
+    description: 'Generate a full crypto tax report. Orchestrates all tax tools: fetches balances, trades, transfers, rates, calculates gains, and estimates tax by bracket. Can accept pre-computed data to skip API calls.',
+    parameters: {
+      type: 'object',
+      required: ['account', 'tax_year'],
+      properties: {
+        account: { type: 'string', description: 'XPR Network account name' },
+        tax_year: { type: 'number', description: 'Tax year number. NZ: 2025 = Apr 2024–Mar 2025. US: 2024 = Jan 2024–Dec 2024' },
+        method: { type: 'string', description: '"fifo" (default) or "average"' },
+        region: { type: 'string', description: 'Region code: "NZ" (default) or "US"' },
+        balances_opening: { type: 'object', description: 'Pre-computed opening balances (skip API call)' },
+        balances_closing: { type: 'object', description: 'Pre-computed closing balances (skip API call)' },
+        trades: { type: 'array', description: 'Pre-computed trades array (skip API call)' },
+        transfers: { type: 'array', description: 'Pre-computed transfers array (skip API call)' },
+      },
+    },
+    handler: async ({ account, tax_year, method, region, balances_opening, balances_closing, trades, transfers }: {
+      account: string;
+      tax_year: number;
+      method?: string;
+      region?: string;
+      balances_opening?: any;
+      balances_closing?: any;
+      trades?: any[];
+      transfers?: any[];
+    }) => {
+      if (!account || typeof account !== 'string') {
+        return { error: 'account parameter is required' };
+      }
+      if (!tax_year || typeof tax_year !== 'number') {
+        return { error: 'tax_year parameter is required (e.g. 2025)' };
+      }
+
+      const regionConfig = getRegion(region);
+      const costMethod = (method || 'fifo').toLowerCase();
+      const { start, end } = getTaxYearDates(tax_year, regionConfig);
+      const currency = regionConfig.currency.toLowerCase();
+      const steps: string[] = [];
+
+      try {
+        // Step 1: Fetch opening balances
+        let openingBalances = balances_opening;
+        if (!openingBalances) {
+          steps.push('Fetching opening balances...');
+          try {
+            let url = `${SALTANT_BASE}/v2/state/get_balance?account=${encodeURIComponent(account)}&datetime=${encodeURIComponent(start)}`;
+            openingBalances = await httpGetJson(url);
+          } catch (err: any) {
+            openingBalances = { error: err.message };
+          }
+        }
+
+        // Step 2: Fetch closing balances
+        let closingBalances = balances_closing;
+        if (!closingBalances) {
+          steps.push('Fetching closing balances...');
+          try {
+            let url = `${SALTANT_BASE}/v2/state/get_balance?account=${encodeURIComponent(account)}&datetime=${encodeURIComponent(end)}`;
+            closingBalances = await httpGetJson(url);
+          } catch (err: any) {
+            closingBalances = { error: err.message };
+          }
+        }
+
+        // Step 3: Fetch DEX trades
+        let tradeData = trades;
+        if (!tradeData) {
+          steps.push('Fetching DEX trades...');
+          try {
+            const url = `${METALX_TAX_BASE}/dex/v1/tax/user?account=${encodeURIComponent(account)}`;
+            const csvText = await httpGetText(url);
+            const rows = parseCSV(csvText);
+
+            tradeData = rows
+              .filter(row => (row['Type'] || row['type'] || '').toLowerCase() === 'trade')
+              .map(row => ({
+                type: row['Type'] || row['type'] || '',
+                buy_amount: parseFloat(row['Buy Amount'] || row['buy_amount'] || '0'),
+                buy_currency: row['Buy Currency'] || row['buy_currency'] || '',
+                sell_amount: parseFloat(row['Sell Amount'] || row['sell_amount'] || '0'),
+                sell_currency: row['Sell Currency'] || row['sell_currency'] || '',
+                fee: parseFloat(row['Fee'] || row['fee'] || '0'),
+                fee_currency: row['Fee Currency'] || row['fee_currency'] || '',
+                date: row['Date'] || row['date'] || '',
+                tx_id: row['Tx-ID'] || row['TxId'] || row['txid'] || row['tx_id'] || '',
+              }));
+
+            // Filter to tax year
+            const startMs = new Date(start).getTime();
+            const endMs = new Date(end).getTime();
+            tradeData = tradeData.filter(t => {
+              const ms = new Date(t.date).getTime();
+              return ms >= startMs && ms <= endMs;
+            });
+          } catch (err: any) {
+            tradeData = [];
+            steps.push(`DEX trades error: ${err.message}`);
+          }
+        }
+
+        // Step 4: Fetch transfers
+        let transferData = transfers;
+        if (!transferData) {
+          steps.push('Fetching transfers...');
+          try {
+            const allTransfers: CategorizedTransfer[] = [];
+            let skip = 0;
+            let hasMore = true;
+            const maxTransfers = 5000;
+            const pageSize = 100;
+
+            while (hasMore && allTransfers.length < maxTransfers) {
+              let url = `${SALTANT_BASE}/v2/history/get_actions?account=${encodeURIComponent(account)}&act.name=transfer&limit=100&sort=asc&skip=${skip}`;
+              url += `&after=${encodeURIComponent(start)}&before=${encodeURIComponent(end)}`;
+
+              const data = await httpGetJson(url);
+              const actions: any[] = data.actions || [];
+
+              if (actions.length === 0) { hasMore = false; break; }
+
+              for (const action of actions) {
+                if (allTransfers.length >= maxTransfers) break;
+                const act = action.act?.data || {};
+                const from = act.from || '';
+                const to = act.to || '';
+                const memo = act.memo || '';
+                const quantityStr = act.quantity || '0 UNKNOWN';
+                const parts = quantityStr.split(' ');
+                const amount = parseFloat(parts[0]) || 0;
+                const symbol = parts[1] || 'UNKNOWN';
+                if (amount === 0) continue;
+
+                const category = categorizeTransfer(account, from, to, amount, symbol, memo);
+                const direction: 'incoming' | 'outgoing' = to === account ? 'incoming' : 'outgoing';
+
+                allTransfers.push({
+                  category, from, to, amount, symbol, memo,
+                  timestamp: action['@timestamp'] || action.timestamp || '',
+                  tx_id: action.trx_id || '',
+                  direction,
+                });
+              }
+
+              skip += actions.length;
+              if (actions.length < pageSize) hasMore = false;
+            }
+
+            transferData = allTransfers;
+          } catch (err: any) {
+            transferData = [];
+            steps.push(`Transfers error: ${err.message}`);
+          }
+        }
+
+        // Step 5: Build conversion rates
+        // Strategy: DEX trades give us direct price ratios (primary source),
+        // stablecoins use forex rate, CoinGecko as fallback for recent dates only
+        steps.push('Building conversion rates...');
+        const rates: Record<string, number> = {};
+        const allSymbols = new Set<string>();
+        const uniqueDates = new Set<string>();
+
+        for (const t of (tradeData || [])) {
+          if (t.buy_currency) { allSymbols.add(t.buy_currency); uniqueDates.add(dateKey(t.date)); }
+          if (t.sell_currency) { allSymbols.add(t.sell_currency); uniqueDates.add(dateKey(t.date)); }
+        }
+        for (const t of (transferData || []) as CategorizedTransfer[]) {
+          if (t.symbol) { allSymbols.add(t.symbol); uniqueDates.add(dateKey(t.timestamp)); }
+        }
+
+        // Pre-populate rates from persistent cache (historical prices are immutable)
+        let cacheHits = 0;
+        for (const sym of allSymbols) {
+          const upper = sym.toUpperCase();
+          for (const d of uniqueDates) {
+            const key = `${upper}:${d}`;
+            const cached = rateCache.get(key);
+            if (cached && cached > 0) {
+              rates[key] = cached;
+              cacheHits++;
+            }
+          }
+        }
+        if (cacheHits > 0) steps.push(`Loaded ${cacheHits} rates from cache`);
+
+        // Get USD→local forex rate (stablecoins and XMD are pegged to USD)
+        let forexRate = 1;
+        if (currency !== 'usd') {
+          try {
+            const forexData = await cgFetch(`/simple/price?ids=usd-coin&vs_currencies=${currency}`);
+            forexRate = forexData['usd-coin']?.[currency] || 1;
+          } catch { /* use 1 */ }
+        }
+
+        // Set stablecoin/XMD rates for all dates (they're pegged to USD)
+        for (const sym of allSymbols) {
+          const upper = sym.toUpperCase();
+          if (STABLECOINS.has(upper) || upper === 'XMD') {
+            for (const d of uniqueDates) {
+              rates[`${upper}:${d}`] = forexRate;
+            }
+            rates[`${upper}:current`] = forexRate;
+          }
+        }
+
+        // Derive token rates from DEX trades (primary source — no API limits)
+        // Most trades are TOKEN→XMD, so rate = buy_xmd / sell_token * forexRate
+        const dexRatesByDate: Record<string, number> = {}; // "SYMBOL:date" → local rate
+        for (const t of (tradeData || [])) {
+          if (!t.date || !t.sell_currency || !t.buy_currency) continue;
+          const d = dateKey(t.date);
+
+          // TOKEN → XMD: sell token, buy XMD → token price = (buy_xmd / sell_token) * forex
+          if ((t.buy_currency === 'XMD' || STABLECOINS.has(t.buy_currency.toUpperCase())) && t.sell_amount > 0 && t.buy_amount > 0) {
+            const tokenRate = (t.buy_amount / t.sell_amount) * forexRate;
+            const key = `${t.sell_currency.toUpperCase()}:${d}`;
+            // Use last trade of the day (overwrites earlier)
+            dexRatesByDate[key] = tokenRate;
+          }
+          // XMD → TOKEN: sell XMD, buy token → token price = (sell_xmd / buy_token) * forex
+          if ((t.sell_currency === 'XMD' || STABLECOINS.has(t.sell_currency.toUpperCase())) && t.buy_amount > 0 && t.sell_amount > 0) {
+            const tokenRate = (t.sell_amount / t.buy_amount) * forexRate;
+            const key = `${t.buy_currency.toUpperCase()}:${d}`;
+            dexRatesByDate[key] = tokenRate;
+          }
+        }
+
+        // Apply DEX-derived rates
+        for (const [key, rate] of Object.entries(dexRatesByDate)) {
+          if (!rates[key]) {
+            rates[key] = rate;
+            cacheRate(key, rate);
+          }
+        }
+
+        // Fill gaps: for dates without a DEX trade, use nearest available DEX rate
+        const symbolsNeedingRates = [...allSymbols].filter(s => {
+          const upper = s.toUpperCase();
+          return !STABLECOINS.has(upper) && upper !== 'XMD';
+        });
+        const sortedDates = [...uniqueDates].sort();
+
+        for (const sym of symbolsNeedingRates) {
+          const upper = sym.toUpperCase();
+          let lastKnownRate = 0;
+
+          for (const d of sortedDates) {
+            const key = `${upper}:${d}`;
+            if (rates[key] && rates[key] > 0) {
+              lastKnownRate = rates[key];
+            } else if (lastKnownRate > 0) {
+              // Forward-fill from last known rate
+              rates[key] = lastKnownRate;
+            }
+          }
+        }
+
+        // Fallback: CoinGecko for dates where we still have no rate
+        // With API key: no date limit, higher rate limits, more fetches allowed
+        // Without key: limited to 365 days, max 30 fetches
+        const cgConfig = getCoinGeckoConfig();
+        const now = Date.now();
+        const oneYearMs = 365 * 24 * 60 * 60 * 1000;
+        let cgFetches = 0;
+        const MAX_CG_FETCHES = cgConfig.hasKey ? 2000 : 30;
+        const CG_DELAY = cgConfig.hasKey ? 100 : 200;
+
+        for (const d of sortedDates) {
+          const dateMs = new Date(d + 'T00:00:00Z').getTime();
+          if (isNaN(dateMs)) continue;
+          // Without API key, skip dates beyond 365 days (CoinGecko free limit)
+          if (!cgConfig.hasKey && (now - dateMs) > oneYearMs) continue;
+
+          for (const sym of symbolsNeedingRates) {
+            const upper = sym.toUpperCase();
+            const key = `${upper}:${d}`;
+            if (rates[key] && rates[key] > 0) continue;
+            if (cgFetches >= MAX_CG_FETCHES) continue;
+
+            const cgId = TOKEN_TO_COINGECKO[upper];
+            if (!cgId) continue;
+
+            const dateObj = new Date(d + 'T00:00:00Z');
+            const ddMmYyyy = `${String(dateObj.getUTCDate()).padStart(2, '0')}-${String(dateObj.getUTCMonth() + 1).padStart(2, '0')}-${dateObj.getUTCFullYear()}`;
+
+            try {
+              const histData = await cgFetch(`/coins/${cgId}/history?date=${ddMmYyyy}`);
+              // Prefer local currency; if unavailable, use USD × forex rate
+              let price = histData?.market_data?.current_price?.[currency] || 0;
+              if (!price) {
+                const usdPrice = histData?.market_data?.current_price?.usd || 0;
+                price = usdPrice * forexRate;
+              }
+              if (price > 0) {
+                rates[key] = price;
+                cacheRate(key, price);
+              }
+              cgFetches++;
+            } catch { /* skip */ }
+
+            await sleep(CG_DELAY);
+          }
+        }
+
+        // Forward-fill again after CoinGecko to cover remaining gaps
+        for (const sym of symbolsNeedingRates) {
+          const upper = sym.toUpperCase();
+          let lastKnownRate = 0;
+          for (const d of sortedDates) {
+            const key = `${upper}:${d}`;
+            if (rates[key] && rates[key] > 0) {
+              lastKnownRate = rates[key];
+            } else if (lastKnownRate > 0) {
+              rates[key] = lastKnownRate;
+            }
+          }
+          // Also backward-fill: if the first few dates had no rate but later ones do
+          let firstKnownRate = 0;
+          for (let i = sortedDates.length - 1; i >= 0; i--) {
+            const d = sortedDates[i];
+            const key = `${upper}:${d}`;
+            if (rates[key] && rates[key] > 0) {
+              firstKnownRate = rates[key];
+            } else if (firstKnownRate > 0) {
+              rates[key] = firstKnownRate;
+            }
+          }
+        }
+
+        // Final fallback: fetch current rate for any symbols still missing
+        const missingSymbols = symbolsNeedingRates.filter(sym => {
+          const upper = sym.toUpperCase();
+          return sortedDates.some(d => !rates[`${upper}:${d}`] || rates[`${upper}:${d}`] === 0);
+        });
+        if (missingSymbols.length > 0) {
+          const cgIds = missingSymbols.map(s => TOKEN_TO_COINGECKO[s.toUpperCase()]).filter(Boolean);
+          if (cgIds.length > 0) {
+            try {
+              const currentData = await cgFetch(`/simple/price?ids=${cgIds.join(',')}&vs_currencies=${currency},usd`);
+              for (const sym of missingSymbols) {
+                const upper = sym.toUpperCase();
+                const cgId = TOKEN_TO_COINGECKO[upper];
+                if (!cgId || !currentData[cgId]) continue;
+                let price = currentData[cgId][currency] || 0;
+                if (!price) {
+                  price = (currentData[cgId].usd || 0) * forexRate;
+                }
+                if (price > 0) {
+                  // Apply to all dates that still have no rate
+                  for (const d of sortedDates) {
+                    const key = `${upper}:${d}`;
+                    if (!rates[key] || rates[key] === 0) {
+                      rates[key] = price;
+                    }
+                  }
+                  rates[`${upper}:current`] = price;
+                }
+              }
+            } catch { /* skip */ }
+          }
+        }
+
+        // Persist rate cache to disk
+        saveRateCache();
+
+        // Step 6: Calculate gains
+        steps.push('Calculating gains...');
+        const tradeEvents: TradeEvent[] = (tradeData || []).map((t: any) => ({
+          type: 'trade' as const,
+          date: t.date || '',
+          buy_amount: parseFloat(t.buy_amount) || 0,
+          buy_currency: t.buy_currency || '',
+          sell_amount: parseFloat(t.sell_amount) || 0,
+          sell_currency: t.sell_currency || '',
+          fee: parseFloat(t.fee) || 0,
+          fee_currency: t.fee_currency || '',
+          tx_id: t.tx_id || '',
+        }));
+
+        const transferEvents: TransferEvent[] = (transferData || []).map((t: any) => ({
+          type: 'transfer' as const,
+          date: t.timestamp || t.date || '',
+          category: t.category || 'transfer',
+          amount: parseFloat(t.amount) || 0,
+          symbol: t.symbol || '',
+          direction: t.direction || 'incoming',
+          tx_id: t.tx_id || '',
+        }));
+
+        const gains = costMethod === 'average'
+          ? calculateGainsAverage(tradeEvents, transferEvents, rates, regionConfig.currency)
+          : calculateGainsFIFO(tradeEvents, transferEvents, rates, regionConfig.currency);
+
+        // Step 7: Estimate tax
+        const taxableIncome = gains.summary.grand_total_taxable;
+        const taxBrackets = calculateTax(Math.max(0, taxableIncome), regionConfig);
+        const estimatedTax = taxBrackets.reduce((sum, b) => sum + b.tax, 0);
+
+        // Build CSV exports
+        const disposalCsv = [
+          'Date,Asset,Amount,Proceeds,Cost Basis,Gain/Loss,Method,TX ID',
+          ...gains.disposals.map(d =>
+            `${d.date},${d.asset},${d.amount},${d.proceeds_local.toFixed(2)},${d.cost_basis_local.toFixed(2)},${d.gain_loss_local.toFixed(2)},${d.method},${d.tx_id || ''}`
+          ),
+        ].join('\n');
+
+        const incomeCsv = [
+          'Date,Category,Asset,Amount,Value,TX ID',
+          ...gains.income_events.map(e =>
+            `${e.date},${e.category},${e.asset},${e.amount},${e.value_local.toFixed(2)},${e.tx_id || ''}`
+          ),
+        ].join('\n');
+
+        // Transfer summary by category
+        const transferSummary: Record<string, number> = {};
+        for (const t of (transferData || []) as CategorizedTransfer[]) {
+          transferSummary[t.category] = (transferSummary[t.category] || 0) + 1;
+        }
+
+        // Income by category
+        const incomeByCategory = gains.income_events.reduce((acc: Record<string, number>, e) => {
+          acc[e.category] = (acc[e.category] || 0) + e.value_local;
+          return acc;
+        }, {});
+
+        const effectiveRate = taxableIncome > 0
+          ? `${((estimatedTax / taxableIncome) * 100).toFixed(2)}%`
+          : '0%';
+
+        // ── Build formatted markdown report ──
+        const CUR = regionConfig.currency;
+        const fmt = (n: number) => `$${n.toLocaleString('en-NZ', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+        const startLabel = start.slice(0, 10);
+        const endLabel = end.slice(0, 10);
+
+        const md: string[] = [];
+        md.push(`# Crypto Tax Report — ${regionConfig.name}`);
+        md.push('');
+        md.push(`**Account:** \`${account}\``);
+        md.push(`**Tax Year:** ${tax_year} (${startLabel} to ${endLabel})`);
+        md.push(`**Currency:** ${CUR}`);
+        md.push(`**Cost Basis Method:** ${costMethod.toUpperCase()}`);
+        md.push(`**Generated:** ${new Date().toISOString().slice(0, 10)}`);
+        md.push('');
+
+        // Balance sheets
+        md.push('---');
+        md.push('');
+        md.push('## Balance Snapshots');
+        md.push('');
+        md.push(`### Opening Balances (${startLabel})`);
+        md.push('');
+        md.push(formatBalancesMarkdown(openingBalances));
+        md.push('');
+        md.push(`### Closing Balances (${endLabel})`);
+        md.push('');
+        md.push(formatBalancesMarkdown(closingBalances));
+        md.push('');
+
+        // Activity summary
+        md.push('---');
+        md.push('');
+        md.push('## Activity Summary');
+        md.push('');
+        md.push(`| Metric | Count |`);
+        md.push(`|--------|-------|`);
+        md.push(`| DEX Trades | ${(tradeData || []).length} |`);
+        md.push(`| On-chain Transfers | ${(transferData || []).length} |`);
+        md.push('');
+
+        if (Object.keys(transferSummary).length > 0) {
+          md.push('**Transfers by Category:**');
+          md.push('');
+          md.push('| Category | Count |');
+          md.push('|----------|-------|');
+          for (const [cat, count] of Object.entries(transferSummary).sort((a, b) => (b[1] as number) - (a[1] as number))) {
+            md.push(`| ${cat} | ${count} |`);
+          }
+          md.push('');
+        }
+
+        // Trading summary
+        md.push('---');
+        md.push('');
+        md.push('## Trading Summary');
+        md.push('');
+        md.push(`| | ${CUR} |`);
+        md.push(`|---|---:|`);
+        md.push(`| Total Proceeds | ${fmt(gains.summary.total_proceeds)} |`);
+        md.push(`| Total Cost Basis | ${fmt(gains.summary.total_cost_basis)} |`);
+        md.push(`| **Net Gain/Loss** | **${fmt(gains.summary.net_gain_loss)}** |`);
+        md.push(`| Disposals | ${gains.disposals.length} |`);
+        md.push('');
+
+        // Top disposals (max 20)
+        if (gains.disposals.length > 0) {
+          md.push('### Disposals');
+          md.push('');
+          md.push('| Date | Asset | Amount | Proceeds | Cost Basis | Gain/Loss |');
+          md.push('|------|-------|-------:|--------:|---------:|----------:|');
+          const topDisposals = gains.disposals.slice(0, 20);
+          for (const d of topDisposals) {
+            md.push(`| ${d.date.slice(0, 10)} | ${d.asset} | ${d.amount} | ${fmt(d.proceeds_local)} | ${fmt(d.cost_basis_local)} | ${fmt(d.gain_loss_local)} |`);
+          }
+          if (gains.disposals.length > 20) {
+            md.push(`| ... | *${gains.disposals.length - 20} more* | | | | |`);
+          }
+          md.push('');
+        }
+
+        // Income summary
+        md.push('---');
+        md.push('');
+        md.push('## Income Summary');
+        md.push('');
+        md.push(`| Category | ${CUR} |`);
+        md.push(`|----------|---:|`);
+        for (const [cat, val] of Object.entries(incomeByCategory).sort((a, b) => (b[1] as number) - (a[1] as number))) {
+          md.push(`| ${cat} | ${fmt(val as number)} |`);
+        }
+        md.push(`| **Total Income** | **${fmt(gains.summary.total_income)}** |`);
+        md.push('');
+
+        // Top income events (max 20)
+        if (gains.income_events.length > 0) {
+          md.push('### Income Events');
+          md.push('');
+          md.push('| Date | Category | Asset | Amount | Value |');
+          md.push('|------|----------|-------|-------:|------:|');
+          const topIncome = gains.income_events.slice(0, 20);
+          for (const e of topIncome) {
+            md.push(`| ${e.date.slice(0, 10)} | ${e.category} | ${e.asset} | ${e.amount} | ${fmt(e.value_local)} |`);
+          }
+          if (gains.income_events.length > 20) {
+            md.push(`| ... | *${gains.income_events.length - 20} more* | | | |`);
+          }
+          md.push('');
+        }
+
+        // Tax estimate
+        md.push('---');
+        md.push('');
+        md.push('## Estimated Tax');
+        md.push('');
+        md.push(`| | ${CUR} |`);
+        md.push(`|---|---:|`);
+        md.push(`| Net Trading Gain/Loss | ${fmt(gains.summary.net_gain_loss)} |`);
+        md.push(`| Total Income | ${fmt(gains.summary.total_income)} |`);
+        md.push(`| **Total Taxable** | **${fmt(gains.summary.grand_total_taxable)}** |`);
+        md.push('');
+
+        if (taxBrackets.length > 0) {
+          md.push('**Tax Brackets:**');
+          md.push('');
+          md.push('| Bracket | Income | Rate | Tax |');
+          md.push('|---------|-------:|-----:|----:|');
+          for (const b of taxBrackets) {
+            md.push(`| ${b.bracket} | ${fmt(b.income)} | ${(b.rate * 100).toFixed(1)}% | ${fmt(b.tax)} |`);
+          }
+          md.push(`| **Total** | | | **${fmt(round2(estimatedTax))}** |`);
+          md.push(`| **Effective Rate** | | **${effectiveRate}** | |`);
+          md.push('');
+        }
+
+        if (!regionConfig.has_capital_gains) {
+          md.push('> No separate capital gains tax in ' + regionConfig.name + ' — all crypto gains are treated as income.');
+          md.push('');
+        }
+
+        // Disclaimer
+        md.push('---');
+        md.push('');
+        md.push(`**Disclaimer:** ${regionConfig.disclaimer}`);
+        md.push('');
+
+        const reportMarkdown = md.join('\n');
+
+        return {
+          report: {
+            account,
+            tax_year: tax_year,
+            region: regionConfig.code,
+            currency: regionConfig.currency,
+            period: { start, end },
+            method: costMethod,
+          },
+          opening_balances: openingBalances,
+          closing_balances: closingBalances,
+          activity: {
+            dex_trades: (tradeData || []).length,
+            transfers: (transferData || []).length,
+            transfer_categories: transferSummary,
+          },
+          trading_summary: {
+            total_proceeds: gains.summary.total_proceeds,
+            total_cost_basis: gains.summary.total_cost_basis,
+            net_gain_loss: gains.summary.net_gain_loss,
+            total_disposals: gains.disposals.length,
+          },
+          income_summary: {
+            total_income: gains.summary.total_income,
+            by_category: incomeByCategory,
+            total_events: gains.income_events.length,
+          },
+          tax_estimate: {
+            total_taxable_income: gains.summary.grand_total_taxable,
+            brackets: taxBrackets,
+            estimated_tax: round2(estimatedTax),
+            effective_rate: effectiveRate,
+            note: regionConfig.has_capital_gains
+              ? 'Capital gains tax applies in this region'
+              : 'No separate capital gains tax — all gains treated as income',
+          },
+          report_markdown: reportMarkdown,
+          csv_exports: {
+            disposals: disposalCsv,
+            income: incomeCsv,
+          },
+          remaining_cost_basis: gains.remaining_lots,
+          steps_completed: steps,
+          disclaimer: regionConfig.disclaimer,
+        };
+      } catch (err: any) {
+        return { error: `Report generation failed: ${err.message}`, steps_completed: steps };
+      }
+    },
+  });
+}