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, USD, 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-rate endpoint to fetch the current rate for your desired currency pair.

2

Create an FX settlement (beneficiary payout)

Use the /beneficiary-payout/create endpoint 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 fxId on the payout object. Use this fxId with the /fx/retrieve endpoint 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 fxId you 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.

See the API Reference for full details on endpoints and parameters.