WorldFirst DocsWorldFirst DocsDOCS

Get an FX quote

POST: /amsin/api/v1/business/fund/createQuote Signature required

The Partner can use this API to create a quote, which is a foreign exchange rate quoted in fixed units of the base currency against a certain amount of the quoted currency.

The Partner calls this API to create a quote for transactional foreign exchanges. If the Partner only needs foreign exchange rates for reference purposes, refer to the inquiryRate API.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request parameters

Field

Data type

Required

Description

customerId

String

Yes(Conditional)

The unique id that is assigned by WorldFirst to identify an account.

Note:

  • This field is not required when the Partner inquires about foreign exchange quotes.
  • This field is required when the Customer inquires about the foreign exchange quotes.
  • customerId and accessToken cannot be both empty.

More information:

  • Maximum length: 64 characters

accessToken

String

Yes(Conditional)

The access token that is used for OAuth authorization.

Note:

  • customerId and accessToken cannot be both empty.

More information:

  • Maximum length: 64 characters

sell

QuoteAmount object

Yes

The amount and the currency to be sold.

Note:

  • For sell.value and buy.value , one of the fields must be empty, and the other one must have value.
  • If the Partner needs to call createTransfer API subsequently, sell.value cannot be empty.

buy

QuoteAmount object

Yes

The amount and the currency to be bought.

Note:

  • For sell.value and buy.value , one of the fields must be empty, and the other one must have value.

exchangeTradeType

String

Yes

Defines the type of foreign exchange trading.

Possible values are:

  • SPOT: Using spot rate.
  • FORWARD: Using forward rate.

For the full list, refer to the exchangeTradeType.

quoteForwardInfo

quoteForwardInfo object

Yes(Conditional)

Information about the forward quotes.

Note:

  • This field is required when the exchangeTradeType is FORWARD.

Response parameters

Field

Data type

Required

Description

result

Result object

Yes

Indicates whether this API is called successfully.

responseId

String

Yes

The unique ID that is assigned by WorldFirst to identify a response.

More information:

  • Maximum length: 32 characters

quote

Quote object

Yes

Information about the quote, such as quote prices, quote start time and expiry time, etc.

sell

QuoteAmount object

Yes

The amount and the currency to be sold.

Note:

  • When making transfers, the Partner uses the value of sell.amount field as the transfer amount.

buy

QuoteAmount object

Yes

The amount and the currency to be bought.

Note:

  • When making transfers, the Partner uses the foreign exchange quotes associated with the buy.amount field.

exchangeTradeType

String

Yes

Defines the type of the foreign exchange trading.

Possible values are:

  • SPOT: Using spot rate.
  • FORWARD: Using forward rate.

For the full list, refer to the exchangeTradeType.

quoteForwardInfo

quoteForwardInfo object

Yes(Conditional)

Information about the forward quotes.

Note:

  • This field is required when the exchangeTradeType is FORWARD.

Result processing logic

After calling the API, a response is returned. The possible responses for result.resultStatus are:

Result status

Description

S

This indicates the API call succeeded. Get the value of quote.quotePrice and quote.quoteId.

F

This indicates the API call failed. For more information on why the call failed, see result.resultCode.

U

This indicates the API call result is unknown. Partner can make a query when the returned status is UNKNOWN. Use the following query strategy:

  • A Partner can make 7 queries at maximum.
  • Intervals between queries: 5m, 10m, 20m, 40m, 80m, 160m, and 320m.

If none of the queries is successful, contact our Technical Support Team.

Result codes

result.resultCode

System-related result codes

resultCode

resultStatus

resultMessage

Further action

SUCCESS

S

Success

PARAM_ILLEGAL

F

Illegal parameters exist. For example, a non-numeric input, or an invalid date.

Check and verify whether the request fields, including the header fields and body fields, are correct and valid.

For details on the fields of each API, see the specific API Structure section.

PROCESS_FAIL

F

A general business failure occurred. Do not retry.

Human intervention is usually needed. It is recommended that you contact our Technical Support Team to resolve the issue.

UNKNOWN_EXCEPTION

U

API failed due to unknown reason.

The service might be down, retry later. If the issue persists, contact our Technical Support Team.

REQUEST_TRAFFIC_EXCEED_LIMIT

U

The request traffic exceeds the limit.

Call the interface again to resolve the issue. If the issue persists, contact our Technical Support Team.

INVALID_API

F

The called API is invalid or not active.

Check whether the correct API is being called.

INVALID_CLIENT

F

The client is invalid.

The Client ID does not exist or is invalid.

INVALID_SIGNATURE

F

The signature is invalid.

Make sure the request is properly signed with a valid signature.

METHOD_NOT_SUPPORTED

F

The server does not implement the requested HTTP method.

Ensure the HTTP method is POST.

Business-related result codes

resultCode

resultStatus

resultMessage

Further action

UN_SUPPORT_BUSINESS

F

Unsupported business.

Invalid parameters are used. Retry with the correct information.

INVALID_ACCESS_TOKEN

F

Invalid access token

Check whether the accessToken is correct.

CURRENCY_NOT_SUPPORT

F

The currency is not supported.

Make sure the currency input is correct and try again.

CONTRACT_CHECK_FAIL

F

The contract check has failed.

Check the contract status before retrying.

Samples

Request

Request body sample

copy
{
    "customerId": "*****",
    "sell": {
        "currency": "SGD",
        "value": 2000
    },
    "buy": {
        "currency": "USD"
    },
    "exchangeTradeType": "SPOT"
}

Request calling samples

copy
var jsonStr="{\"customerId\":\"******\",\"sell\":{\"currency\":\"SGD\",\"value\":2000},\"buy\":{\"currency\":\"USD\"},\"exchangeTradeType\":\"SPOT\"}";
var client = new RestClient("http://{domain_name}.com/amsin/api/v1/business/fund/createQuote");
var request = new RestRequest(Method.POST);
request.AddHeader("client-id","*****");
request.AddHeader("request-time","2022-05-17T11:19:20+08:00");
request.AddHeader("Content-Type","application/json");
request.AddHeader("signature","algorithm=RSA256,keyVersion=1,signature=RckSOIrxy%2FKqC%2FZQOO0t74U9U4TFVYKmW%2FZflFRut7W1hipos3NLBGdpzbulcc5Q7XwZP1t3qgTZMFrC%2FlzOQCOsBhUgelvEAuACu49PEGiAus8sU%2FFJa1HOIUmst3oWjLT%2BDqY083mR7jVwc5O2JYP08wNCLu55PFZtXHBUfwEAYoZInhgRoLtQTr%2F7Bphd7L9cS3xD3tluxbgkcaFr7NQVrfWJuQKp%2BFrabo6xZr%2FRHZRd%2FijALuUYYjXH92n4VFwSXSO%2B%2BUBVPoGyWWz1q3QJ2tHNVU7wpc3wtCwwB76pNfGTbJit%2BdylGU8O5UkW3TwSkNnpzepRABM8bBQpgQ%*****");
request.AddParameter("application/json; charset=utf-8", jsonStr, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
copy
url = "http://{domain_name}.com/amsin/api/v1/business/account/createQuote"
headers = {
    "client-id": "*****",
    "request-time": "2022-05-17T11:19:20+08:00",
    "Content-Type": "application/json",
    "signature": "algorithm=RSA256,keyVersion=1,signature=RckSOIrxy%2FKqC%2FZQOO0t74U9U4TFVYKmW%2FZflFRut7W1hipos3NLBGdpzbulcc5Q7XwZP1t3qgTZMFrC%2FlzOQCOsBhUgelvEAuACu49PEGiAus8sU%2FFJa1HOIUmst3oWjLT%2BDqY083mR7jVwc5O2JYP08wNCLu55PFZtXHBUfwEAYoZInhgRoLtQTr%2F7Bphd7L9cS3xD3tluxbgkcaFr7NQVrfWJuQKp%2BFrabo6xZr%2FRHZRd%2FijALuUYYjXH92n4VFwSXSO%2B%2BUBVPoGyWWz1q3QJ2tHNVU7wpc3wtCwwB76pNfGTbJit%2BdylGU8O5UkW3TwSkNnpzepRABM8bBQpgQ%*****"
}
datas ={"customerId":"*****","sell":{"currency":"SGD","value":2000},"buy":{"currency":"USD"},"exchangeTradeType":"SPOT"}
res = requests.post(url=url, data=json.dumps(datas), headers=headers)
copy
CloseableHttpClient client = HttpClientBuilder.create().build();
HttpPost httpPost = new HttpPost("http://{domain_name}.com/amsin/api/v1/business/fund/createQuote");
httpPost.addHeader("client-id", "*****");
httpPost.addHeader("request-time", "2022-05-17T11:19:20+08:00");
httpPost.addHeader("signature","algorithm=RSA256,keyVersion=1,signature=RckSOIrxy%2FKqC%2FZQOO0t74U9U4TFVYKmW%2FZflFRut7W1hipos3NLBGdpzbulcc5Q7XwZP1t3qgTZMFrC%2FlzOQCOsBhUgelvEAuACu49PEGiAus8sU%2FFJa1HOIUmst3oWjLT%2BDqY083mR7jVwc5O2JYP08wNCLu55PFZtXHBUfwEAYoZInhgRoLtQTr%2F7Bphd7L9cS3xD3tluxbgkcaFr7NQVrfWJuQKp%2BFrabo6xZr%2FRHZRd%2FijALuUYYjXH92n4VFwSXSO%2B%2BUBVPoGyWWz1q3QJ2tHNVU7wpc3wtCwwB76pNfGTbJit%2BdylGU8O5UkW3TwSkNnpzepRABM8bBQpgQ%*****" );
httpPost.addHeader("Content-Type","application/json");
StringEntity entity = new StringEntity("{\"customerId\":\"******\",\"sell\":{\"currency\":\"SGD\",\"value\":2000},\"buy\":{\"currency\":\"USD\"},\"exchangeTradeType\":\"SPOT\"}");
httpPost.setEntity(entity);
CloseableHttpResponse response = client.execute(httpPost);
copy
var jsonStr="{\"customerId\":\"******\",\"sell\":{\"currency\":\"SGD\",\"value\":2000},\"buy\":{\"currency\":\"USD\"},\"exchangeTradeType\":\"SPOT\"}";
var client = "http://{domain_name}.com/amsin/api/v1/business/fund/createQuote";
var xhr = new XMLHttpRequest;
xhr.open("POST",client,true);
xhr.setRequestHeader("client-id","*****");
xhr.setRequestHeader("request-time","2022-05-17T11:19:20+08:00");
xhr.setRequestHeader("Content-Type","application/json");
xhr.setRequestHeader("signature","algorithm=RSA256,keyVersion=1,signature=RckSOIrxy%2FKqC%2FZQOO0t74U9U4TFVYKmW%2FZflFRut7W1hipos3NLBGdpzbulcc5Q7XwZP1t3qgTZMFrC%2FlzOQCOsBhUgelvEAuACu49PEGiAus8sU%2FFJa1HOIUmst3oWjLT%2BDqY083mR7jVwc5O2JYP08wNCLu55PFZtXHBUfwEAYoZInhgRoLtQTr%2F7Bphd7L9cS3xD3tluxbgkcaFr7NQVrfWJuQKp%2BFrabo6xZr%2FRHZRd%2FijALuUYYjXH92n4VFwSXSO%2B%2BUBVPoGyWWz1q3QJ2tHNVU7wpc3wtCwwB76pNfGTbJit%2BdylGU8O5UkW3TwSkNnpzepRABM8bBQpgQ%*****");
xhr.send(jsonStr);

Response

Response body sample

Success

copy
 {
     "buy":
     {
         "currency": "USD",
         "value": 1462
     },
     "exchangeTradeType": "SPOT",
     "quote":
     {
         "quoteCurrencyPair": "USD/SGD",
         "quoteExpiryTime": "2022-01-01T00:00:00Z",
         "quoteId": "*****",
         "quotePrice": 1.36764100,
         "quoteStartTime": "2022-01-01T00:00:00Z"
     },
     "responseId": "*****",
     "result":
     {
         "resultCode": "SUCCESS",
         "resultMessage": "success.",
         "resultStatus": "S"
     },
     "sell":
     {
         "currency": "SGD",
         "value": 2000
     }
 }

Failed due to unsupported currency

copy
{
    "result": {
        "resultCode": "CURRENCY_NOT_SUPPORT",
        "resultMessage": "The currency is not supported.",
        "resultStatus": "F"
    }
}

Failed due to illegal parameters

copy
{
    "result": {
        "resultCode": "PARAM_ILLEGAL",
        "resultMessage": "Illegal parameters. For example, non-numeric input, invalid date.",
        "resultStatus": "F"
    }
}

@2024 WorldFirst