FX Trade

You can exchange any currency pairs the Multi-Currency Account supports. Let's exchange USD for EUR as an example.

How to perform a currency exchange:

Get the FX Rate – Use the Get an FX rate endpoint to get the latest FX rate for your desired currency pair.
Create an FX Order – Execute the currency exchange with the FX rate using the Create an FX order endpoint.

Get an Exchange Rate

To retrieve an exchange rate, call the Get an FX rate endpoint, providing the currency pair and the amount you wish to exchange.

Request:

curl --request POST \
     --url https://sandbox.hifibridge.com/v2/multi-currency-account/exchanges/rate \
     --header 'accept: application/json' \
     --header 'authorization: Bearer zpka_xxxxx' \
     --header 'content-type: application/json' \
     --data '
{
  "source": {
    "currency": "USD",
    "amount": 10
  },
  "destination": {
    "currency": "EUR"
  },
  "userId": "faf56e30-6806-46a9-ab46-f8413f191a01"
}
'

Response:

{
    "id": "736c17bd-fcb1-4bb5-ad9b-76d74d7f8ca0",
    "createdAt": "2025-02-01T04:32:27.037269+00:00",
    "userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01",
    "source": {
        "amount": 10,
        "currency": "USD"
    },
    "destination": {
        "amount": 9.62,
        "currency": "EUR"
    },
    "rate": 0.96189,
    "expiresAt": "2025-02-01T04:33:26.557+00:00"
}

Exchange Currencies Using an Exchange Rate

Once you have obtained an exchange rate, you can proceed with the currency exchange by using the exchange rate id.

Request:

curl --request POST \
     --url https://sandbox.hifibridge.com/v2/multi-currency-account/exchanges \
     --header 'accept: application/json' \
     --header 'authorization: Bearer zpka_xxxxx' \
     --header 'content-type: application/json' \
     --data '
{
  "source": {
    "currency": "USD",
    "amount": 10
  },
  "destination": {
    "currency": "EUR"
  },
  "requestId": "79d661c4-f9d1-44a8-937a-0b3de6c6bf63",
  "userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01",
  "rateId": "736c17bd-fcb1-4bb5-ad9b-76d74d7f8ca0"
}
'

Response:

{
    "id": "dc93b3d3-ae96-4bd6-848f-7e96adb0082f",
    "createdAt": "2025-02-11T15:23:59.811266+00:00",
    "updatedAt": "2025-02-11T15:24:02.604+00:00",
    "requestId": "bf068b04-66cb-4658-b84d-7ecea493de85",
    "userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01",
    "rateId": "736c17bd-fcb1-4bb5-ad9b-76d74d7f8ca0",
    "source": {
        "amount": 10,
        "currency": "USD"
    },
    "destination": {
        "amount": 9.62,
        "currency": "EUR"
    },
    "reference": null,
    "status": "CREATED",
    "failedReason": ""
}

The FX trade order will initially have the status CREATED, indicating that the order has been created and is awaiting processing. You can either poll the Retrieve an FX order endpoint or wait for the Exchange webhook event to receive the latest application status updates. Learn more about FX Trade order statuses here.