Exchanges

Exchanges in Caliza allow you to convert between different currencies within a beneficiary's account — for example, converting USDC to USD, USDT to USD, or USDC to USDT. To perform an exchange, follow a two-step process:

1. Simulate the exchange to get a quote.
2. Execute the exchange based on the simulation.

See the sections below for more details on each step.

Simulate the exchange

To simulate an exchange using the Caliza API, you can use the following cURL command. Make sure to replace the following:

• YOUR_TOKEN with your actual API token
• beneficiaryId with the ID of the beneficiary you want to simulate the exchange for.

See an example request and response below:

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": 500
    },
    "to": {
        "currencyCode": "USD"
    },
    "beneficiaryId": "69261109adcc7b2db705a123"
}'

Adding your own spread

When an exchange involves a currency conversion (for example USDC → BRL), you can add your own spread on top of Caliza's spread. That spread becomes your revenue on the conversion. You set it by passing a customFees object with an INTEGRATOR_SPREAD value on the simulation request.

• The value is expressed in basis points (BPS), where 100 BPS = 1%. A value of 10 means a 0.10% markup.
• The value must be ≥ 0. Passing 0 (or omitting customFees) disables your spread; Caliza's spread always applies.
• It only affects the currency-conversion (FX) leg of an operation. Same-currency flows are unaffected.

How the rates relate

A converted amount is built up in two markup tiers on top of the raw market rate. Each margin is revenue for a different party:

The two margins stack, so the integrator rate is the least favorable of the three. The beneficiary receives the amount converted at the integrator rate.

Request

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": 500
    },
    "to": {
        "currencyCode": "BRL"
    },
    "customFees": {
        "INTEGRATOR_SPREAD": 100
    },
    "beneficiaryId": "69261109adcc7b2db705a123"
}'

Where customFees.INTEGRATOR_SPREAD is your spread in basis points (here 100 BPS = 1%).

Response

The simulation (and later the transaction) reports the rate tiers under conversionDetails, and each margin as an item under feeDetails.spreadFees[] — a CALIZA item for Caliza's revenue and an INTEGRATOR_SPREAD item for yours:

"transactionDetails": {
    "conversionDetails": {
        "effectiveTransactionValue": 2633.76,
        "marketExchangeRate": 5.40000000,
        "clientRate": 5.32019704,
        "calizaRate": 5.32019704,
        "integratorRate": 5.26752183
    },
    "feeDetails": {
        "spreadFees": [
            {
                "type": "CALIZA",
                "spreadBasisPoint": 150,
                "marketRate": 5.40000000,
                "effectiveRate": 5.32019704,
                "calizaRate": 5.32019704,
                "calculatedFee": 39.90
            },
            {
                "type": "INTEGRATOR_SPREAD",
                "spreadBasisPoint": 100,
                "marketRate": 5.40000000,
                "effectiveRate": 5.26752183,
                "calizaRate": 5.26752183,
                "calculatedFee": 26.34
            }
        ]
    }
}

Worked example

Converting 500 USDC → BRL at a market rate of 5.40, with a Caliza spread of 150 BPS and your spread of 100 BPS:

• At the market rate (5.40000000): 500 × 5.40 = 2700.00 BRL.
• At the Caliza rate (5.32019704): 500 × 5.32019704 ≈ 2660.10 BRL. The 39.90 BRL gap is Caliza's revenue (the CALIZA spread item).
• At the integrator rate (5.26752183): 500 × 5.26752183 ≈ 2633.76 BRL. The 26.34 BRL gap is your revenue (the INTEGRATOR_SPREAD spread item).

The beneficiary receives 2633.76 BRL — the amount converted at the integrator rate.

Execute the exchange

After simulating and agreeing on the from and to values, you'll need to execute the exchange.

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

Get the exchange status

To check the status of an exchange using the Caliza API, you can use the following cURL command.

curl --location --globoff 'https://api.sandbox.caliza.com/core-api/v1/transactions/{{transaction_id}}' \
--header 'Authorization: Bearer YOUR_TOKEN'

Webhook events for exchanges

When an exchange is completed, Caliza will send a webhook event to notify you about the successful exchange. The relevant webhook event for exchanges completed is as follows:

{
"operation": "TRANSACTION_COMPLETED",
"resourceId": "{{transaction_id}}",
"createdAt": "2025-04-17T22:10:23.476151179",
"integratorId": "{{integrator_id}}",
"beneficiaryId": "{{beneficiary_id}}",
"message": null,
"success": true,
"data": {
  "callbackType": "transactionCallback",
  "id": "{{transaction_id}}",
  "integratorId": "{{integrator_id}}",
  "beneficiaryId": "{{beneficiary_id}}",
  "simulationId": null,
  "foFTransactionType": "REGULAR_TRANSACTION",
  "amountToBeConverted": {
    "currencyCode": "USDC",
    "value": 100.00
  },
  "from": {
    "currencyCode": "USDC",
    "value": 100.00
  },
  "to": {
    "currencyCode": "USD",
    "value": 100.00
  },
  "totalFees": {
    "currencyCode": "USD",
    "value": 0.0000
  },
  "totalTaxes": {
    "currencyCode": "USD",
    "value": 0.0000
  },
  "status": "TRANSACTION_COMPLETED",
  "fiatAccountId": null,
  "recipientId": null,
  "fundingWallet": {{funding_wallet_address}},
  "targetWallet": null,
  "depositTransactionHash": null,
  "withdrawalTransactionHash": null,
  "flowOfFundsId": {{flow_of_funds_id}},
  "localTargetAccount": null,
  "exchangeRate": null,
  "settlement": false
}
}

Where:

• operation: The type of operation that triggered the webhook (for example, TRANSACTION_COMPLETED).
• resourceId: The ID of the transaction associated with the webhook event.
• createdAt: The timestamp when the webhook event was created.
• integratorId: The ID of the integrator associated with the transaction.
• beneficiaryId: The ID of the beneficiary associated with the transaction.
• data: An object containing detailed information about the transaction, including its status and amounts.

You can use these webhook events to track exchange status and take appropriate actions based on each transaction.

Related Articles