FX Rate Locks

FX Rate Locks allow you to lock an exchange rate for an extended period of time beyond the default simulation expiry. This is useful when you need more time to confirm a transaction with your end user or when you want to guarantee a rate while awaiting approval.

When you create a simulation, Caliza automatically generates FX Lock variants with different durations. Each variant applies a small spread on top of the market rate — the longer the lock, the higher the spread.

To use FX Rate Locks, follow this workflow:

1. Create a simulation using v2.
2. Retrieve the available FX Lock options.
3. Choose the lock variant that best fits your needs.
4. Execute the payment or transaction using the chosen simulation ID.

Step 1: Create a simulation

To get started, create a simulation using the v2 endpoint. Make sure to replace the following:

• YOUR_TOKEN with your actual API token
• beneficiaryId with the ID of the beneficiary

curl -s --location --request POST 'https://api.sandbox.caliza.com/core-api/v2/simulations' \
--header "Authorization: Bearer YOUR_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "from": {
        "currencyCode": "USDC",
        "value": 1000
    },
    "to": {
        "currencyCode": "BRL"
    },
    "beneficiaryId": "69261109adcc7b2db705a123",
    "recipientId": "12ace467-8189-42ec-8b21-0a5bf7cd7f5e",
    "funding": "ETH",
    "payout": "PIX"
}'

Step 2: Retrieve FX Lock options

Using the simulation ID from the previous step, retrieve all available FX Lock variants.

curl --location 'https://api.sandbox.caliza.com/core-api/v2/simulations/{{simulationId}}/fxlocks' \
--header 'Authorization: Bearer YOUR_TOKEN'

Step 3: Choose a lock and execute

Once you've reviewed the FX Lock options, pick the simulation that best fits your needs and use its id to execute the payment or transaction.

Execute as a payment

curl 'https://api.sandbox.caliza.com/core-api/v1/payments' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "simulationId": "{{chosenSimulationId}}",
  "beneficiaryIp": "{{beneficiaryIp}}"
}'

Execute as a transaction

Alternatively, you can execute as a transaction:

curl 'https://api.sandbox.caliza.com/core-api/v1/transactions' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "simulationId": "{{chosenSimulationId}}",
  "beneficiaryIp": "{{beneficiaryIp}}"
}'

📘

Locked rate guarantee

The exchange rate is guaranteed for the full duration of the chosen lock. If you selected FX_LOCK_24, you have 24 hours from the simulation creation time to execute the payment or transaction at the locked rate. After the expiresAt time, the simulation can no longer be used.

⚠️

Spread trade-off

Longer lock durations provide more time to execute but come with a higher spread. Choose the shortest lock duration that meets your operational needs to minimize costs.

Related Articles