Create a conversion
Use this step-by-step guide to learn how to successfully create currency conversions for your Airwallex Wallet currencies using Transactional FX APIs. Depending on your chosen FX solution, MarketFX or LockFX, the integration code for the first two steps will differ.
For conversions in payouts, see Create a payout.
Before you begin
- Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
- Contact your Airwallex Account Manager to enable MarketFX or LockFX for your account. Note that your account will be set to pre-funding mode by default, so you need to ensure that you have sufficient funds in your Airwallex Wallet before making a conversion. You can check your Wallet balance using Get current balances API. In the post-funding mode, you can make trades up to your open position limit without sufficient balance. For more information on funding modes, see Funding and Settlement models.
- Check the sell and buy currencies supported on your Airwallex account using Supported currencies API so you can use a valid currency pair in your conversion request.
Step 1: Retrieve a quote
Regardless of the FX product, you can retrieve price quotes before booking a conversion.
MarketFX
If you are using MarketFX, you can retrieve an indicative quote for a specified currency pair that will give you an indication of the current price you would receive if you were to create a currency conversion.
Call Retrieve an indicative MarketFX quote API with the buy_currency, sell_currency, and either the sell_amount or buy_amount as query parameters. You can optionally specify a conversion_date, i.e., the date on which the conversion will be settled. If you do not specify a date, Airwallex determines the default based on your funding mode (see settlement timing).
Example request
Example response
LockFX
If you are using LockFX, call Create a LockFX quote API to retrieve a guaranteed conversion rate for use within the validity period. Specify the buy_currency, sell_currency, buy_amount/sell_amount, and the quote validity. The validity period you specify must belong to the validity group configured for your account. See Quote validity period.
Optionally, you can specify a conversion_date, i.e., the date on which the conversion will be settled. If you do not specify a date, Airwallex determines the default based on your funding mode (see settlement timing).
Example request
A successful conversion returns the quote_id in the response. You must store the quote_id for future use on subsequent conversions or payout requests (see Create a payout).
The quote response also contains key details that are required for a successful subsequent conversion booking including:
- Validity period of the quote (
valid_from,valid_to) - Whether the quote can be used once or multiple times (
MULTI_USEorSINGLE_USE) - Conversion date (
conversion_date) - Direction of conversion (
buy_currency,sell_currency)
Example response
Step 2: Book a conversion
Call Create a conversion API to execute a conversion.
As a MarketFX customer, you do not need to populate quote_id so leave this field blank to allow Airwallex to execute MarketFX conversion.
When using LockFX, you must use a valid quote_id in the conversion or payout request. The relevant details from the quote including buy_currency, sell_currency and any future dated conversion_date if specified must match the subsequent conversion or payout request. A successful conversion request will occur at the client_rate from your retrieved quote.
Example request
Example response
Step 3: Retrieve the conversion
You can retrieve details of a previous conversion including its current status anytime using Retrieve a conversion API. If you want to retrieve details of all conversions associated with your account, see List all conversions API.
See Conversion statuses to learn about the status of your conversion.