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.

Time-Sensitive Token: The returned token is short-lived and expires at fxRateExpireDt. Execute your FX order via the Create FX Order API immediately after receiving the token to ensure the locked rate remains valid.

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"

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.

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

{
  "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

{
  "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

curl -X POST "https://{base_url_openapi}/v2/gc/fx/inquiry" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -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.