> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Exchange Rates

> Query current FX rates before creating conversions or cross-currency payouts.

Use exchange rates to check whether UQPAY has a current rate for a currency pair before you create a conversion or cross-currency payout. The [List Current Rates](/global-account/v1.6/api-reference/list-current-rates) API returns the latest available rates for one or more currency pairs, plus any requested pairs that are currently unavailable.

Exchange rates are useful for discovery, pricing previews, and operational checks. They do not create a `quote_id` and do not reserve a rate for execution. To execute a conversion or cross-currency payout, create a quote immediately before submitting the transaction.

## When to use exchange rates

Call [List Current Rates](/global-account/v1.6/api-reference/list-current-rates) when you need to:

* Show available FX pairs in your UI.
* Check whether a currency pair is currently supported before calling [Create Quote](/global-account/v1.6/api-reference/create-quote).
* Refresh indicative buy and sell prices for treasury or operations teams.
* Detect unsupported or temporarily unavailable pairs through `unavailable_currency_pairs`.
* Run pricing checks for a master account or a sub-account before creating a conversion or payout.

For an executable rate, use [Create Quote](/global-account/v1.6/api-reference/create-quote). The quote response returns a `quote_id`, the calculated `buy_amount` or `sell_amount`, and a validity window.

## Exchange rates versus quotes

| Capability                                 | List Current Rates                                         | Create Quote                                             |
| ------------------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------- |
| Primary purpose                            | Check current available rates and pair availability.       | Lock the transaction parameters for execution.           |
| Returns a `quote_id`                       | No                                                         | Yes                                                      |
| Calculates exact transaction amount        | No                                                         | Yes                                                      |
| Has a validity window                      | Response includes `last_updated`, but no execution window. | Quote must be used within its `validity` window.         |
| Used by Create Conversion or Create Payout | No, use it for pre-checks only.                            | Yes, pass the returned `quote_id` to the create request. |

`buy_price` and `sell_price` are for rate previews and currency-pair availability checks only. They are not executable rates and do not lock the final transaction amount. When a customer confirms a conversion or cross-currency payout, call Create Quote and use the returned `quote_id` and calculated amounts.

## Step 1: Query current rates

You can query specific currency pairs or omit `currency_pairs` to return all available pairs.

### Query selected currency pairs

Pass `currency_pairs` as a comma-separated list. Each pair must be a six-letter uppercase code such as `USDEUR` or `USDJPY`. You can request up to 100 pairs.

```bash theme={null}
curl --location 'https://api-sandbox.uqpaytech.com/api/v1/exchange/rates?currency_pairs=USDEUR,USDJPY,JPYKRW' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}'
```

### Query all available rates

Omit `currency_pairs` when you need the full list of currently available currency pairs.

```bash theme={null}
curl --location 'https://api-sandbox.uqpaytech.com/api/v1/exchange/rates' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}'
```

If you are checking rates for a sub-account, include the sub-account ID in `x-on-behalf-of`.

```bash theme={null}
curl --location 'https://api-sandbox.uqpaytech.com/api/v1/exchange/rates?currency_pairs=USDSGD' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}' \
  --header 'x-on-behalf-of: {{sub_account_id}}'
```

## Step 2: Read the response

A successful response wraps the result in a `data` object: available rates in `data.rates`, unavailable requested pairs in `data.unavailable_currency_pairs`, and the rate timestamp in `data.last_updated`.

```json theme={null}
{
  "data": {
    "rates": [
      {
        "currency_pair": "USDEUR",
        "buy_price": "0.8688",
        "sell_price": "0.8757"
      },
      {
        "currency_pair": "USDJPY",
        "buy_price": "161.4914",
        "sell_price": "162.7986"
      }
    ],
    "unavailable_currency_pairs": [
      "JPYKRW"
    ],
    "last_updated": "2026-07-16T16:15:58+08:00"
  }
}
```

| Field                        | Meaning                                                                                                         |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `rates`                      | The rate records currently available for the requested pairs, or all available pairs if no filter was provided. |
| `currency_pair`              | The pair that the rate applies to. The order may follow market convention, so always read the returned value.   |
| `buy_price`                  | The current buy price, rounded to 4 decimal places.                                                             |
| `sell_price`                 | The current sell price, rounded to 4 decimal places.                                                            |
| `unavailable_currency_pairs` | Requested pairs that are unsupported or have no available rate at the moment.                                   |
| `last_updated`               | The timestamp of the last rate update in ISO 8601 format.                                                       |

If a requested pair appears in `unavailable_currency_pairs`, do not continue to quote creation for that pair. Show a clear message to the user or route the transaction through another supported currency pair.

## Step 3: Use rates before creating a quote

Use List Current Rates as a pre-check, then use Create Quote when the user or system is ready to execute.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant UQPAY

    Client->>UQPAY: List Current Rates
    UQPAY-->>Client: Available rates and unavailable pairs
    Client->>Client: Display rate preview or validate pair
    Client->>UQPAY: Create Quote
    UQPAY-->>Client: quote_id, calculated amount, validity window
    Client->>UQPAY: Create Conversion or Create Payout with quote_id
```

Recommended flow:

1. Query current rates for the pair you plan to use.
2. If the pair is unavailable, stop the flow and ask the user to choose another pair.
3. If the pair is available, show the rate preview or continue to your approval flow.
4. Immediately before execution, call [Create Quote](/global-account/v1.6/api-reference/create-quote).
5. Submit [Create Conversion](/global-account/v1.6/api-reference/create-conversion) or [Create Payout](/global-account/v1.6/api-reference/create-payout) with the returned `quote_id` within the quote validity window.

## Sub-account pricing

The endpoint accepts `x-on-behalf-of`. Use it when you need the rate context for a specific sub-account:

* For a master account operation, omit `x-on-behalf-of`.
* For a sub-account operation, set `x-on-behalf-of` to the sub-account `account_id`.
* Use the same account context when you later call Create Quote and the corresponding create endpoint.

Keeping the same account context avoids mismatches in FX product configuration, currency enablement, and pricing.

## Common validation issues

| Issue                                              | How to resolve                                                                                        |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `currency_pairs` contains lowercase values         | Send six-letter uppercase pairs such as `USDEUR`.                                                     |
| More than 100 pairs are requested                  | Split the request into multiple calls.                                                                |
| A pair is returned in `unavailable_currency_pairs` | Do not create a quote for that pair. Select another supported pair or try again later.                |
| Create Quote fails after rates looked available    | Confirm the account context, FX product configuration, quote `transaction_type`, and conversion date. |
| The displayed rate differs from the quote rate     | The quote is the executable rate. Refresh the preview and create a new quote before execution.        |

## Related API reference

* [List Current Rates](/global-account/v1.6/api-reference/list-current-rates)
* [Create Quote](/global-account/v1.6/api-reference/create-quote)
* [Create Conversion](/global-account/v1.6/api-reference/create-conversion)
* [Create Payout](/global-account/v1.6/api-reference/create-payout)

## Related guides

* [Create Conversion via API](/global-account/v1.6/guide/create-conversion-via-api)
* [Cross-Currency Payout Guide](/global-account/v1.6/guide/cross-currency-payout-guide)