Skip to main content
Use this endpoint to exchange funds between two settlement wallets in different currencies. The exchange operates in two steps: first request a QUOTE to preview the rate and converted amount, then submit an EXCHANGE request to execute the conversion. Both the source and destination must be settlement wallets on your account. Method: POST
URL: https://app.kulmipay.com/api/v1/wallets/{wallet_id}/exchange/ Replace {wallet_id} with the wallet_id of the source settlement wallet — the one holding the currency you want to sell.
Always request a QUOTE before executing an EXCHANGE. Rates reflect live market conditions and can change. Reviewing the quoted rate and converted amount before committing prevents surprises.

​
Request parameters

​
currency
string
required
The target currency you want to receive. Must be different from the source wallet’s currency. One of: KES, USD, EUR, GBP.
​
amount
string
required
The amount in the source currency to exchange, as a decimal string. Must be greater than 0.01 and no more than 999999.00.
​
action
string
required
The operation to perform. Use QUOTE to preview the exchange rate without moving any funds, or EXCHANGE to execute the conversion and debit the source wallet.

​
Code examples

cURL
curl --request POST \
  --url https://app.kulmipay.com/api/v1/wallets/wlt_kes123/exchange/ \
  --header "Authorization: Bearer YOUR_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "currency": "USD",
    "amount": "100000.00",
    "action": "QUOTE"
  }'

​
Response — QUOTE

A QUOTE response returns the current exchange rate and the amount you would receive. No funds are moved.
​
rate
string
The exchange rate applied, expressed as units of target currency per unit of source currency.
​
fxe_amount
string
The amount you would receive in the target currency at this rate.
​
currency
string
The target currency for this quote.

​
Example QUOTE response

{
  "rate": "0.00769",
  "fxe_amount": "769.23",
  "currency": "USD"
}

​
Response — EXCHANGE

An EXCHANGE response confirms the conversion was executed. The source wallet is debited and the destination settlement wallet is credited.
​
status
string
Always "success" when the exchange completes.
​
rate
string
The exchange rate that was applied.
​
fxe_amount
string
The amount credited to the destination wallet.
​
currency
string
The target currency that was credited.
​
narrative
string
A description of the exchange that appears in both wallets’ transaction statements.

​
Example EXCHANGE response

{
  "status": "success",
  "rate": "0.00769",
  "fxe_amount": "769.23",
  "currency": "USD",
  "narrative": "FX exchange KES 100000.00 to USD 769.23 at rate 0.00769"
}
The EXCHANGE action requires that the source wallet’s available_balance is greater than or equal to amount. The request will return an error if the wallet has insufficient available funds.