Exchange Rates & Multi-Currency

AI-Native ERP provides an automatic exchange rate feed system that fetches daily rates from multiple public sources, calculates cross-rates, and distributes them across your organization. Combined with automatic FX gain/loss posting, the system handles the full lifecycle of multi-currency accounting.

---

Architecture Overview#

Exchange rates flow through a three-tier architecture:

External Sources (ECB, Frankfurter, US Treasury)
        |
        v
System-Level Cache (shared market rates)
        |
        v
Organization Working Copy (market + manual + contract rates)

Why Two Levels?#

This separation means market rates are fetched once and shared efficiently, while each organization maintains its own working copy that can include manual overrides and entity-specific rates.

---

Data Sources#

The system fetches rates from three free, public APIs:

European Central Bank (ECB)#

• 28 EUR-based currency pairs
• Daily updates on weekdays (~16:00 CET)
• Available as daily snapshot or 90-day history
• No authentication required

Frankfurter API#

• 28 currencies with flexible base currency
• Supports historical date ranges
• JSON format (ECB data in a developer-friendly wrapper)
• No authentication required

US Treasury Fiscal Data API#

• 170+ currency pairs (USD-based)
• Quarterly updates
• Broadest currency coverage of the three sources
• No authentication required

Source Priority#

When multiple sources provide the same currency pair on the same date, the system applies this priority:

manual > ecb > us_treasury > frankfurter > calculated

Manual rates always take precedence over automated feeds, ensuring your overrides are preserved.

---

Rate Types#

The system supports four types of exchange rates, each serving a different purpose:

Transaction processing automatically uses spot rates. Contract and budget rates must be explicitly selected.

---

Automatic Features#

Inverse Rate Calculation#

Every fetched rate automatically generates its inverse. If the system fetches EUR-to-USD = 1.08, it simultaneously stores USD-to-EUR = 0.9259. This ensures both directions of any currency pair are always available.

Cross-Rate Calculation#

When a direct rate is not available from any source, the system derives it by bridging through USD or EUR.

Example:

Need: ILS to GBP (not directly available)

Available:
  ILS to USD = 0.2740 (from US Treasury)
  USD to GBP = 0.7890 (from ECB)

Calculated:
  ILS to GBP = 0.2740 x 0.7890 = 0.2162

Cross-rates are recalculated automatically based on your organization's functional currencies. If your entities operate in AED, ILS, or other currencies not directly covered by ECB, the system ensures you have rates for all needed pairs.

Rate Lookup for Transactions#

When a transaction is posted in a foreign currency, the system automatically:

1. Looks up the spot rate for the transaction date (or the most recent rate on or before that date)
2. Converts the document amount to the entity's functional currency
3. Converts the document amount to the reporting currency (if different)
4. Records all six amount fields: document debit/credit, functional debit/credit, reporting debit/credit

If no rate is found, the system logs a warning and uses a fallback rate of 1.0 to avoid blocking business operations. The transaction still posts, but amounts may need correction.

---

FX Gain/Loss Handling#

When a payment is received or made at a different exchange rate than the original transaction, the system automatically calculates and posts the foreign exchange variance.

How It Works#

Invoice created:  EUR 50,000 at rate 1.10 = USD 55,000 (functional)
Payment received: EUR 50,000 at rate 1.08 = USD 54,000 (functional)

Variance: USD 54,000 - USD 55,000 = -USD 1,000 (FX Gain)

The system recognizes this as an FX gain (the company received less in functional currency but the liability was also less) and automatically posts a journal entry.

Posting Rules#

FX journal entries include metadata linking back to the source transaction, documenting the original rate, actual rate, and variance calculation for audit purposes.

---

Managing Exchange Rates#

Automatic Sync#

Rate feeds can be synced on demand or scheduled for daily execution. The sync process:

1. Fetches rates from all configured sources
2. Calculates inverse and cross-rates
3. Stores in the system cache
4. Distributes to all active organizations

The distribution uses upsert logic, so it is safe to run repeatedly -- existing rates are updated and new rates are inserted.

Manual Rate Entry#

You can create, update, or delete exchange rates manually through the workflow system. Manual rates receive the highest priority and are never overwritten by automated feeds.

Common reasons for manual rates:

• Currency pairs not covered by any API source
• Contractual or negotiated rates for specific transactions
• Budget rates for planning purposes
• Corrections to market data

Currency Conversion#

A built-in currency conversion tool lets you convert any amount between currencies using stored rates. You specify the amount, source currency, target currency, and effective date, and the system returns the converted amount using the appropriate rate.

---

Consolidated Reporting#

When generating consolidated reports across entities with different functional currencies, the system automatically converts amounts to a common reporting currency.

Reports that use currency conversion:

• Consolidated Trial Balance
• Consolidated Balance Sheet
• Consolidated Income Statement
• Entity Comparison Report

Each entity's functional currency amounts are translated at the rate for the report date, with the conversion applied transparently in the report output.

---

New Organization Onboarding#

When a new organization is created, it needs historical exchange rates immediately. Rather than fetching months of data from external APIs (which is slow and may hit rate limits), the system copies all cached rates from the system-level store into the new organization's schema instantly.

What gets copied:

• All market rates from all sources
• Calculated cross-rates

What does not get copied:

• Manual rates from other organizations
• Contract or budget rates from other organizations
• Entity-specific rate overrides from other organizations

This means a new organization has full rate history from day one, ready for immediate transaction processing and reporting.

---

Rate Coverage Statistics#

The system maintains comprehensive rate coverage. A typical organization has:

• 50,000+ stored rate records
• Coverage from multiple years of daily rates
• Multiple sources per currency pair for reliability
• Cross-rates filling gaps where direct rates are unavailable

Source distribution typically includes rates from Frankfurter (~47%), ECB (~26%), US Treasury (~15%), calculated cross-rates (~10%), and manual entries (~2%).

---

Best Practices#

1. Run daily syncs -- Fetch rates on weekdays to keep your rate data current

2. Use manual rates sparingly -- Rely on automated feeds for market rates and reserve manual entry for contract, budget, or truly unavailable pairs

3. Monitor for gaps -- If transactions log "no rate found" warnings, check whether the currency pair needs manual entry or a cross-rate bridge

4. Backfill new organizations -- Always run a backfill when creating a new organization to ensure full rate history

5. Understand rate lookup behavior -- The system uses the most recent rate on or before the transaction date, not necessarily the exact date. This means weekend transactions use Friday's rate automatically

6. Review FX postings -- Periodically review automatic FX gain/loss entries to ensure they align with your expectations, especially during periods of high currency volatility