Currency exchange
Use the currency exchange endpoints to convert money between wallets that hold different currencies. GetExchangeRate returns the real-time exchange rate between two currencies. BookExchange debits a wallet in one currency, converts the amount at the real-time rate, and credits the result to a wallet in another currency.
Currencies are identified by three-letter ISO 4217 codes such as USD, EUR or AUD. Rates are real-time, so the rate can change slightly between a GetExchangeRate call and the BookExchange call that follows it. Both wallets in an exchange must belong to the account that makes it.
#Get an exchange rate
/API/v4/Payment/GetExchangeRateReturns the real-time exchange rate for converting FromCurrency into ToCurrency. Call it before BookExchange to check the current rate.
The rate is returned in ExchangeRate inside ExchangeRateMethodsDetail. It's the number of units of ToCurrency that 1 unit of FromCurrency buys, so multiply an amount in FromCurrency by the rate to get its value in ToCurrency.
Note
The rate is real-time and can change slightly between a call to GetExchangeRate and a call to BookExchange.
Body parameters
GetExchangeRateobjectRequiredWrapper object for the operation.
Child parameters1
RequestobjectRequiredWrapper object for the request fields.
Child parameters3
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.FromCurrencystringRequiredThree-letter ISO 4217 code of the source currency you convert from, for example
USD.ToCurrencystringRequiredThree-letter ISO 4217 code of the target currency you convert to, for example
EUR.
Response fields
GetExchangeRateMethodsResponseobjectWrapper object for the response.
Child parameters1
ExchangeRateMethodResultobjectResult of the operation.
Child parameters2
ExchangeRateMethodsobjectContainer for the exchange rate details.
Child parameters1
ExchangeRateMethodsDetailobject[]List of exchange rate details, with one entry for the requested currency pair.
Child parameters5
IssuerAccountNumberstringThe Xtrm account identifier of the account that initiated the API call.
FromCurrencystringThree-letter ISO 4217 code of the source currency.
ToCurrencystringThree-letter ISO 4217 code of the target currency.
AmountnumberThe amount of
FromCurrencythe rate is quoted for: always1.ExchangeRatenumberThe real-time exchange rate: the number of units of
ToCurrencythat 1 unit ofFromCurrencybuys. Multiply an amount inFromCurrencyby the rate to get its value inToCurrency. For example, aUSDtoAUDrate of1.4005406means 1 USD converts to 1.4005406 AUD, so 100 USD converts to 140.05 AUD.
OperationStatusobjectOutcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]The error messages when the call fails, as an array of strings.
nullon success, so decide withSuccessand useErrorsonly to explain a failure.
Related: Exchange currency between wallets
#Exchange currency between wallets
/API/v4/Payment/BookExchangeConverts money from one currency to another. Xtrm debits Amount, in FromCurrency, from the source wallet (FromWalletID), converts it at the real-time rate, and credits the result in ToCurrency to the destination wallet (ToWalletID). If you omit ToWalletID, Xtrm credits one of the account's wallets in the target currency, or creates one if there's none.
AccountNumber identifies the account that makes the exchange. It can be a company account (SPN) or a personal account (PAT). If it isn't your own account, your company must be connected to it. Without a connection, the call returns HTTP 400 with Not authorized to access this resource. Make One Time Password API Call to access this resource.
To check the current rate first, call GetExchangeRate. Xtrm doesn't hold that rate: BookExchange converts at the rate at the moment you book, which can differ slightly.
The response returns two transaction IDs: DebitTransactionID for the debit from the source wallet and CreditTransactionID for the credit to the destination wallet. Xtrm posts both before it responds, so the converted funds can pay a batch right away. Both appear in the wallets' transactions as Currency Exchange.
If the wallet in FromWalletID holds less than Amount, Xtrm rejects the exchange with HTTP 400 before it books anything, so no money is exchanged and nothing leaves the wallet. OperationStatus.Success is false, and Errors contains <FromWalletID> - Insufficient balance in the wallet.
Important
Both FromWalletID and ToWalletID must belong to the account in AccountNumber. That is why release 4.91.2 removed the OTP parameter from BookExchange.
Tip
The wallet transaction list endpoints (GetCompanyWalletTransactions and GetUserWalletTransactions) accept Currency Exchange as a TransactionType filter value.
Body parameters
BookExchangeobjectRequiredWrapper object for the operation.
Child parameters1
RequestobjectRequiredWrapper object for the request fields.
Child parameters7
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.AccountNumberstringRequiredThe Xtrm account number of the account that makes the exchange, starting with
SPNfor company accounts orPATfor personal accounts. Both wallets in the exchange must belong to this account.FromWalletIDstringRequiredThe numeric
WalletIDof the source wallet that the funds are debited from, for example"122181". It must be a wallet of the account inAccountNumber, inFromCurrency. Wallet names aren't accepted.FromCurrencystringRequiredThree-letter ISO 4217 code of the currency you sell, for example
USD.ToCurrencystringRequiredThree-letter ISO 4217 code of the currency you buy, for example
EUR.AmountstringRequiredAmount to exchange as a decimal string, for example
"365.00". Denominated inFromCurrency. The wallet inFromWalletIDmust hold at least this amount; anAmountequal to its balance is accepted.ToWalletIDstringOptionalThe numeric
WalletIDof the destination wallet that receives the converted money, for example"122182". It must be a wallet of the account inAccountNumber, inToCurrency. If you omit it, Xtrm credits one of the account's wallets inToCurrency, or creates one if there's none. A value that isn't a number, such as the wallet's name, counts as omitted, so always send the numeric ID.
Response fields
BookExchangeMethodsResponseobjectWrapper object for the response.
Child parameters1
BookExchangeMethodResultobjectResult of the operation.
Child parameters2
BookExchangeMethodsobjectContainer for the exchange details.
Child parameters1
BookExchangeMethodsDetailobjectDetails of the booked exchange.
Child parameters4
DebitTransactionIDintegerUnique identifier of the debit transaction from the source wallet.
CreditTransactionIDintegerUnique identifier of the credit transaction into the destination wallet.
PaymentDatestringTimestamp of when the exchange was processed, for example
"2026-06-04T00:00:00-04:00".PaymentStatusstringStatus of the exchange: always
Completedon success.
OperationStatusobjectOutcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]The error messages when the call fails, as an array of strings.
nullon success, so decide withSuccessand useErrorsonly to explain a failure.
#Errors
| Message | Meaning |
|---|---|
400 · Insufficient balance in the wallet | The wallet in FromWalletID holds less than Amount. Errors contains <FromWalletID> - Insufficient balance in the wallet. Xtrm books nothing and doesn't debit the wallet. Fund the wallet or exchange a smaller amount, then book again. |
400 · Not authorized to access this resource. Make One Time Password API Call to access this resource | The account in AccountNumber isn't your company's own account and isn't connected to it. A Pending connection doesn't count. Connect the account first, for example with a one-time password, then book again. See Connections and manager services. |
Related: Get an exchange rate · List company wallets · List an individual recipient's wallets · Create a company wallet · Create an individual recipient's wallet · List company wallet transactions · List an individual recipient's wallet transactions