FX Market Order API Documentation

Overview

FX Market Order API is designed for simple currency conversion executed at the current market price. For example, you have some US Dollars and you would like to convert these to your home currency e.g. DKK. The API allows you to execute this conversion at a value date of your choice, or even as an FX SWAP. The available FX products are SPOT, Forward, SWAP and Money Market Deposit.

Onboarding to API

In the developer portal, no additional onboarding is needed and you can start testing your workflow right away. When you are ready to migrate your solution to production, a Nordea FX Sales onboarding process is required to map the correct company IDs and other data before live trading can begin. Additionally, it is possible to be onboarded on a pre-production system based on live market data from our UAT environment, however this requires a whitelisting of your IP ranges. In both cases, please contact e-TradingSystems@nordea.com for more information.

FX Market Order API Endpoints

The API has the following endpoints. The developer portal version is based on mocked data only and does not reflect live FX rates on the market.

The first endpoint can be used to either buy or sell currency at a specific value date. SPOT typically refers to value date T+2 (two business days from now, although in some currencies SPOT is T+1). A forward trade refers to all conversions where the value date is either before the SPOT date (also known as a short-dated forward), or after the SPOT date. The value date refers to when the settlement takes place, so the actual calendar date when the money is moved between the accounts.

An example of a short-dated forward could therefore be a BUY 1000 EUR with value date TODAY by selling X USD. In this scenario, the customer would be credited the 1000 EUR during today for their account, and debited X USD based on the exchange rate used (visible in the trade confirmation). Alternatively, you could specify today’s date in YYYYMMDD format. Similarly, an example of a regular forward could be a BUY 1000 EUR with value date 3M, which equals to buying 1000 EUR in three months time from now. Alternatively you could specify a future value date in YYYYMMDD format.

The second endpoint is used for creating an FX SWAP of type BUY/SELL or SELL/BUY. For example, a EUR/USD BUY/SELL SWAP with value dates TODAY/TOM would result in EUR credit on the account, USD debit from the account today, and the opposite tomorrow.

In an FX SWAP, the two settlements are referred to as near leg and far leg.

Table of Operations

Each operation is always a BUY or a SELL operation on the base currency. For example, in EUR/USD, EUR is considered the base currency. In USD/DKK, USD is the base currency. In SEK/HUF, SEK is the base currency. This leads to the following table of operations:

The X amount will be determined by the prevailing FX rate.

Supported FX Tenors

A tenor refers to a fixed value date in the future that takes into account all banking holidays in the two currencies involved. For example during easter, a EUR/DKK TOM trade executed on Wednesday will have settlement on the following Tuesday due to the bank holidays of Thursday, Friday and Monday in Denmark.

All tenors except for TODAY will automatically roll your transaction to the next available value date (such as in the above example, TOM does not settle on Thursday rather than on the following Tuesday). TODAY is the exception to the rule, and behaves like specific YYYYMMDD value dates. Specifying a YYYYMMDD or TODAY value date that is not a valid banking day in either involved currency will result in a rejection of the market order.

Allowed tenors:

You can always opt to specify a YYYYMMDD value date instead of a tenor.

Opening Hours / Daily Cut-Off Hours

It is possible to execute FX trades during market opening hours, which are from Monday 5am Sydney time until Friday 5pm New York Time. The exception is the daily service window which takes place between 5-5:30pm New York Time nightly, and weekends when the global FX market is closed.

Additionally there are cut-off times for some currencies on specific tenors like TODAY, TOM. For example, it is not possible to trade CNH with value date today if the CNH settlement account is not a Nordea account. This is because additional time is needed to perform the settlement and physically move the money to the external account.

The specific trading hours for currencies and tenors are available here: e-Markets opening hours

Specifying Settlement Accounts

It is possible to override the settlement bank account in one or both of the currencies involved in a trade by specifying a valid IBAN (International Bank Account Number). During onboarding to the API together with FX sales, Nordea will setup default bank accounts for settlement that will be used if no settlement accounts are specified in the market order. If you would like to override the default settlement accounts, FX sales will have to onboard each additional account before you can choose to override the accounts as a part of your market order.

Note: the settlement account does not have to be a Nordea account and can easily be an external IBAN at another bank, however, it will still need to be onboarded into Nordea’s systems.

API Timeout Values

You must specify a REST timeout of minimum 95 seconds before abandoning each call. While nearly all transactions will complete immediately with few milliseconds of latency, very large transactions will sometimes require manual pricing by a physical trader as they cannot be automatically priced. Before 95 seconds have passed you are guaranteed either a confirmation of trade or a rejection of a trade.
This can also be the case during extraordinary circumstances and technical difficulties.

Client Order ID requirements

The client order ID is your unique reference to a given trade. You can use this to track market orders on your side. When specifying a client order ID, you should specify an ID that is maximum 24 characters long.

The ID must be unique for each account during a 24 hour period. In the cloud sandbox, the default client order ID specified in the API console, as well as the value clientOrderId1 can be used to execute on the same client order ID multiple times without this restriction.

Company ID

The company ID field can be set to any value in the sandbox environment. In production, this value must be set to the company ID provided to you by FX Sales as a part of the onboarding process.

Client Reference

The client_reference in a Market Order corresponds to the Note field that is viewable on the e-Markets platform. This is a freeform textfield which allows you to include a custom reference to each trade.

TLS Cipher Suites

Nordea uses secure HTTPS TLS1.2 cipher suites for all endpoints. In practice, any modern platform should support the below HTTPS ciphers out-of-box, but applications running on older operating systems (for example: older than Windows 8.1) may have to use additional software to wrap your connection with.

The minimum cipher suites levels are:

• TLS1.2-ECDHE-RSA-AES256-GCM-SHA384 (TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384)
• TLS1.2-ECDHE-RSA-AES128-GCM-SHA256 (LS_ECDH_RSA_WITH_AES_128_GCM_SHA256)

Migrate to Production

Once you have completed your integration to our FX Trading API, you are ready to migrate to production. This requires an onboarding process together with Nordea FX Sales.

In order to migrate to Production, please contact e-TradingSystems@nordea.com for additional information.

Pre-Production availability

If you would like to test your integration against live market data in UAT instead of our mocked sandbox environment, this is possible in our pre-production environment. However, onboarding to pre-production requires white-listing of your IP range.

Please contact e-TradingSystems@nordea.com and request onboarding to pre-production for a specific IP range.

API Examples

Here you can find examples on how to use the FX Market Order API endpoints. All examples can also be tried in the API Console.

Note that in all of the example cURL commands you must change the x-ibm-client-id, and x-ibm-client-secret header values to the correct ones for your application.

You can find the client id, and client secret from your app console. As a part of the production onboarding you must specify the client id value to your FX sales manager who will map it to Nordea’s FX systems accordingly. Failing to do so will result in a rejection of the trade.

If you need to replace your client id in production, you must contact your FX sales representative or contact e-TradingSystems@nordea.com

cURL Examples

SPOT Example: BUY 1000 EUR (sell X USD)

POST fx-market-order-api/v1/spot-fwd HTTP/1.1

The following cURL can be used to send a market order. Note: The settl_date field accepts both Tenor and yyyyMMdd date. However, in the response, this is always a yyyyMMdd date except in the mock environment.

$ curl 'https://api.nordeaopenbanking.com/fx-market-order-api/v1/spot-fwd' -i \
    -H 'accept: application/json' \
	-H 'Content-Type: application/json' \
    -H 'x-ibm-client-id: CLIENT_ID' \
    -H 'x-ibm-client-secret: CLIENT_SECRET' \
	-d '{"company_id": "COMPANY_A",
  "amount_currency": "EUR",
  "client_order_id": "201902040001",
  "currency_pair": "EUR/USD",
  "order_amount": 1000,
  "settl_date": "SPOT",
  "side": "CLIENT_BUY",
  "client_reference": "Custom note about the trade"}' 

Example response for a confirmed BUY 1000 EUR (sell X USD) trade:

{
    "client_order_id": "201902040001",
    "nordea_transaction_reference": "201904010837112762416",
    "nordea_order_id": "140N0",
    "order_status": "CONFIRMED",
    "company_id": "COMPANY_A",
    "currency_pair": "EUR/USD",
	"transaction_time": "2020-02-06T11:19:44.316Z",
    "spot_rate": 1.1205,
    "legs": [
        {
            "value_date": "SPOT",
            "side": "CLIENT_BUY",
            "leg_amount": 1000,
            "settle_currency": "USD",
            "contra_amount": 1120.50,
            "forward_points": 0,
            "all_in_rate": 1.1205
        }
    ]
}

In the confirmation: contra_amount indicates the converted amount e.g. the amount of USD used to buy 1000 EUR.

SPOT Example: SELL X EUR (buy 1000 USD)

In this example we are selling X amount of base currency by buying 1000 USD.

POST fx-market-order-api/v1/spot-fwd HTTP/1.1

$ curl 'https://api.nordeaopenbanking.com/fx-market-order-api/v1/spot-fwd' -i \
    -H 'accept: application/json' \
	-H 'Content-Type: application/json' \
    -H 'x-ibm-client-id: CLIENT_ID' \
    -H 'x-ibm-client-secret: CLIENT_SECRET' \
	-d '{"company_id": "COMPANY_A",
  "amount_currency": "USD",
  "client_order_id": "201902040001",
  "currency_pair": "EUR/USD",
  "order_amount": 1000,
  "settl_date": "SPOT",
  "side": "CLIENT_SELL"}' 

Example response for a confirmed SELL X EUR (BUY 1000 USD) trade:

{
    "client_order_id": "201902040001",
    "nordea_transaction_reference": "201904010837112762417",
    "nordea_order_id": "141N0",
    "order_status": "CONFIRMED",
    "company_id": "COMPANY_A",
    "currency_pair": "EUR/USD",
    "spot_rate": 1.1203,
	"transaction_time": "2020-02-06T11:19:44.316Z",
    "legs": [
        {
            "value_date": "SPOT",
            "side": "CLIENT_SELL",
            "leg_amount": 1000,
            "settle_currency": "USD",
            "contra_amount": 892.62,
            "forward_points": 0,
            "all_in_rate": 1.1203
        }
    ]
}

In the confirmation: contra_amount indicates the converted amount e.g. the amount of EUR sold to buy 1000 USD.

Forward Example: BUY 1000 EUR (sell X USD) on value date 20 December 2019

POST fx-market-order-api/v1/spot-fwd HTTP/1.1

$ curl 'https://api.nordeaopenbanking.com/fx-market-order-api/v1/spot-fwd' -i \
    -H 'accept: application/json' \
	-H 'Content-Type: application/json' \
    -H 'x-ibm-client-id: CLIENT_ID' \
    -H 'x-ibm-client-secret: CLIENT_SECRET' \
	-d '{"company_id": "COMPANY_A",
  "amount_currency": "EUR",
  "client_order_id": "201902040003",
  "currency_pair": "EUR/USD",
  "order_amount": 1000,
  "settl_date": "20191220",
  "side": "CLIENT_BUY"}' 

Example response for a confirmed BUY 1000 EUR (sell X USD) trade:

{
    "client_order_id": "201902040003",
    "nordea_transaction_reference": "201904010837112762418",
    "nordea_order_id": "142N0",
    "order_status": "CONFIRMED",
    "company_id": "COMPANY_A",
    "currency_pair": "EUR/USD",
    "spot_rate": 1.1205,
	"transaction_time": "2020-02-06T11:19:44.316Z",
    "legs": [
        {
            "value_date": "20191220",
            "side": "CLIENT_BUY",
            "leg_amount": 1000,
            "settle_currency": "EUR",
            "contra_amount": 1120.60,
            "forward_points": 0.0001,
            "all_in_rate": 1.1206
        }
    ]
}

Notice here that the value date is set to 20 December 2019, and that there are forward points included in the trade.

SWAP Example: BUY 1000 EUR (sell X USD) on SPOT, SELL 1000 EUR (buy X USD) 1 Month later.

POST fx-market-order-api/v1/swap HTTP/1.1

$ curl 'https://api.nordeaopenbanking.com/fx-market-order-api/v1/swap' -i \
    -H 'accept: application/json' \
	-H 'Content-Type: application/json' \
    -H 'x-ibm-client-id: CLIENT_ID' \
    -H 'x-ibm-client-secret: CLIENT_SECRET' \
	-d '{"account": "COMPANY_A",
  "amount_currency": "EUR",
  "client_order_id": "201902040004",
  "currency_pair": "EUR/USD",
  "order_amount": 1000,
  "settl_date": "SPOT",
  "side": "CLIENT_BUY"
  "settl_date_far_leg": "1M",
  "order_amount_far_leg": 1000}' 

Note that the side refers to the near leg side. The far leg side will always be the opposite of the near leg side.

Example response for a confirmed BUY/SELL 1000 EUR (sell/buy X USD) SWAP:

{
    "client_order_id": "201902040004",
    "nordea_transaction_reference": "2019040210105552629899",
    "nordea_order_id": "241N0",
    "order_status": "CONFIRMED",
    "company_id": "COMPANY_A",
    "currency_pair": "EUR/USD",
    "spot_rate": 1.1205,
	"transaction_time": "2020-02-06T11:19:44.316Z",
    "legs": [
        {
            "value_date": "SPOT",
            "side": "CLIENT_BUY",
            "leg_amount": 1000,
            "settle_currency": "USD",
            "contra_amount": 1120.50,
            "forward_points": 0,
            "all_in_rate": 1.1205
        },
        {
            "value_date": "1M",
            "side": "CLIENT_SELL",
            "leg_amount": 1000,
            "settle_currency": "EUR",
            "contra_amount": 1120.50,
            "forward_points": 0,
            "all_in_rate": 1.1205
        }
    ]
}

In the confirmation you can now see two legs: the near leg of SPOT, and the far leg of 1M.

SPOT Example: BUY 1000 EUR (sell X USD) and override settlement accounts

POST fx-market-order-api/v1/spot-fwd HTTP/1.1

Notice the additional json field settlement accounts that can feature either one or two settlement accounts should you wish to override the default settlement account.

$ curl 'https://api.nordeaopenbanking.com/fx-market-order-api/v1/spot-fwd' -i \
    -H 'accept: application/json' \
	-H 'Content-Type: application/json' \
    -H 'x-ibm-client-id: CLIENT_ID' \
    -H 'x-ibm-client-secret: CLIENT_SECRET' \
	-d '{"company_id": "COMPANY_A",
  "amount_currency": "EUR",
  "client_order_id": "201902040001",
  "currency_pair": "EUR/USD",
  "order_amount": 1000,
  "settl_date": "SPOT",
  "side": "CLIENT_BUY",
  "settlement_accounts": [
	{
		"currency" : "EUR",
		"iban_account_number" : "DK9520000123456789"
	},
	{
		"currency" : "USD",
		"iban_account_number" : "DK9520000155562135"
	}
  ]
  
  }' 

The confirmation will not feature the settlement accounts, and so is otherwise identical to a standard SPOT trade.

{
    "client_order_id": "201902040001",
    "nordea_transaction_reference": "201904010837112762416",
    "nordea_order_id": "140N0",
    "order_status": "CONFIRMED",
    "company_id": "COMPANY_A",
    "currency_pair": "EUR/USD",
    "spot_rate": 1.1205,
	"transaction_time": "2020-02-06T11:19:44.316Z",
    "legs": [
        {
            "value_date": "SPOT",
            "side": "CLIENT_BUY",
            "leg_amount": 1000,
            "settle_currency": "USD",
            "contra_amount": 1120.50,
            "forward_points": 0,
            "all_in_rate": 1.1205
        }
    ]
}

Deposit Example: Deposit 1000 EUR

POST fx-market-order-api/v1/deposit HTTP/1.1

$ curl 'https://api.nordeaopenbanking.com/fx-market-order-api/v1/deposit' -i \
    -H 'accept: application/json' \
	-H 'Content-Type: application/json' \
    -H 'x-ibm-client-id: CLIENT_ID' \
    -H 'x-ibm-client-secret: CLIENT_SECRET' \
	-d '{
  "company_id": "COMPANY_A",
  "amount_currency": "EUR",
  "client_order_id": "201902040001",
  "order_amount": 1000,
  "start_date": "20240606",
  "settl_date": "20250606",
  }' 

Example response for a confirmed Deposit:

{
    "client_order_id": "201902040001",
    "nordea_transaction_reference": "201904010837112762416",
    "nordea_order_id": "140N0",
    "order_status": "CONFIRMED",
    "company_id": "COMPANY_A",
	"transaction_time": "2020-02-06T11:19:44.316Z",
    "details": 
        {
            "start_date": "20240606",
            "value_date": "20250606",
            "currency": "EUR",
            "product_type": "MM_DEPOSIT",
            "symbol": "Depo EUR",
            "principal_amount": "1000",
            "maturity_amount": "1004.5",
            "interest_rate": "0.045",
            "interest_days": 365,
            "day_count_convention": "Act/360"
        }
}

Change Settlement Example: Spot 100 EUR

POST fx-market-order-api/v1/change-settlement HTTP/1.1

$ curl 'https://api.nordeaopenbanking.com/fx-market-order-api/v1/change-settlement' -i \
    -H 'accept: application/json' \
	-H 'Content-Type: application/json' \
    -H 'x-ibm-client-id: CLIENT_ID' \
    -H 'x-ibm-client-secret: CLIENT_SECRET' \
	-d '{
    "amount_currency": "EUR",
    "client_order_id": "201902040001",
    "company_id": "COMPANY_A",
    "currency_pair": "EUR/USD",
    "order_amount": "50",
    "settl_date": "20230927",
    "side": "CLIENT_BUY",
    "new_settl_date": "20230925",
    "rate_type": "HISTORICAL_RATE",
    "referenced_trade": "0230918001392"
}' 

Example response for a change settlement:

{
    "client_order_id": "201902040002",
    "nordea_transaction_reference": "201904010837112762416",
    "nordea_order_id": "140N0",
    "order_status": "CONFIRMED",
    "company_id": "COMPANY_A",
    "currency_pair": "EUR/USD",
    "spot_rate": "1.0789166",
    "transaction_time": "2023-09-18T11:40:46.309Z",
    "legs": [
        {
            "value_date": "20230925",
            "side": "CLIENT_BUY",
            "leg_amount": "50",
            "settle_currency": "USD",
            "contra_amount": "53.94",
            "forward_points": "-0.000084",
            "all_in_rate": "1.0788326"
        },
        {
            "value_date": "20230927",
            "side": "CLIENT_SELL",
            "leg_amount": "50",
            "settle_currency": "USD",
            "contra_amount": "53.95",
            "forward_points": "0",
            "all_in_rate": "1.0789166"
        }
    ]
}