Foreign Exchange

FX Trade

Receive real-time foreign exchange rates and initiate currency conversions.

Sandbox

The sandbox environment is functionally identical to production, the technical and authorization documentation applies to both environments.

The sandbox environment enables you to trigger scenarios where you can develop and test your code against all possible outcomes and HTTP status codes.

Quotes stay tradable for 90 seconds, which is substantially longer than production. Quotes and orders created in the sandbox environment will be purged after 14 days, or when the number exceeds 5000.

Access

To access to the Sandbox, see overview. The sandbox environment is located at: https://api-sandbox.abnamro.com.

For ease of use, we provide a private/public key pair that can be used to get an access token from the authentication endpoint. The private/public key can be used for other API products in sandbox as well and represents the method of how to obtain an access token in production. The clientId to be used as part of the request to the authentication server is API_client.

For convenience a PKCS#12 keystore is provided that contains the private and public key (no passwords set):

Client authentication files
Download | Private key file
Download | Public certificate file
Download | PKCS#12 keystore

Next to the production way of obtaining an access token, we provide for sandbox an easier way to get a token via basic authentication (id=FXAPI, password=z5l2KRWEXnmDvBhssPq7). Find below the example request for getting an access token for all possible operations for the FX Trade API:

curl -u FXAPI:z5l2KRWEXnmDvBhssPq7 \
     -X POST https://auth-sandbox.connect.abnamro.com/as/token.oauth2 \
     -d 'grant_type=client_credentials&scope=fxtrade:allowedcurrencypairs:read fxtrade:settlementaccountgroups:read fxtrade:rates:read fxtrade:quotes:read fxtrade:quotes:write fxtrade:orders:read fxtrade:orders:write'

Note: once you passed basic testing you are advised to switch to TLS-MA for obtaining the access token as that represents the mechanism used in production.

Supported currency pairs

In the sandbox environment, the following currency pairs are available and can be traded, this applies to the inverse pair. Each currency pair has a cutoff time in UTC that dictates whether settlement for the tenor TODAY can still take place. For all currencies, official bank-holidays are observed. It is possible to trade a currency pair for which a cross can be performed.

Currency Pair Cutoff (UTC)
EURUSD 16:00
USDJPY 16:00
GBPUSD 16:00
AUDUSD 16:00
USDCHF 13:30
NZDUSD 16:00
USDCAD 17:00
EURRON 10:30
USDMXN 16:00

Supported settlement account groups

When performing an FX order the settlement account group must be provided. In production this determines the currency accounts to be used in the settlement of a sum of money. In sandbox the following settlement accounts groups are supported: Client Account, House Account.

Supported outcomes of operations

We differentiate between the following 3 types of outcomes for operations in the sandbox environment:

  • Successful: the operations that return a response that contains a 2xx status code, and which do not fall in the category 'partially successful'
  • Partially successful: the POST operations for a quote or order that return a response that contains a 2xx status code, but for which the status of the quote or order returned is not considered 'final'. The client must perform a GET operation to find out whether the quote or order status reaches a final state
  • Unsuccessful: the operations that return a response that contains a 4xx or 5xx status code
Partially successful operations

The following section describes how to trigger and test for partially successful operations.

Slow responses

In general, all responses to POST requests for an FX quote or order that do not go into intervention, will return within 200 ms. To simulate a slow response, one out of ten POST requests in the sandbox will provide a response time in-between 200 and 1500 ms. Use this feature combined with the optional maxWaitTime query parameter, that is smaller than 1500, to test for the scenario where the response does not contain the final state.

Intervention

When requesting an FX quote for which the buy or sell amount exceeds 100.000,- intervention will be triggered, this is regardless of the currency pair involved. The time it takes for the intervention to result in either a REJECTED or QUOTED status will be between 5 and 90 seconds. For each intervention one out of five interventions will result in a status of REJECTED, the others will result in a QUOTED status.

Rejection

Performing an FX quote request for the tenor TODAY after the cutt-off time has been reached for the currency pair used, will result in a status of REJECTED.

Unsuccessful operations

Most client errors, i.e. a response with a 4xx status code, can be triggered by providing an illegal request, wrong request headers, or the wrong token as documented in Technical. To trigger other HTTP return codes, such as 429, 500 and 503 see the sections below.

429 Too Many Requests

When requests are executed in a way that exceeds certain thresholds, a response with the 429 status code will be returned. This can be triggered in the sandbox environment by requesting indicative rates with a frequency of one request per 5 seconds for a prolonged period.

500 Internal Server Error

A response with this status code is not likely to occur in production, but can be triggered in the sandbox environment by requesting an FX quote that involves the currencies 'MXN' and 'CHF'.

503 Service Unavailable

In circumstances where the service is not able to handle an incoming request and the expectation is that the underlying cause will be solved in short notice. In these circumstances the 503 status code will be returned in the response. The response will also contain the Retry-After header as specified in RFC 7231 and its value will be set to the number of seconds in which the service is expected to be available again.

This scenario can be triggered by requesting an FX quote that involves the currencies 'MXN' and 'RON'.