Skip to main content
FX beneficiary payouts let you convert your Ivy account balance from one currency to another and settle to a bank account or wallet in the target currency. This is ideal for global businesses, treasury management, and reducing FX costs.
To enable stablecoin beneficiary payouts, Ivy support must configure this for your account. Contact your Ivy account manager to get started.

​
Use Cases

  • Settle your EUR balance to a GBP, USDC, or other currency account
  • Receive payouts in your preferred currency, regardless of how you were paid in
  • Pay suppliers or partners in their local currency
  • Move funds between fiat and stablecoin balances for treasury optimization
  • Reduce FX costs by leveraging Ivy’s direct FX rails

​
How It Works

1

Get a real-time exchange rate

Use the /fx/retrieve-rateendpoint to fetch the current rate for your desired currency pair.
2

Create an FX settlement (beneficiary payout)

Use the /beneficiary-payout/createendpoint to convert and settle your balance in the target currency to your bank account or wallet.
3

Fetch FX details for a completed payout

After creating a beneficiary payout, you’ll receive an fxIdon the payout object. Use this fxIdwith the /fx/retrieveendpoint to fetch details about the exchange rate and conversion used for that specific payout.
4

Track settlement status

Monitor your settlement in the Dashboard or via webhooks. Funds usually arrive instantly, but can take up to 2 business days depending on the destination.

​
API Endpoints

​
1. Retrieve Exchange Rate

​
/api/service/fx/retrieve-rate
POST
required
Get the real-time exchange rate for a specific currency pair.
Request
POST /api/service/fx/retrieve-rate
{
  "sourceCurrency": "EUR",
  "targetCurrency": "USD"
}
Response
{
  "rate": 1.085,
  "targetAmount": 1.085,
  "sourceAmount": 1
}

​
2. Perform FX Settlement (Beneficiary Payout)

​
/api/service/beneficiary-payout/create
POST
required
Trigger the FX Beneficiary Payout. This will sweep all your fiat balances, onramp them to stablecoins and settle to your beneficiary wallet. The response will include an fxIdyou can use to fetch more details about the conversion.
Request
POST /api/service/beneficiary-payout/create
{}
Response
[
    {
        "id": "1234567890",
        "type": "beneficiary-payout",
        "referenceId": "ref_1234567890",
        "merchant": "merchant_1234567890",
        "amount": 1,
        "currency": "EUR",
        "status": "pending"
    }
]

​
3. Retrieve FX Details (for a specific payout)

Check the status of your Beneficiary Payout, corresponding trx hash and FX Details in the Dashboard.