Treasury

FX Trade

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

Technical

This topic describes how to build a client using the FX Trade API. For some quick API examples, see Tutorial.

Open API Specification

  • To download the OAS 3.0 FX Trade API, in .YAML format, click here.
  • To view the reference content and understand the full semantics of this service, open the .YAML file in a tool such as Swagger Editor.

Environments

Below you will find the URLs for the FX Trade API as well as the authentication server to be used for obtaining an access token. The URL for the authentication server depends on the type of authentication you use. The sandbox environment has two types of authentication. The production has one.

Environment Authentication URL Authentication (auth_url) URL API (api_url)
Sandbox Basic https://auth-sandbox.connect.abnamro.com/ https://api-sandbox.abnamro.com
TLS-MA https://auth-sandbox.connect.abnamro.com:8443/ https://api-sandbox.abnamro.com
Production TLS-MA https://auth.connect.abnamro.com:8443/ https://api.abnamro.com

General notes

Use this guide as a general reference only. For a more detailed description of this API, view the OpenAPI Specification .YAML file. This specification contains the definitions, the life-cycle description for quotes and orders, as well as the standardized messages that can be returned in case of rejection of quotes and orders.

If not otherwise stated the request and response body have the content type 'application/json'.

Scopes

Scopes define the specific actions that can be performed against the API. When an access token is obtained you must provide the scopes that you want. The following scopes are supported for this API:

Scope Operation
fxtrade:allowedcurrencypairs:read GET /v1/fxtrade/allowedcurrencypairs
fxtrade:settlementaccountgroups:read GET /v1/fxtrade/settlementaccountgroups
fxtrade:rates:read GET /v1/fxtrade/rates
GET /v1/fxtrade/rates/{currencyPair}
fxtrade:quotes:read GET /v1/fxtrade/quotes
GET /v1/fxtrade/quotes/{quoteId}
fxtrade:quotes:write POST /v1/fxtrade/quotes
fxtrade:orders:read GET /v1/fxtrade/orders
GET /v1/fxtrade/orders/{orderId}
fxtrade:orders:write POST /v1/fxtrade/orders

Getting an access token

Before you can access this service, you must obtain an access token from the authentication server by performing:

POST /as/token.oauth2

Request Attributes

The request body for this request is of the content type 'application/x-www-form-urlencoded'.

Name Type In Required Description
grant_type string body true The indicator of the type of flow being used, it should contain client_credentials
client_id string body true The ID that identifies you as an client
scope string body true Scope(s) for which the access token is to be created. Multiple scopes can be requested at once by separating them using a space
Sample Request
curl -X POST \
     {auth_url}/as/token.oauth2 \
     --cert {location_of_your_certificate} \
     --key {location_of_your_private_key} \
     -d 'grant_type=client_credentials&client_id={your_client_id}&scope={your_scope}'
Response Attributes
Name Type In Required Description
access_token string body true The access token which is used to access the API
token_type string body true The type of token provided
expires_in number body true Expiry time of the access token, in seconds
Sample Response
{
  "access_token": "{your_access_token}",
  "token_type": "Bearer",
  "expires_in": 3599
}

GET Allowed Currency Pairs

GET /v1/fxtrade/allowedcurrencypairs

Returns the currency pairs for which a spot or outright rate, quote, and order can be requested.

Request Attributes
Name Type In Required Description
Authorization string header true Access token to be passed as a Bearer token
API-Key string header true Consumer key obtained after app registration on developer portal
Sample Request
curl -X GET \
     {api_url}/v1/fxtrade/allowedcurrencypairs \
     -H "Accept: application/json" \
     -H "Authorization: Bearer {your_access_token}" \
     -H "API-Key: {your_api_key}"
Response Attributes
Name Type In Required Description
Trace-Id string header true Unique ID generated for every request
- string array body true An array of allowed currency pairs
Sample Response
[
  "EURUSD",
  "EURJPY",
  "USDSGD",
  "USDEUR",
  "SGDUSD"
]

GET Settlement Account Groups

GET /v1/fxtrade/settlementaccountgroups

Returns the settlement account group identifiers that are used to control the settlement of an amount for the FX spot, or outright trade, on the payment accounts at settlement date.

Request Attributes
Name Type In Required Description
Authorization string header true Access token to be passed as a Bearer token
API-Key string header true Consumer key obtained after app registration on developer portal
Sample Request
curl -X GET \
     {api_url}/v1/fxtrade/settlementaccountgroups \
     -H "Accept: application/json" \
     -H "Authorization: Bearer {your_access_token}" \
     -H "API-Key: {your_api_key}" 
Response Attributes
Name Type In Required Description
Trace-Id string header true Unique ID generated for every request
- string array body true An array of settlement account group identifiers
Sample Response
[
  "Client Account",
  "House Account"
]

GET Indicative Rates

GET /v1/fxtrade/rates

Returns the FX rates for the currency pairs you specified, are allowed to trade, and available prices.

The rates returned should be treated as indicative. They provide no guarantee that a trade, at this rate, can be performed at this moment in time.

Currency pairs provided that are not included in the list returned by GET /v1/fxtrade/allowedcurrencypairs will be silently ignored.

Request Attribute
Name Type In Required Description
Authorization string header true Access token to be passed as a Bearer token
API-Key string header true Consumer key obtained after app registration on developer portal
currencyPairs string array query true A comma separated list of currency pairs which will limit the FX rates returned
fxRateTenor string query false Indicates the tenor to use for the FX rate to be obtained, see for details settlement. Default value: SPOT
Sample Request
curl -X GET \
     "{app_url}/v1/fxtrade/rates?currencyPairs=EURUSD,EURJPY&fxRateTenor=SPOT" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer {your_access_token}" \
     -H "API-Key: {your_api_key}"
Response Attributes
Name Type In Required Description
Trace-Id string header true Unique ID generated for every request
FxInstrumentRate array body true An array of FX spot or outright rates
FxInstrumentRate Attributes
Name Type Required Description
currencyPair string true A currency pair represented by the combination of 2 ISO 4217 currency codes of the format XXXYYY, where XXX represents the base currency and YYY the quote currency
spotRate FxRate true Describes the FX spot rate in case of an FX outright
swapPoints SwapPoints false Provides the swap points in case this instrument represents an outright, a positive value represents a premium, a negative value a discount
allInRate FxRate false Describes the all-in-rate for an FX spot or outright
settlementDate string true The date the actual transfer of the cash involved in a trade would be completed on the customer accounts when an order would have been placed at the moment this rate was provided
FxRate Attributes
Name Type Required Description
bidRate number true Bid rate for the quoted currency in the currency pair, i.e. the rate the dealer is willing to pay for you selling your base currency and buying the quote currency
askRate number true Ask rate for the quoted currency in the currency pair, i.e. the rate the dealer asks for you buying your base currency while trading in the quote currency
midRate number false Calculated average between the bid and ask rate
effectiveDateTime string true Date and time the rates were published from the viewpoint of the service provider, the time component will include milliseconds and is in UTC time
SwapPoints Attributes
Name Type Required Description
bidPoints number true The swap points that needs to be added to the bid spot rate to represent the bid all-in-rate for the ouright. A positive value represents a premium, a negative value a discount
askPoints number true The swap points that needs to be added to the ask spot rate to represent the ask all-in-rate for the ouright. A positive value represents a premium, a negative value a discount
Sample Response
[
  {
    "currencyPair": "EURUSD",
    "allInRate": {
      "bidRate": 1.1400,
      "askRate": 1.1405,
      "midRate": 1.1403,
      "effectiveDateTime": "2018-11-02T09:25:43.324Z"
    },
    "settlementDate": "2018-11-06"
  },
  {
    "currencyPair": "EURJPY",
    "allInRate": {
      "bidRate": 128.53,
      "askRate": 128.57,
      "midRate": 128.55,
      "effectiveDateTime": "2018-11-02T09:25:44.324Z"
    },
    "settlementDate": "2018-11-06"
  }
]

GET Indicative Rate

GET /v1/fxtrade/rates/{currencyPair}

Returns the FX spot or outright rate for the currency pair specified.

The rate returned should be treated as indicative. It provides no guarantee that a trade, at this rate, can be performed at this moment in time.

Request Attributes
Name Type In Required Description
Authorization string header true Access token to be passed as a Bearer token
API-Key string header true Consumer key obtained after app registration on developer portal
currencyPair string path true A currency pair represented by the combination of 2 ISO 4217 currency codes of the format XXXYYY, where XXX represents the base currency and YYY the quote currency
fxRateTenor string query false Indicates the tenor to use for the FX rate to be obtained, see for details settlement. Default value: SPOT
Sample Request
curl -X GET \
     "{app_url}/v1/fxtrade/rates/EURUSD?fxRateTenor=TODAY" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer {your_access_token}" \
     -H "API-Key: {your_api_key}"
Response Attributes
Name Type In Required Description
Trace-Id string header true Unique ID generated for every request
FxInstrumentRate array body true The indicative FX spot or outright rate
Sample Response
{
  "currencyPair": "EURUSD",
  "spotRate": {
    "bidRate": 1.14,
    "askRate": 1.1405,
    "midRate": 1.1403,
    "effectiveDateTime": "2018-11-02T09:25:43.324Z"
  },
  "swapPoints": {
    "bidPoints": -0.0011,
    "askPoints": -0.0011
  },
  "allInRateRate": {
    "bidRate": 1.1389,
    "askRate": 1.1394,
    "midRate": 1.1402,
    "effectiveDateTime": "2018-11-02T09:25:43.325Z"
  },
  "settlementDate": "2018-11-02"
}

POST Quote

POST /v1/fxtrade/quotes

Submits a request for quote for an FX spot or outright.

Important: you can place one order only using a quote that is obtained using this method. If the same trade needs to be performed multiple times you must request for a quote for each trade.

Request Attributes
Name Type In Required Description
Authorization string header true Access token to be passed as a Bearer token
API-Key string header true Consumer key obtained after app registration on developer portal
maxWaitTime integer query false The maximum amount of time, in milliseconds, that the caller is willing to wait for this call to return a quote in the QUOTED or REJECTED state. If this period elapses, and the call did not return a QUOTED or REJECTED state, an FxQuote resource with a PENDING_NEW state will be returned. If not within the specified range it defaults to either the minimum or maximum. Default value: 500
FxQuoteRequest FxQuoteRequest body true The buy and sell currency together with the buy or sell amount and the tenor that defines the moment of cash settlement. An optional reference can be provided to correlate your request with the returned quote identifier
FxQuoteRequest Attributes
Name Type Required Description
consumerQuoteReference string false The customer reference for the FX quote request, which can be used later on to correlate the quote
quoteRequest FxRequest true Describes an FX request that can be used for both placing an FX spot or outright quote. A request must always contain the buy and sell currency and either the buy amount or the sell amount
settlementAccountGroup string true A settlement account group identifier used for the settlement of the money over payment accounts
FxRequest Attributes
Name Type Required Description
buyCurrency string true An ISO 4217 currency codes of the format XXX representing the buy currency
sellCurrency string true An ISO 4217 currency codes of the format XXX representing the sell currency
buyAmount number false A positive amount if the buy currency needs to be bought, either the buyAmount or sellAmount must be specified
sellAmount number false A positive amount if the sell currency needs to be sold, either the buyAmount or sellAmount must be specified
settlement string false An instruction for when the settlement of the cash amount must take place, see for details settlement
Sample Request
curl -X POST \
     "{app_url}/v1/fxtrade/quotes" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer {your_access_token}" \
     -H "API-Key: {your_api_key}" \
     -d '{
           "consumerQuoteReference": "SP-20181107-176",
           "quoteRequest": {
             "buyCurrency": "JPY",
             "sellCurrency": "EUR",
             "buyAmount": 1000,
             "settlement": "TODAY"
           },
           "settlementAccountGroup": "House Account"
         }'
Response Attributes
Name Type In Required Description
Trace-Id string header true Unique ID generated for every request
FxQuote FxQuote body true Describes the FX spot or outright quote, containing the original request data and the order execution data, data available depends on the status of the order
FxQuote Attributes
Name Type Required Description
quoteId string true The unique identifier for this quote
submittedDateTime string true The date and time the FX spot or outright request has been submitted, the time component will include milliseconds and is in UTC time
quoteStatus string true Status of the FX spot or outright quote. The status field follows the semantics as specified in the FIX protocol, see quote status
expirationDateTime string false The date and time till the FX spot or outright quote is valid, i.e. after the expiration date and time (as viewed by the service provider) no FX spot order can be placed with this quote as a reference. The time component will include milliseconds and is in UTC time. The time duration of this quote is the difference between the expirationDateTime and the submittedDateTime. This property is set when the quoteStatus is QUOTED or EXPIRED
message string false Optional message from the service provider related to this quote. If a quote has been rejected or went into intervention, this property will explain the reason. The message can contain standardized codes, for the meaning of these codes and the action to take consult the standardized codes
consumerQuoteReference string false The customer reference for the FX spot or outright quote, which can be used later on to correlate the FX spot quote
buyCurrency string true The buy currency from the quote request
sellCurrency string true The sell currency from the quote request
buyAmount number false The buy amount from the quote request, if any
sellAmount number false The sell amount from the quote request, if any
settlement string true The instruction for when the settlement must take place as in the quote request
currencyPair string false A currency pair represented by the combination of 2 ISO 4217 currency codes of the format XXXYYY, where XXX represents the base currency and YYY the quote currency
spotRate FxRate false Describes the FX spot rate in case of an FX outright
swapPoints SwapPoints false Provides the swap points in case this quote represents an outright, a positive value represents a premium, a negative value a discount
allInRate FxRate false Describes the all-in-rate for an FX spot or outright
contraAmount number false Represent the contra amount for the sell or buy amount that can be converted with the rate provided for the given currency pair as part of this quote. In case of a sell amount the contra amount is for the buy currency and represents the amount bought. In case of a buy amount the contra amount is for the sell currency snd represents the amount that needs to be paid. This property is set when the quoteStatus is QUOTED or EXPIRED
rate number false The FX rate effective for the quote, this is either the bid or ask rate from the allInRate property depending on the direction. This property is set when the quoteStatus is QUOTED or EXPIRED
settlementDate string true The date that a transfer, of an amount associated with a trade performed for this quote, is completed on the customer accounts
quoteSignature string false The cryptographic reference in Base64 encoding for this quote. This must be passed in the request payload for placing an order to ensure the order will be executed against the rate provided, as part of the quote, that is associated with this reference
Sample Response
{
  "quoteId": "2a3e4567-a79b-40a3-a456-036142440410",
  "submittedDateTime": "2018-11-07T10:03:08.519Z",
  "quoteStatus": "QUOTED",
  "expirationDateTime": "2018-11-07T10:03:13.519Z",
  "consumerQuoteReference": "SP-20181107-176",
  "buyCurrency": "JPY",
  "sellCurrency": "EUR",
  "buyAmount": 1000,
  "settlement": "TODAY",
  "currencyPair": "EURJPY",
  "spotRate": {
    "bidRate": 128.53,
    "askRate": 128.57,
    "midRate": 128.55,
    "effectiveDateTime": "2018-11-07T10:03:07.324Z"
  },
  "swapPoints": {
    "bidPoints": 0.02,
    "askPoints": 0.02
  },
  "allInRate": {
    "bidRate": 128.55,
    "askRate": 128.59,
    "midRate": 128.57,
    "effectiveDateTime": "2018-11-07T10:03:07.325Z"
  },
  "contraAmount": 7.78,
  "rate": 128.55,
  "settlementDate": "2018-11-07",
  "quoteSignature": "DET/IEOl3+ohSNqr0l1RywOkyqgjZ1JkGxxHxFkyHux6UUP71ybU6t4QWPg1dZ8NazY++v9nBP1+a3yKBRzMVK94QmwgHhWYTyO6f6iXj9VGKN2LH/qhAI2yzPz4DEAKCbc6H1ssw3yUT1QhAA=="
}

GET Quotes

GET /v1/fxtrade/quotes

Returns the FX spot and outright quotes that have been created. If multiple query parameters are provided they operate in 'AND' mode.

Request Attributes
Name Type In Required Description
Authorization string header true Access token to be passed as a Bearer token
API-Key string header true Consumer key obtained after app registration on developer portal
consumerQuoteReference string body false When provided, this parameter will be assessed as to whether it is equal to, or a substring of, the consumerQuoteReference property in the FX quote. If it is not equal, the FX quote will be excluded from the result set
quoteStatus array body false When provided the status of the FX quote must be in the provided set of status codes. Available values: NEW, PENDING_NEW, REJECTED, QUOTED, EXPIRED
startDateTime string body false Defines the start of an interval (inclusive) in which the FX spot or outright quote has been requested. If not provided, it defaults to 24 hours before the current moment. If no time zone information is provided as part of the parameter, as per RFC 3339, the date-time provided defaults to UTC
endDateTime string body false Defines the end of an interval (exclusive) in which the FX spot or outright quote has been requested. If not provided, it defaults to the current moment. If no time zone information is provided as part of the parameter, as per RFC 3339, the date-time provided defaults to UTC
nextPageKey string body false The reference to the next page. The value for this parameter should be taken from the nextPageKey property in the response from the previous request. For consistent behavior the query parameters should not change during traversal of the result set
pageSize number body false The maximum number of records returned in the result set, the service is permitted to return a number that is less than this value. If a very small small number is chosen the service is also permitted to return more records to be able to provide a consistent view over the complete result set when traversing via the nextPageKey. Defaults to 100
Sample Request
curl -X GET \
     "{app_url}/v1/fxtrade/quotes?startDateTime=2018-11-07T08%3A00%3A00Z&pageSize=500" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer {your_access_token}" \
     -H "API-Key: {your_api_key}"
Response Attributes
Name Type In Required Description
Trace-Id string header true Unique ID generated for every request
nextPageKey string body false The reference to the next page. If this property is not returned, the last page has been reached
FxQuote FxQuote array body true The Fx spot and outright quotes matching the criteria
Sample Response
{
  "nextPageKey": "2018-11-07T10:09:42.105Z",
  "records": [
    {
      "quoteId": "2a3e4567-a79b-40a3-a456-036142440410",
      "submittedDateTime": "2018-11-07T10:03:08.519Z",
      "quoteStatus": "QUOTED",
      "expirationDateTime": "2018-11-07T10:03:13.519Z",
      "consumerQuoteReference": "SP-20181107-176",
      "buyCurrency": "JPY",
      "sellCurrency": "EUR",
      "buyAmount": 1000,
      "settlement": "TODAY",
      "currencyPair": "EURJPY",
      "spotRate": {
        "bidRate": 128.53,
        "askRate": 128.57,
        "midRate": 128.55,
        "effectiveDateTime": "2018-11-07T10:03:07.324Z"
      },
      "swapPoints": {
        "bidPoints": 0.02,
        "askPoints": 0.02
      },
      "allInRate": {
        "bidRate": 128.55,
        "askRate": 128.59,
        "midRate": 128.57,
        "effectiveDateTime": "2018-11-07T10:03:07.325Z"
      },
      "contraAmount": 7.78,
      "rate": 128.55,
      "settlementDate": "2018-11-07",
      "quoteSignature": "DET/IEOl3+ohSNqr0l1RywOkyqgjZ1JkGxxHxFkyHux6UUP71ybU6t4QWPg1dZ8NazY++v9nBP1+a3yKBRzMVK94QmwgHhWYTyO6f6iXj9VGKN2LH/qhAI2yzPz4DEAKCbc6H1ssw3yUT1QhAA=="
    },
    ...
  ]
}

GET Quote

GET /v1/fxtrade/quotes/{quoteId}

Returns the FX spot or outright quote details for the specified quote ID.

Request Attributes
Name Type In Required Description
Authorization string header true Access token to be passed as a Bearer token
API-Key string header true Consumer key obtained after app registration on developer portal
quoteId string path true The unique reference for this quote
Sample Request
curl -X GET \
     "{app_url}/v1/fxtrade/quotes/2a3e4567-a79b-40a3-a456-036142440410" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer {your_access_token}" \
     -H "API-Key: {your_api_key}"
Response Attributes
Name Type In Required Description
Trace-Id string header true Unique ID generated for every request
FxQuote FxQuote body true The FX spot or outright quote
Sample Response
{
  "quoteId": "2a3e4567-a79b-40a3-a456-036142440410",
  "submittedDateTime": "2018-11-07T10:03:08.519Z",
  "quoteStatus": "QUOTED",
  "expirationDateTime": "2018-11-07T10:03:13.519Z",
  "consumerQuoteReference": "SP-20181107-176",
  "buyCurrency": "JPY",
  "sellCurrency": "EUR",
  "buyAmount": 1000,
  "settlement": "TODAY",
  "currencyPair": "EURJPY",
  "spotRate": {
    "bidRate": 128.53,
    "askRate": 128.57,
    "midRate": 128.55,
    "effectiveDateTime": "2018-11-07T10:03:07.324Z"
  },
  "swapPoints": {
    "bidPoints": 0.02,
    "askPoints": 0.02
  },
  "allInRate": {
    "bidRate": 128.55,
    "askRate": 128.59,
    "midRate": 128.57,
    "effectiveDateTime": "2018-11-07T10:03:07.325Z"
  },
  "contraAmount": 7.78,
  "rate": 128.55,
  "settlementDate": "2018-11-07",
  "quoteSignature": "DET/IEOl3+ohSNqr0l1RywOkyqgjZ1JkGxxHxFkyHux6UUP71ybU6t4QWPg1dZ8NazY++v9nBP1+a3yKBRzMVK94QmwgHhWYTyO6f6iXj9VGKN2LH/qhAI2yzPz4DEAKCbc6H1ssw3yUT1QhAA=="
}

POST Order

POST /v1/fxtrade/orders

Submits an order for an FX spot or outright based upon a quote that has been obtained by a previous request for quote.

When a spot or outright order is placed, based upon a quote that was obtained through a quote request, the 'quoteSignature' will be used to verify whether the quote is still valid and whether it was requested for exactly the same data. Any tampering of the quoteSignature will result in a REJECTED order.

An order will be executed against exactly the same rate as has been communicated for the underlying quote that has not yet expired.

Under very special circumstances it is possible to perform an order without obtaining a quote first, in such a case it will be executed as a 'market order'.

For each order, the settlement account group has to be supplied that is used for the purpose of trade settlement, the settlement account group name provided must be one that is returned by a request to GET /v1/fxtrade/settlementaccountgroups.

Request Attributes
Name Type In Required Description
Authorization string header true Access token to be passed as a Bearer token
API-Key string header true Consumer key obtained after app registration on developer portal
maxWaitTime integer query false The maximum amount of time, in milliseconds, that the caller is willing to wait for this call to return an order in the FILLED or REJECTED state. If this period elapses, and the call did not return a FILLED or REJECTED state, an FxOrder resource with a PENDING_NEW state will be returned. If not within the specified range it defaults to either the minimum or maximum. Default value: 500
FxOrderRequest FxOrderRequest body true The buy and sell currency together with the buy or sell amount and the tenor that defines the moment of settlement as well as the indicator that defines the accounts to use. An optional reference can be provided to correlate your request with the returned order identifier. A quote signature must be provided to execute an order based upon a quote that has been requested
FxOrderRequest Attributes
Name Type Required Description
consumerOrderReference string false The customer reference for the FX spot or outright order, which can be used later on to correlate the order
orderRequest FxRequest true Describes an FX request that can be used for both placing an FX spot or outright order, or for a request for quote. A request must always contain the buy and sell currency and either the buy amount or the sell amount
settlementAccountGroup string true A settlement account group identifier used for the settlement of the money over payment accounts
quoteSignature string true The cryptographic reference in Base64 encoding for this quote. This must be passed in the request payload for placing an order to ensure the order will be executed against the rate provided, as part of the quote, that is associated with this reference
Sample Request
curl -X POST \
     "{app_url}/v1/fxtrade/orders" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer {your_access_token}" \
     -H "API-Key: {your_api_key}" \
     -d '{
           "consumerOrderReference": "SP-20181107-13",
           "quoteRequest": {
             "buyCurrency": "JPY",
             "sellCurrency": "EUR",
             "buyAmount": 1000,
             "settlement": "TODAY"
           },
           "settlementAccountGroup": "House Account",
           "quoteSignature": "DET/IEOl3+ohSNqr0l1RywOkyqgjZ1JkGxxHxFkyHux6UUP71ybU6t4QWPg1dZ8NazY++v9nBP1+a3yKBRzMVK94QmwgHhWYTyO6f6iXj9VGKN2LH/qhAI2yzPz4DEAKCbc6H1ssw3yUT1QhAA==" 
         }'
Response Attributes
Name Type In Required Description
Trace-Id string header true Unique ID generated for every request
FxOrder FxOrder body true Describes the FX spot or outright order, containing the original request data and the order execution data, data available depends on the status of the order
FxOrder Attributes
Name Type Required Description
orderId string true The unique identifier for this order
submittedDateTime string true The date and time the FX spot or outright request has been submitted, the time component will include milliseconds and is in UTC time
orderStatus string true Status of the FX spot or outright order. The status field follows the semantics as specified in the FIX protocol, see order status
message string false Optional message from the service provider related to this order. If an order has been rejected or went into intervention, this property will explain the reason. The message can contain standardized codes, for the meaning of these codes and the action to take consult the standardized codes
consumerQuoteReference string false The customer reference for the FX spot or outright order, which can be used later on to correlate the FX spot order
buyCurrency string true The buy currency from the order request
sellCurrency string true The sell currency from the order request
buyAmount number false The buy amount from the order request, if any
sellAmount number false The sell amount from the order request, if any
settlement string true The instruction for when the settlement must take place as in the quote request
settlementAccountGroup string true A settlement account group identifier used for the settlement of the money over payment accounts
quoteId string false In case the FX spot or outright order was accompanied by a quoteSignature this identifier identifies the quote as in GET /v1/fxtrade/quotes/{quoteId}
currencyPair string false A currency pair represented by the combination of 2 ISO 4217 currency codes of the format XXXYYY, where XXX represents the base currency and YYY the quote currency
spotRate FxRate false Describes the FX spot rate in case of an FX outright
swapPoints SwapPoints false Provides the swap points in case this order represents an outright, a positive value represents a premium, a negative value a discount
allInRate FxRate false Describes the all-in-rate for an FX spot or outright
filledAmount number false The filled amount, i.e. the amount ('buy' currency) bought so far in case the order contained a buy amount, otherwise the amount ('sell' currency) sold so far when the sell amount was specified. In case the order is filled this amount must equal the buy or sell amount, in case of a partially filled order this value represents the amount bought or sold so far
contraAmount number false Represent the contra amount for the sell or buy amount that can be converted with the rate provided for the given currency pair as part of this quote. In case of a sell amount the contra amount is for the buy currency and represents the amount bought. In case of a buy amount the contra amount is for the sell currency snd represents the amount that needs to be paid. This property is set when the 'quoteStatus' is 'QUOTED' or 'EXPIRED'
rate number false The FX rate effective for the order, this is either the bid or ask rate from the 'allInRate' property depending on the direction. This property is set when the quoteStatus is QUOTED or EXPIRED
settlementDate string true The date that a transfer, of an amount associated with a trade, is completed on the customer accounts
Sample Response
{
  "orderId": "eec6b4c7-6b2f-477b-85fa-2d8dd1a07c4f",
  "submittedDateTime": "2018-11-07T10:03:09.925Z",
  "orderStatus": "FILLED",
  "consumerQuoteReference": "SP-20181107-136",
  "buyCurrency": "JPY",
  "sellCurrency": "EUR",
  "buyAmount": 1000,
  "settlement": "TODAY",
  "settlementAccountGroup": "House Account",
  "quoteId": "2a3e4567-a79b-40a3-a456-036142440410",
  "currencyPair": "EURJPY",
  "spotRate": {
    "bidRate": 128.53,
    "askRate": 128.57,
    "midRate": 128.55,
    "effectiveDateTime": "2018-11-07T10:03:07.324Z"
  },
  "swapPoints": {
    "bidPoints": 0.02,
    "askPoints": 0.02
  },
  "allInRate": {
    "bidRate": 128.55,
    "askRate": 128.59,
    "midRate": 128.57,
    "effectiveDateTime": "2018-11-07T10:03:07.325Z"
  },
  "filledAmount": 1000,
  "contraAmount": 7.78,
  "rate": 128.55,
  "settlementDate": "2018-11-07"
}

GET Orders

GET /v1/fxtrade/orders

Returns the FX spot and outright orders that have been created. If multiple query parameters are provided they operate in 'AND' mode.

Request Attributes
Name Type In Required Description
Authorization string header true Access token to be passed as a Bearer token
API-Key string header true Consumer key obtained after app registration on developer portal
consumerOrderReference string body false When provided, this parameter will be assessed as to whether it is equal to, or a substring of, the consumerOrderReference property in the FX order. If it is not equal, the FX order will be excluded from the result set
orderStatus array body false When provided the status of the FX order must be in the provided set of status codes. Available values: NEW, PENDING_NEW, FILLED, REJECTED, REJECTED_EXPIRED
startDateTime string body false Defines the start of an interval (inclusive) in which the FX spot or outright order has been requested. If not provided, it defaults to 24 hours before the current moment. If no time zone information is provided as part of the parameter, as per RFC 3339, the date-time provided defaults to UTC
endDateTime string body false Defines the end of an interval (exclusive) in which the FX spot or outright quote has been requested. If not provided, it defaults to the current moment. If no time zone information is provided as part of the parameter, as per RFC 3339, the date-time provided defaults to UTC
nextPageKey string body false The reference to the next page. The value for this parameter should be taken from the nextPageKey property in the response from the previous request. For consistent behavior the query parameters should not change during traversal of the result set
pageSize number body false The maximum number of records returned in the result set, the service is permitted to return a number that is less than this value. If a very small small number is chosen the service is also permitted to return more records to be able to provide a consistent view over the complete result set when traversing via the nextPageKey. Defaults to 100
Sample Request
curl -X GET \
     "{app_url}/v1/fxtrade/orders?startDateTime=2018-11-07T08%3A00%3A00Z&pageSize=500" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer {your_access_token}" \
     -H "API-Key: {your_api_key}"
Response Attributes
Name Type In Required Description
Trace-Id string header true Unique ID generated for every request
nextPageKey string body false The reference to the next page. If this property is not returned, the last page has been reached
FxOrder FxOrder array body true The Fx spot and outright orders matching the criteria
Sample Response
{
  "nextPageKey": "2018-11-07T10:42:01.086Z",
  "records": [
    {
      "orderId": "eec6b4c7-6b2f-477b-85fa-2d8dd1a07c4f",
      "submittedDateTime": "2018-11-07T10:03:09.925Z",
      "orderStatus": "FILLED",
      "consumerQuoteReference": "SP-20181107-136",
      "buyCurrency": "JPY",
      "sellCurrency": "EUR",
      "buyAmount": 1000,
      "settlement": "TODAY",
      "settlementAccountGroup": "House Account",
      "quoteId": "2a3e4567-a79b-40a3-a456-036142440410",
      "currencyPair": "EURJPY",
      "spotRate": {
        "bidRate": 128.53,
        "askRate": 128.57,
        "midRate": 128.55,
        "effectiveDateTime": "2018-11-07T10:03:07.324Z"
      },
      "swapPoints": {
        "bidPoints": 0.02,
        "askPoints": 0.02
      },
      "allInRate": {
        "bidRate": 128.55,
        "askRate": 128.59,
        "midRate": 128.57,
        "effectiveDateTime": "2018-11-07T10:03:07.325Z"
      },
      "filledAmount": 1000,
      "contraAmount": 7.78,
      "rate": 128.55,
      "settlementDate": "2018-11-07"
    },
    ...
  ]
}

GET Order

GET /v1/fxtrade/orders/{orderId}

Returns the FX spot or outright order details for the specified order ID.

Request Attributes
Name Type In Required Description
Authorization string header true Access token to be passed as a Bearer token
API-Key string header true Consumer key obtained after app registration on developer portal
orderId string path true The unique reference for this order
Sample Request
curl -X GET \
     "{app_url}/v1/fxtrade/orders/eec6b4c7-6b2f-477b-85fa-2d8dd1a07c4f" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer {your_access_token}" \
     -H "API-Key: {your_api_key}"
Response Attributes
Name Type In Required Description
Trace-Id string header true Unique ID generated for every request
FxOrder FxOrder body true The FX spot or outright order
Sample Response
{
  "orderId": "eec6b4c7-6b2f-477b-85fa-2d8dd1a07c4f",
  "submittedDateTime": "2018-11-07T10:03:09.925Z",
  "orderStatus": "FILLED",
  "consumerQuoteReference": "SP-20181107-136",
  "buyCurrency": "JPY",
  "sellCurrency": "EUR",
  "buyAmount": 1000,
  "settlement": "TODAY",
  "settlementAccountGroup": "House Account",
  "quoteId": "2a3e4567-a79b-40a3-a456-036142440410",
  "currencyPair": "EURJPY",
  "spotRate": {
    "bidRate": 128.53,
    "askRate": 128.57,
    "midRate": 128.55,
    "effectiveDateTime": "2018-11-07T10:03:07.324Z"
  },
  "swapPoints": {
    "bidPoints": 0.02,
    "askPoints": 0.02
  },
  "allInRate": {
    "bidRate": 128.55,
    "askRate": 128.59,
    "midRate": 128.57,
    "effectiveDateTime": "2018-11-07T10:03:07.325Z"
  },
  "filledAmount": 1000,
  "contraAmount": 7.78,
  "rate": 128.55,
  "settlementDate": "2018-11-07"
}

Error Response & Codes

This section describes the error response & the codes being sent by the FX Rates & Currency Conversion API.

Error Response Attributes
Name Type In Required Description
Trace-Id string header true Unique ID generated for every request
Error Error body true An array of error records. Only for the HTTP status code 400 it is possible that more than one record will be returned
Error Attributes
Name Type Required Description
code string true Unique Error code
message string true Error message
status integer true HTTP status code
reference string false Link to an information resource for this error
tradeId string true Unique ID generated for every request. It will be used to trace errors. Its value is same as Trace-Id in response header
Sample Error Response
{
  "errors": [
    {
      "code": "PROPERTY_INVALID",
      "message": "'buyCurrency' with value 'XXX' does not represent a monetary currency",
      "status": 400,
      "traceId": "0b9ad304-0467-4ec2-a1f9-8f2f685dec8e"
    },
    {
      "code": "PROPERTY_INVALID",
      "message": "'sellAmount' with value '0' is not a valid positive amount",
      "status": 400,
      "traceId": "0b9ad304-0467-4ec2-a1f9-8f2f685dec8e"
    }
  ]
}
Error Codes

This section lists the errors that are specific for this API. If the error is not listed here, or you want to know which general errors can occur, please check the general error section.

Code Status Description
REQUEST_BODY_INVALID 400 in case the request body can not be parsed. Only applicable to the POST operations
PATH_PARAMETER_INVALID 400 provided path parameter is invalid, the message will provide details about the path parameter being invalid
QUERY_PARAMETER_MISSING 400 mandatory query parameter is missing, the message will provide details about the missing parameter
QUERY_PARAMETER_INVALID 400 provided query parameter is invalid, the message will provide details about the parameter being invalid
PROPERTY_MISSING 400 mandatory request body property is missing, the message will provide details about the missing property. Only applicable to the POST operations
PROPERTY_INVALID 400 provided request body property is invalid, the message will provide details about the property being invalid. Only applicable to the POST operations
RESOURCE_NOT_FOUND 404 the requested resource does not exist
ACCEPT_HEADER_INVALID 406 the target resource does not have a current representation as requested by the 'Accept' header
CONTENT_TYPE_INVALID 415 the 'Content-Type' of the supplied request body is not supported
INTERNAL_SERVER_ERROR 500 an unexpected internal failure failure occurred. The issue has been reported to the DevOps Team and is being investigated
SERVICE_UNAVAILABLE 503 this service is currently unavailable, check the 'Retry-After' header to check when the service will be available again