---
title: FX History
description: Inspect the local FX rate cache that powers historical currency conversion. Run firma sync (or firma sync fx) to populate it from FRED. Stored as "foreign per 1 USD" for KRW, JPY, EUR, CNY, GBP, HKD, INR, and TWD.
---

export const usageFeatures = [
  {
    icon: '📊',
    title: 'show balance / show flow',
    desc: <>Each entry uses its date's rate. The output footer shows <code>FX @ 2026-03-31: 1 USD = 1523.5 KRW</code> so the conversion is auditable.</>,
  },
  {
    icon: '📈',
    title: 'report (time series)',
    desc: "Each period aggregates with that period's rate. The Net Worth trend reflects what you actually had in your home currency, not \"today's USD value × today's rate\".",
  },
  {
    icon: '💼',
    title: 'show portfolio Net Worth',
    desc: "Historical FX for the latest balance period. Portfolio MV (your live holdings) stays on the live FX rate. They're distinct concepts.",
  },
];

<Section label="firma show fx">
Without arguments, shows per-currency coverage of the cache: how many rows are
stored for each currency, and the date range covered. Useful for verifying that
the backfill completed and that the cache spans your earliest entry date.

<div className="terminal">
  <div className="terminal-line">
    <span className="term-prompt">$</span>
    <span className="term-cmd">firma show fx</span>
  </div>
  <table className="term-table">
    <thead>
      <tr><th>CURRENCY</th><th>ROWS</th><th>FIRST</th><th>LAST</th></tr>
    </thead>
    <tbody>
      <tr className="sep"><td colSpan={4}/></tr>
      <tr><td className="td-bold">CNY</td><td className="td-muted">1905</td><td className="td-muted">2018-08-28</td><td className="td-muted">2026-04-17</td></tr>
      <tr><td className="td-bold">EUR</td><td className="td-muted">1905</td><td className="td-muted">2018-08-28</td><td className="td-muted">2026-04-17</td></tr>
      <tr><td className="td-bold">GBP</td><td className="td-muted">1905</td><td className="td-muted">2018-08-28</td><td className="td-muted">2026-04-17</td></tr>
      <tr><td className="td-bold">HKD</td><td className="td-muted">1905</td><td className="td-muted">2018-08-28</td><td className="td-muted">2026-04-17</td></tr>
      <tr><td className="td-bold">INR</td><td className="td-muted">1905</td><td className="td-muted">2018-08-28</td><td className="td-muted">2026-04-17</td></tr>
      <tr><td className="td-bold">JPY</td><td className="td-muted">1905</td><td className="td-muted">2018-08-28</td><td className="td-muted">2026-04-17</td></tr>
      <tr><td className="td-bold">KRW</td><td className="td-muted">1905</td><td className="td-muted">2018-08-28</td><td className="td-muted">2026-04-17</td></tr>
      <tr><td className="td-bold">TWD</td><td className="td-muted">1905</td><td className="td-muted">2018-08-28</td><td className="td-muted">2026-04-17</td></tr>
      <tr className="sep"><td colSpan={4}/></tr>
    </tbody>
  </table>
</div>

  <Note>
    USD has no rows. It's the base currency, always 1.0 in code.
    The FIRST date is your earliest transaction/balance/flow date (or close to it),
    since that's the backfill anchor.
  </Note>
</Section>

<Section label="firma show fx <currency>">
With a currency code, shows the most recent N rates (default 30):

<div className="terminal">
  <div className="terminal-line">
    <span className="term-prompt">$</span>
    <span className="term-cmd">firma show fx KRW --limit 5</span>
  </div>
  <table className="term-table">
    <thead><tr><th>DATE</th><th>KRW per USD</th></tr></thead>
    <tbody>
      <tr className="sep"><td colSpan={2}/></tr>
      <tr><td className="td-muted">2026-04-17</td><td>1461.6600</td></tr>
      <tr><td className="td-muted">2026-04-16</td><td>1478.1900</td></tr>
      <tr><td className="td-muted">2026-04-15</td><td>1474.4100</td></tr>
      <tr><td className="td-muted">2026-04-14</td><td>1471.5100</td></tr>
      <tr><td className="td-muted">2026-04-13</td><td>1486.9400</td></tr>
      <tr className="sep"><td colSpan={2}/></tr>
    </tbody>
  </table>
</div>

  <Note>
    Newest first. Direction is uniform across all currencies: foreign per 1 USD,
    so multiply your USD value by the rate to get the home-currency equivalent.
  </Note>
</Section>

<Section label="Date Range">
Use <code>--from</code> and <code>--to</code> for an explicit window (the default
limit is ignored when a range is set):

<div className="terminal">
  <div className="terminal-line">
    <span className="term-prompt">$</span>
    <span className="term-cmd">firma show fx KRW --from 2020-03-01 --to 2020-04-01</span>
  </div>
  <pre className="term-pre">{`DATE            KRW per USD
──────────────────────────────
2020-03-31      1217.4200
2020-03-30      1224.5500
2020-03-27      1218.0800
2020-03-26      1232.0100
2020-03-25      1241.4900
2020-03-24      1247.9800
2020-03-23      1267.2500   ← COVID crash peak
...`}</pre>
</div>
</Section>

<Section label="JSON Output">
<code>--json</code> works on both forms. Coverage summary or per-currency series:

<div className="terminal">
  <div className="terminal-line">
    <span className="term-prompt">$</span>
    <span className="term-cmd">firma show fx KRW --json --limit 2</span>
  </div>
  <pre className="term-pre">{`{
  "currency": "KRW",
  "count": 2,
  "observations": [
    { "date": "2026-04-17", "currency": "KRW", "rate_to_usd": 1461.66 },
    { "date": "2026-04-16", "currency": "KRW", "rate_to_usd": 1478.19 }
  ]
}`}</pre>
</div>
</Section>

<Section label="How firma Uses the Cache">
When you display past data in a non-USD currency, firma converts *each entry
using the FX rate from its own date*. Looked up here.

  <FeatureList items={usageFeatures} />
</Section>

<Section label="Cache Misses & Fallbacks">
If a date isn't in the cache (weekend, holiday, or a brand-new entry whose date
comes after your last sync), firma falls back to the most recent prior rate within
a 7-day lookback window. If even that misses, the live FX rate from{' '}
<code>open.er-api.com</code> is used as a last resort. <code>firma sync fx</code>
after adding old data ensures the cache covers your full history.
</Section>
