Quotes

Create a quote that can be used in a subsequent conversion request during the requested validity period.

Endpoints

POST /api/v1/fx/quotes/create
GET /api/v1/fx/quotes/{quote_id}

Create a quote

POST /api/v1/fx/quotes/create

Copy for LLMView as Markdown

The Quote endpoint gives the user a guaranteed rate for an agreed period of time.

Request body

buy_currencyrequiredstring

Currency (3-letter ISO-4217 code) the client buys

sell_currencyrequiredstring

Currency (3-letter ISO-4217 code) the client sells. This is the currency you will need to send us by the settlement cutoff time

validityrequiredstring

Quote validity period. Available options: [MIN_1, MIN_15, MIN_30, HR_1, HR_4, HR_8, HR_24]

application_fee_optionsarray

The application fee options applied to the transaction.

application_fee_options.amountstring

A positive integer specifying the amount of the fee expressed in the smallest unit of the currency. e.g. cents for USD. This field is required only when type is FIXED.

application_fee_options.currencystring

Specify the currency of the application fee in ISO 4217 currency code format, e.g., USD, AUD. This field is required when the type is FIXED.
When the type is PERCENTAGE and source_type is CONVERSION, the currency for the conversion if specified must be from the currency pair. If the currency is unspecified, the contra currency of the quote will be used.

application_fee_options.metadataobject

The metadata of the application fee. The value should be set in key:value format. (e.g., id:1).

application_fee_options.percentagestring

Required if the type is PERCENTAGE, and the value to be provided depends on the transaction context.
FX Conversions: The value acts as a markup on the FX rate, increasing the conversion cost by the specified percentage.
Others: The value represents a direct fee calculated as a percentage of the transaction amount.

application_fee_options.source_typestring

Specify type of the source transaction.

CONVERSION, TRANSFER

application_fee_options.typestring

Define the type of fee calculation. If the source_type is CONVERSION, then the type must be PERCENTAGE.

FIXED, PERCENTAGE

buy_amountnumber

Amount the client buys in buy_currency (must be blank if sell_amount is specified)

conversion_datestring

Date on which the conversion will be settled. conversion_date defaults to current date, if funding is available, unless specified.

sell_amountnumber

Amount the client sells in sell_currency (must be blank if buy_amount is specified)

Response body - 201 Created

application_feesarray

Application fees in this transaction.

application_fees.amountstring

The application fee amount.

application_fees.currencystring

The currency of the application fee.

application_fees.source_typestring

Specify the type of source transaction for this application fee.

CONVERSION, TRANSFER

awx_ratenumber

For reference purposes only. This is a reference rate Airwallex compiles by analyzing prices across multiple banking providers and independent rate publishers

buy_amountnumber

buy_amount copied from the Quote request (if specified). Otherwise, this is calculated by multiplying/dividing the sell_amount by the FX quote depending on the direction of the currency pair

buy_currencystring

Buy currency of the quote (3-letter ISO-4217 code)

client_ratenumber

The returned quote

conversion_datestring

Date on which the conversion will be settled. conversion_date defaults to current date, if funding is available, unless specified.

currency_pairstring

The currency pair that the quote is for. The direction of the currency pair is per market convention where possible

dealt_currencystring

The currency where the client provided the exact amount for in the request

mid_ratenumber

For reference purposes only. This rate represents the midpoint of the current bid and ask price

quote_idstring

The quote unique identifier

rate_detailsarray

Breakdown of rates at different user levels.

rate_details.buy_amountnumber

The total amount being bought at the respective level.

rate_details.levelstring

Supported levels include: CLIENT, AWX, PLATFORM_CLIENT

rate_details.ratenumber

The exchange rate from the respective level's perspective.

rate_details.sell_amountnumber

The total amount being sold at the respective level.

sell_amountnumber

sell_amount copied from the Quote request (if specified). Otherwise, this is calculated by multiplying/dividing the buy_amount by the FX quote depending on the direction of the currency pair

sell_currencystring

Sell currency of the quote (3-letter ISO-4217 code)

usagestring

Quote usage, SINGLE_USE or MULTI_USE

valid_from_atstring

Quote valid from in ISO8601 format (inclusive)

valid_to_atstring

Quote valid to in ISO8601 format (inclusive)

validitystring

Quote validity period in the create request

MIN_1, MIN_15, MIN_30, HR_1, HR_4, HR_8, HR_24

Errors

Error status	Description
400	Possible errors: `amount_below_limit`, `amount_above_limit`, `operation_failed`, `field_required`, `invalid_settlement_date`, `invalid_endpoint`, `invalid_argument`, `unsupported_currency`
401	Possible errors: `credentials_invalid`, `credentials_expired`
429	Too many requests
500	Service unavailable

POST /api/v1/fx/quotes/create

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/fx/quotes/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "application_fee_options": [
>    {
>      "amount": "5",
>      "currency": "AUD",
>      "percentage": "0.1",
>      "source_type": "TRANSFER",
>      "type": "FIXED"
>    }
>  ],
>  "buy_amount": 10000,
>  "buy_currency": "AUD",
>  "conversion_date": "2017-04-01",
>  "sell_amount": 100,
>  "sell_currency": "USD",
>  "validity": "HR_24"
>}'

Response (201 Created)

1{
2  "application_fees": [
3    {
4      "amount": "5",
5      "currency": "AUD",
6      "source_type": "TRANSFER"
7    }
8  ],
9  "awx_rate": 0.7622,
10  "buy_amount": 10000,
11  "buy_currency": "AUD",
12  "client_rate": 0.7632,
13  "conversion_date": "2017-04-01",
14  "currency_pair": "AUDUSD",
15  "dealt_currency": "AUD",
16  "mid_rate": 0.7612,
17  "quote_id": "a08c0f2f-3f26-4443-b5df-fad15582eb94",
18  "rate_details": [
19    {
20      "buy_amount": 10000,
21      "level": "CLIENT",
22      "rate": 0.781523,
23      "sell_amount": 12794.27
24    }
25  ],
26  "sell_amount": 7632,
27  "sell_currency": "USD",
28  "usage": "SINGLE_USE",
29  "valid_from_at": "2019-05-03T02:49:05+0000",
30  "valid_to_at": "2019-05-04T02:49:05+0000",
31  "validity": "HR_24"
32}

Was this section helpful?

Retrieve a quote

GET /api/v1/fx/quotes/{quote_id}

Copy for LLMView as Markdown

Get a specific quote by specifying the quote_id.

Parameters

quote_idrequiredstring

Unique identifier of the quote to retrieve.

Response body - 200 OK

application_feesarray

Application fees in this transaction.

application_fees.amountstring

The application fee amount.

application_fees.currencystring

The currency of the application fee.

application_fees.source_typestring

Specify the type of source transaction for this application fee.

CONVERSION, TRANSFER

awx_ratenumber

For reference purposes only. This is a reference rate Airwallex compiles by analyzing prices across multiple banking providers and independent rate publishers

buy_amountnumber

buy_amount copied from the Quote request (if specified). Otherwise, this is calculated by multiplying/dividing the sell_amount by the FX quote depending on the direction of the currency pair

buy_currencystring

Buy currency of the quote (3-letter ISO-4217 code)

client_ratenumber

The returned quote

conversion_datestring

Date on which the conversion will be settled. conversion_date defaults to current date, if funding is available, unless specified.

currency_pairstring

The currency pair that the quote is for. The direction of the currency pair is per market convention where possible

dealt_currencystring

The currency where the client provided the exact amount for in the request

mid_ratenumber

For reference purposes only. This rate represents the midpoint of the current bid and ask price

quote_idstring

The quote unique identifier

rate_detailsarray

Breakdown of rates at different user levels.

rate_details.buy_amountnumber

The total amount being bought at the respective level.

rate_details.levelstring

Supported levels include: CLIENT, AWX, PLATFORM_CLIENT

rate_details.ratenumber

The exchange rate from the respective level's perspective.

rate_details.sell_amountnumber

The total amount being sold at the respective level.

sell_amountnumber

sell_amount copied from the Quote request (if specified). Otherwise, this is calculated by multiplying/dividing the buy_amount by the FX quote depending on the direction of the currency pair

sell_currencystring

Sell currency of the quote (3-letter ISO-4217 code)

usagestring

Quote usage, SINGLE_USE or MULTI_USE

valid_from_atstring

Quote valid from in ISO8601 format (inclusive)

valid_to_atstring

Quote valid to in ISO8601 format (inclusive)

validitystring

Quote validity period in the create request

MIN_1, MIN_15, MIN_30, HR_1, HR_4, HR_8, HR_24

Errors

Error status	Description
401	Possible errors: `credentials_invalid`, `credentials_expired`
404	Possible errors: `not_found`
429	Too many requests
500	Service unavailable

GET /api/v1/fx/quotes/{quote_id}

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/fx/quotes/quote_id' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "application_fees": [
3    {
4      "amount": "5",
5      "currency": "AUD",
6      "source_type": "TRANSFER"
7    }
8  ],
9  "awx_rate": 0.7622,
10  "buy_amount": 10000,
11  "buy_currency": "AUD",
12  "client_rate": 0.7632,
13  "conversion_date": "2017-04-01",
14  "currency_pair": "AUDUSD",
15  "dealt_currency": "AUD",
16  "mid_rate": 0.7612,
17  "quote_id": "a08c0f2f-3f26-4443-b5df-fad15582eb94",
18  "rate_details": [
19    {
20      "buy_amount": 10000,
21      "level": "CLIENT",
22      "rate": 0.781523,
23      "sell_amount": 12794.27
24    }
25  ],
26  "sell_amount": 7632,
27  "sell_currency": "USD",
28  "usage": "SINGLE_USE",
29  "valid_from_at": "2019-05-03T02:49:05+0000",
30  "valid_to_at": "2019-05-04T02:49:05+0000",
31  "validity": "HR_24"
32}

Was this section helpful?