WalletsFX

Foreign Exchange (FX)

Get real-time exchange rates between supported currencies and execute currency conversions within your wallets.

Get exchange rates

Retrieve current exchange rates for a given base currency. Rates are updated in real time and include a spread that reflects the conversion cost.

GET/fx/rates

Get live exchange rates for a base currency.

Query parameters

Name	Type	Required	Description
base	string	required	Base currency code (e.g., "IQD"). Rates will be quoted against this currency.
targets	string	optional	Comma-separated target currencies (e.g., "USD,EUR"). Omit for all supported currencies.

curl "https://wallet.e-mazad.store/api/v1/fx/rates?base=IQD&targets=USD,EUR" \
  -H "Authorization: Bearer sk_sandbox_..."

Rate expiry

Rates include an expires_at timestamp. Always check this before displaying rates to users. Expired rates should be refreshed before executing a conversion.

Execute conversion

Convert funds between currencies within a wallet. The conversion uses the current live rate and is settled instantly.

POST/fx/convert

Convert funds between currencies in a wallet at the current live rate.

Request body

Name	Type	Required	Description
wallet_id	string	required	The wallet ID to convert within, or "me" for merchant wallet.
from_currency	string	required	Source currency code (e.g., "IQD").
to_currency	string	required	Target currency code (e.g., "USD").
amount	integer	required	Amount to convert in smallest unit of the source currency.

curl -X POST https://wallet.e-mazad.store/api/v1/fx/convert \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_id": "me",
    "from_currency": "IQD",
    "to_currency": "USD",
    "amount": 1310000
  }'

Conversion is irreversible

Once a currency conversion is executed, it cannot be reversed. To convert back, you would need to execute a new conversion in the opposite direction at the then-current rate.

Supported currency pairs

All supported currencies can be converted to and from each other. IQD is the primary settlement currency.

Currency	Can convert to	Spread
IQD	USD, EUR, GBP, AED, TRY	1.5%
USD	IQD, EUR, GBP, AED, TRY	1.5%
EUR	IQD, USD, GBP, AED, TRY	1.5%
GBP	IQD, USD, EUR, AED, TRY	1.5%
AED	IQD, USD, EUR, GBP, TRY	1.5%
TRY	IQD, USD, EUR, GBP, AED	2.0%

Sandbox rates are fixed

In the sandbox environment, FX rates are fixed and do not fluctuate. This makes testing predictable and reproducible. Production rates update in real time from market data.

Transactions Testing