FX Conversion & Hedging

Use this pattern when your integration needs to convert balances between currencies using either spot FX trades for routine conversion or OTC deals for larger negotiated transactions.

✅ Before you start

Complete these steps before you implement the FX pattern:

1. Authenticate with the merged Login service and store the returned token and companyId.
2. Confirm both the source and target wallets exist.
3. Confirm the source wallet has enough availableBalance for the planned conversion.
4. Decide whether the conversion size warrants a spot trade or an OTC deal.
5. Register webhook endpoints so you can reconcile FX trade completions.

📚 Use this page with the recipe

This guide explains when to use the FX conversion pattern and the minimum sequence. For the implementation walkthrough, use the recipe:

FX Conversion & Hedging Recipe →

The FX pattern

This integration pattern follows a simple sequence:

1. Get a live FX rate with Get FX rate when a quote is needed.
2. Execute the conversion before the vfx_token expires by calling Create FX trade.
3. Store the FX trade paymentId and reference for reconciliation.
4. Use OTC deals for larger sizes that need a negotiated rate, then retrieve and reconcile them through the OTC Deals API.
5. Track final state through webhooks before treating the converted balance as available.

What makes this pattern different?

Unlike a single transaction flow, FX conversion as an integration pattern needs to:

• respect short vfx_token lifetimes for spot rates
• fall back to OTC deals when size or pricing demands it
• reconcile both inwardSettlementTime and outwardSettlementTime per trade
• support FX markup configuration where the platform sets customer-facing pricing

Where to go deeper

• FX Conversion Guide
• FX Markup Functionality
• Exchange
• OTC Deals

Troubleshooting

Next steps