Mastering FX Conversions

Get a live FX quote, lock the rate with a vfx_token, and convert funds between supported wallets before you continue into payout or treasury flows.

✅ Before you convert funds

Complete these steps before you request a quote:

1. Make sure the source wallet exists and holds the funds you want to convert.
2. Confirm the target currency and destination wallet or downstream flow.
3. Decide whether you need immediate settlement or a later deal structure.
4. Prepare to execute quickly after you fetch the quote because the token expires fast.

stateDiagram-v2
    [*] --> Fetch_Quote
    Fetch_Quote --> Lock_Rate: Logic Check
    Lock_Rate --> Execute: Confirm
    Execute --> Settling: Rail In-Transit
    Settling --> [*]: Funds Hit Wallet

⚡ Step 1: Get a live FX rate

Use Get Rates (New) to retrieve the current FX rate for a currency pair. The rate request uses currencyFrom, currencyTo, and paymentMode to describe the conversion you intend to create.

Capture the returned vfx_token immediately because it expires after 30 seconds and is required when you create the FX trade.

🔒 Rate Locking & The VFX Token

Verto's liquidity rail uses a "Loc-Rate" mechanism. When you fetch a quote, the response includes a vfx_token.

[!IMPORTANT] 30-Second Window The vfx_token locks the mid-market rate and your partner markup for exactly 30 seconds. If the token expires, you must fetch a new quote before executing the conversion.

📅 Step 2: Create the FX trade

To execute, pass the fresh rate token into Create FX Trade (New). The trade payload uses paymentType to define whether you are converting between wallets or converting and paying out.

{
  "paymentType": "convertWithinWallets",
  "sourceWalletId": 11435,
  "sourceAmount": 4800,
  "vfx_Token": "uciebcjdencijwnijnciqnq832982jhbj3eduh3",
  "targetWalletId": 23181,
  "paymentId": "35448e78-8180-4ce5-8671-772c29ad658f"
}

If the token has expired, do not retry the conversion with the old token. Request a fresh rate and execute again with the new vfx_token.

🔔 Webhook Feedback Loop

Once the conversion is booked, monitor your webhooks for the following granular states:

• inward_remittance_confirmed: Your source wallet has been successfully debited.
• outward_remittance_complete: The conversion is finished and funds have hit the target wallet or beneficiary.

Use these events to update balances, unlock downstream payout steps, and reconcile the conversion result against your internal ledger.

📘 Documented FX lifecycle statuses

The following FX lifecycle statuses are currently documented in v1.1:

If your application also reads trade status fields from Get an FX Trade (New), reconcile them against the FX conversion completion webhook before you treat the conversion as final in your own system.

🛑 Step 3: Cutoff & Settlement Times

Treat these timings as operational guidance when planning downstream payout or treasury actions.

💡 Yield Optimization

• Early Booking: Conversions executed before 14:00 GMT often settle same-day for major corridors.
• Liquidity Check: For exotic pairs (e.g. KES, GHS), execution may require manual desk approval for amounts >$250k.

Troubleshooting