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"
}'

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