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. For conversions during 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.
- If your account is set to the default pre-funding mode then make sure 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
You can retrieve price quotes before booking a conversion regardless of the FX product you want to use for conversions – Rates or Quotes.
Rates
You can retrieve the current rate for a specified currency pair that will give you an indication of the current price you would receive if you were to book a currency conversion. Call Retrieve a current rate API with the buy_currency and sell_currency as query parameters. You can optionally specify either the sell_amount or buy_amount, and a conversion_date, i.e., the date on which the conversion will be settled.
The amount if not specified defaults to 10, 000. If a date is not specified, Airwallex determines the default based on your funding mode (see settlement timing).
Example request
Example response
Quotes
To retrieve a guaranteed quote for use within a validity period, call Create a Quote API. Specify the buy_currency, sell_currency, buy_amount/sell_amount, and the quote validity. Supported validity periods include: 1 minute, 15 minutes, 30 minutes, 1 hour, 4 hour, 8 hour, 24 hour.
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).
Once a quote is retrieved, you must request a conversion using that quote before the expiry time (valid_to_at) returned in the response.
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_at,valid_to_at) - Quote usage (
MULTI_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.
Provide buy_currency, sell_currency, buy_amount/sell_amount and the request_id (an idempotency key to prevent duplicate requests) in your conversion request.
If you do not provide quote_id Airwallex will execute a conversion at the current market rate.
If you provide a valid quote_id in the conversion or payout request, the conversion will be executed at the client_rate from the quote. The details in the conversion or payout request such as buy_currency, sell_currency and any future dated conversion_date (if specified) must match the quote details.
Funding source
By default, your Wallet will be used as the funding source for the conversion. However, if you want the conversion to be funded via direct debit from Linked Account, provide the funding_source object. Airwallex settles the funds direct-debited from a Linked Account into a temporary clearing wallet dedicated to the conversion, and ensures that the funds cannot be used for other transactions until the conversion is settled.
id: Provide the unique ID of your Linked Account as returned in Create a Linked Account.deposit_type: Should be eitherDIRECT_DEBITorFASTER_DIRECT_DEBIT. Deposit type will default toDIRECT_DEBITif not specified. See direct debit flight times to understand the difference between the two deposit types.
If you are registered as a platform account, you can charge application fees for conversions booked by your connected accounts. See Application fees.
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.