​
What is the FX Engine?

The FX Engine is Layer 1 of the OpenFX four-layer architecture. It sits between the Identity layer (Layer 0) below and the Banking layer (Layer 2) above, powering every operation that involves converting one currency or asset into another. The FX Engine serves two primary use cases:
  1. Standalone conversions — A customer converts USD to EUR on their own account. The account is debited in USD and credited in EUR.
  2. Cross-currency payments — A customer sends a payment where the source currency differs from the destination. The FX Engine converts inline as part of payment execution.
From the customer’s perspective, an FX conversion is simply “I converted USD to EUR.” The internal liquidity mechanism that makes this possible is never exposed in the API. There are no references to internal counterparties, liquidity pools, or trading books.

​
Three FX capabilities

The FX Engine provides three categories of functionality, each building on the last:
CapabilityEndpointPurpose
DiscoveryGET /fx/asset-pairsFind out which asset pairs are available and their min/max amounts
PricingGET /fx/rates/indicative and POST /fx/quotesGet informational rates or lock an executable rate for 60 seconds
ExecutionPOST /fx/conversionsExecute a conversion that debits one currency and credits another
A typical FX flow follows this sequence:
  1. Discover pairs — Call GET /fx/asset-pairs to confirm the pair is available and check min/max amounts.
  2. Get a rate or lock a quote — Use GET /fx/rates/indicative for informational display, or POST /fx/quotes to lock a rate for execution.
  3. Execute — Call POST /fx/conversions with either a locked quote ID or at-market parameters.

​
Sell/buy naming convention

All FX fields use sell/buy terminology, not source/target. This is a locked design decision that matches industry conventions from CurrencyCloud, Airwallex, and other leading FX platforms.
FieldDescriptionExample
sellCurrencyThe currency being sold (debited)"USD"
buyCurrencyThe currency being bought (credited)"EUR"
sellAmountThe amount of the sell currency"10000.00"
buyAmountThe amount of the buy currency"9250.00"
When creating a quote or conversion, you provide either sellAmount or buyAmount (never both). The system calculates the other side at the current rate. The FxAmountInputSide field (sell or buy) indicates which side was authoritative.
Always use sellCurrency / buyCurrency and sellAmount / buyAmount in your integration code. The API does not accept sourceCurrency, targetCurrency, or similar alternatives.

​
AssetCode — fiat and crypto unified

The AssetCode type (pattern ^[A-Z]{2,10}$) is used for sellCurrency and buyCurrency across all FX endpoints. It accommodates both fiat ISO 4217 codes and crypto asset tickers:
TypeExamplesFormat
FiatUSD, EUR, GBP, SGD, MXN, BRLISO 4217, 3 uppercase letters
CryptoUSDC, USDT, EURC, PYUSDTicker, 2-10 uppercase letters
This means the FX Engine handles fiat-to-fiat, fiat-to-crypto, and crypto-to-crypto conversions through the same API surface. A conversion from USD to USDC uses the same endpoints as a conversion from USD to EUR.

​
FX on payments

When a payment’s source currency differs from the delivery currency, the FX Engine handles conversion inline as part of payment processing. There are two execution modes:
ModeexecutionPreferenceHow it works
Pre-locked quoteuse_quoteYou create an FX quote first (POST /fx/quotes), then reference its quoteId in the payment. The payment executes at the locked rate.
At-marketat_marketNo quote needed. The payment converts at the current market rate at the time of processing.
Additionally, payment-specific pricing tools are available:
  • Payment estimates (POST /payments/estimates) — Get a non-binding cost preview including FX rate, fees, and delivery timeline.
  • Payment quotes (POST /payments/quotes) — Lock an executable payment quote with guaranteed FX rate, fees, and total cost.
For simple balance-to-balance currency conversions (no external payment), use the standalone FX endpoints (POST /fx/quotes and POST /fx/conversions). For cross-currency payments to a counterparty, use the payment endpoint directly with executionPreference to handle FX and payment in a single call.

​
FX guides

Asset Pairs

Discover available trading pairs, supported currencies, and min/max amounts.

Quotes & Rates

Get indicative rates for display or lock executable quotes for 60 seconds.

Conversions

Execute currency conversions on customer accounts.

​
API Reference