> For the complete documentation index, see [llms.txt](https://docs.neox.vn/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neox.vn/docs/global/global-collections/integration/fx/api-fx-inquiry.md).
# FX Inquiry
#### Endpoint: POST /v2/gc/fx/inquiry
#### Description: Lock an FX rate for a currency conversion and obtain a short-lived quote token to execute the trade via the Create FX Order API.
{% hint style="warning" %}
**Time-Sensitive Token:** The returned `token` is short-lived and expires at `fxRateExpireDt`. Execute your FX order via the [Create FX Order API](/docs/global/global-collections/integration/fx/api-create-fx-order.md) immediately after receiving the token to ensure the locked rate remains valid.
{% endhint %}
## Request
#### Request Body Field Descriptions (JSON)
| Field Name | Type | Required | Description |
| -------------- | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| requestId | string | Yes | Unique request ID (*UUID recommended*) used for idempotency. |
| sourceCurrency | string | Yes | ISO 4217 currency code of the currency to convert from (e.g. `USD`). |
| targetCurrency | string | Yes | ISO 4217 currency code of the currency to convert to (e.g. `CNH`). |
| sourceAmount | number | No | Amount in `sourceCurrency` to convert. Provide exactly one of `sourceAmount` or `targetAmount`. |
| targetAmount | number | No | Amount in `targetCurrency` the merchant wishes to receive. Provide exactly one of `sourceAmount` or `targetAmount`. |
| fxType | string | No | FX settlement type. Enum: `TOD` (today) \| `TOM` (tomorrow) \| `SPOT` \| `FORWARD_1W` \| `FORWARD_2W` \| `FORWARD_1M` \| `BROKEN` (broken-date forward). |
| deliveryDate | date string | No | Requested delivery date for forward FX types (ISO 8601, `YYYY-MM-DD`). Required when `fxType=BROKEN`. |
fxType - FX Settlement Type
Specifies the settlement timeline for the foreign exchange transaction. Supported values:
| FX Type | Description |
| ------------ | ----------------------------------------------------------------------------------- |
| `TOD` | **Real-time currency exchange** (default). Settlement occurs today (T+0). |
| `TOM` | **Tomorrow settlement** (T+1). FX conversion settles the next business day. |
| `SPOT` | **Spot settlement** (T+2). Standard spot FX delivery in two business days. |
| `FORWARD_1W` | **Forward 1 Week**. Settlement occurs one week from the trade date. |
| `FORWARD_2W` | **Forward 2 Weeks**. Settlement occurs two weeks from the trade date. |
| `FORWARD_3W` | **Forward 3 Weeks**. Settlement occurs three weeks from the trade date. |
| `FORWARD_1M` | **Forward 1 Month**. Settlement occurs one month from the trade date. |
| `BROKEN` | **Broken-date forward**. Non-standard settlement date specified via `deliveryDate`. |
**Notes:**
* If omitted, defaults to `TOD` (real-time exchange).
* For `BROKEN`, you **must** provide the `deliveryDate` parameter with the exact settlement date (ISO 8601, `YYYY-MM-DD`).
* Forward contracts (`FORWARD_*` and `BROKEN`) lock the FX rate for future settlement and may have different pricing than spot rates.
**Example:** `"fxType": "SPOT"`
{% hint style="info" %}
**Supported Currency Pairs by FX Type:**
The available currency pairs vary by settlement type. Ensure your `sourceCurrency` and `targetCurrency` combination is supported for your chosen `fxType`:
**Note:** TOD (real-time) supports the widest range of currency pairs. TOM and SPOT settlement types are limited to USD/CNH and HKD/CNH pairs only.
{% endhint %}
| FX Type | Supported Currency Pairs |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **TOD** (T+0) | USDCNH, CNHUSD, USDHKD, HKDUSD, USDAUD, AUDUSD, CADUSD, USDDKK, DKKUSD, USDEUR, EURUSD, USDGBP, GBPUSD, USDGHS, GHSUSD, USDIDR, IDRUSD, USDJPY, JPYUSD, USDKES, KESUSD, USDKRW, KRWUSD, USDMYR, MYRUSD, USDNGN, NGNUSD, USDPHP, USDSEK, SEKUSD, USDSGD, SGDUSD, USDTHB, THBUSD, USDUGX, UGXUSD, USDVND, VNDUSD, USDZAR, ZARUSD, USDZMW, ZMWUSD, EURAUD, AUDEUR, EURGBP, GBPEUR, EURJPY, JPYEUR, EURSGD, SGDEUR, EURCNH, CNHEUR, EURHKD, HKDEUR, GBPAUD, AUDGBP, GBPJPY, JPYGBP, GBPSGD, SGDGBP, GBPHKD, HKDGBP, GBPCNH, CNHGBP, AUDJPY, JPYAUD, AUDSGD, SGDAUD, AUDHKD, HKDAUD, AUDCNH, CNHAUD, CADAUD, CADHKD, CADEUR, CADGBP, CADJPY, CADSGD, CADCNH, CNHJPY, JPYCNH, CNHSGD, SGDCNH, CNHHKD, HKDCNH, CNHKRW, KRWCNH, CNHSEK, SEKCNH, CNHDKK, DKKCNH, CNHMYR, MYRCNH, CNHNGN, NGNCNH, CNHPHP, CNHTHB, THBCNH, CNHIDR, IDRCNH, CNHVND, VNDCNH, CNHUGX, UGXCNH, CNHZAR, ZARCNH, CNHZMW, ZMWCNH, CNHGHS, GHSCNH, CNHKES, KESCNH, HKDSGD, SGDHKD, HKDJPY, JPYHKD, HKDGBP, HKDEUR, SGDJPY, JPYSGD, USDCHF, CHFUSD, CNHCHF, CHFCNH, AEDUSD, AEDCNH |
| **TOM** (T+1) | USDCNH, CNHUSD, HKDCNH, CNHHKD |
| **SPOT** (T+2) | USDCNH, CNHUSD, HKDCNH, CNHHKD |
| **Forward Types** | Same as general supported pairs (contact support for availability by specific forward term) |
#### Request sample
```json
{
"requestId": "c3d4e5f6-3333-4444-5555-ccddeeff0011",
"sourceCurrency": "USD",
"targetCurrency": "CNH",
"sourceAmount": 10000.00,
"fxType": "SPOT"
}
```
### Response
#### Response Field Descriptions
| Field Name | Type | Description |
| ------------- | ------ | --------------------------------------------- |
| code | number | Response code. |
| state | number | State of the response. |
| data | object | FX inquiry result including the locked token. |
| message | string | Response message. |
| neoResponseId | string | Unique NeoX response identifier. |
#### `data` object fields:
| Field Name | Type | Description |
| -------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| fxRate | number | Locked FX rate between `sourceCurrency` and `targetCurrency`. |
| token | string | Short-lived quote token. Pass this value in the `token` field of the Create FX Order API. |
| fxRateExpireDt | date string | Timestamp after which the `token` and the locked rate are no longer valid (ISO 8601). Execute the order before this time. |
| deliveryDt | date string | Expected settlement delivery date for the FX conversion (ISO 8601). |
#### Response sample
```json
{
"code": 1,
"state": 2,
"data": {
"fxRate": 7.2815,
"token": "FX-TOKEN-9e1f2a3b-cc44-5d6e-bf7a-8899aabbcc00",
"fxRateExpireDt": "2024-08-15T10:30:00Z",
"deliveryDt": "2024-08-17T00:00:00Z"
},
"message": "Successful",
"neoResponseId": "ac23ea1c-98db-4ed6-b927-7e7692ef2f69"
}
```
## Example cURL
```bash
curl -X POST "https://{base_url_openapi}/v2/gc/fx/inquiry" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-H "Accept-Language: en" \
-d '{
"requestId": "c3d4e5f6-3333-4444-5555-ccddeeff0011",
"sourceCurrency": "USD",
"targetCurrency": "CNH",
"sourceAmount": 10000.00,
"fxType": "SPOT"
}'
```
### Notes
* Requires Bearer token in the Authorization header.
* The Accept-Language header can be used to specify the response language (Support: "vi", "en").
* Use a unique `requestId` for each request to avoid duplicate inquiries.
* Provide exactly one of `sourceAmount` or `targetAmount`; providing both or neither will result in an error.
* The returned `token` must be passed to the Create FX Order API (`POST /v2/gc/fx/orders`) before `fxRateExpireDt` is reached.
* For forward FX types (`FORWARD_1W`, `FORWARD_2W`, `FORWARD_1M`, `BROKEN`), the `deliveryDate` parameter specifies the desired settlement date. `BROKEN` requires an explicit `deliveryDate`.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.neox.vn/docs/global/global-collections/integration/fx/api-fx-inquiry.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.