Currency conversion

Overview

Currency conversion is MessageMind's shared money layer rather than a credentialed external integration. The /integrations card lists it under Bank and Finance with an empty fields array and a Disabled status, because there is nothing per-tenant to paste. Every account has an account currency (the owner's own locale currency, resolved from the assistant profile or country when not yet set), and every reader can request totals in their own currency through the display currency header or query parameter. A single rate table per UTC day is used across the whole platform, fetched from a configured provider, cached in memory, and persisted so the last known day can serve stale when the provider is temporarily unreachable.

What MessageMind can do with it

• Resolve each account's own currency from the assistant profile, the stored country, or the account time zone, defaulting to USD when nothing is known. The default is stamped on the account the first time it is read so it never changes under the owner.
• Fetch and cache one FX rate table per UTC day, store it in the database, and serve the last stored day (marked stale) when the provider is unreachable.
• Convert a stored amount from any ISO 4217 currency the registry knows into the reader's currency, with proper half-away-from-zero rounding at that currency's digits (0, 2, or 3).
• Report the rate table's day, staleness, and any currencies the reader asked for that the table could not convert, on every money-bearing response.
• Expose a convertCurrency assistant tool that converts one or more amounts between two currencies, returning either a value or a human-readable breakdown with exact, rounded, and nearest-5 variants.

Requirements

• A FX rate provider configured through the CURRENCY_URL environment variable. The provider is expected to return a payload with a data block of CODE: rate pairs.
• A MongoDB connection (used to persist the day's rate table and to allow stale fallback).

How to connect

1. There is nothing to connect per account. The /integrations card for Currency Conversion ships with no fields and a Disabled status because the capability is wired at the platform layer, not per tenant.
2. An operator sets the CURRENCY_URL environment variable to the FX provider's endpoint on the deployment.
3. The first read for a given UTC day triggers a fetch, stores the table, and keeps it in memory for the day.
4. Each account's account currency is resolved from the assistant profile, country, and time zone, then stamped on the account's user record the first time it is read.

Authentication and permissions

Available data and actions

AI agent use cases

• A customer asks the price of something quoted in a different currency; the AI converts it on the fly through the convertCurrency tool.
• A reader on a different currency opens their money view with a currency query parameter or the x-currency header; totals are converted into their currency, with the rate day and staleness surfaced on the response.
• An amount stored without an explicit currency is read in the owner's account currency, so legacy or ambiguous records remain comparable.

Configuration

• The registry covers the circulating ISO 4217 codes as of October 2026. Metals, SDR, fund codes, and withdrawn codes are deliberately excluded.
• A code outside the registry is ignored (not refused), so a stale client that asks for a withdrawn code still gets a readable response in the fallback currency.
• After a provider failure, the fetch is held off for 15 minutes while readers receive the last stored day with the stale flag set.
• Rounding uses the currency's own ISO 4217 minor units (0, 2, or 3), from a baked-in table.
• The display currency is taken from the currency query parameter first, then the x-currency header, then a per-caller fallback, then the owner's account currency.

Example workflows

Limitations

• One rate table per UTC day. Intraday rate moves are not reflected.
• When the provider is down and no stored day exists, no conversion is possible and the response surfaces that explicitly.
• Codes outside the baked-in registry are not converted. The registry excludes metals, SDR, fund codes, and withdrawn codes.
• Only the owner's stored currency, country, and time zone (and the assistant profile currency) feed the default resolution.
• The /integrations card shows status Disabled because there is no per-tenant credential to collect; the capability is on whenever the deployment has CURRENCY_URL set.

Troubleshooting

Disconnect and reconnect

• Currency conversion is a platform capability rather than a per-account connection; there is no per-tenant disconnect flow. Unset CURRENCY_URL at the deployment to stop fetching new rates (stored days will still be served, marked stale).

Related integrations

Stripe Shopify WooCommerce