FX Trade Retriever API Documentation
Overview
FX Trade Retriever API enables you to retrieve your FX trades and Money market deposits executed with Nordea. This includes trades completed in all venues, including both Nordea’s own channels and the third-party platforms where you can trade with Nordea.
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 you will be able to retrieve your trades. Please contact e-TradingSystems@nordea.com for more information about production onboarding.
FX Trade Retriever API Endpoints
The API has these endpoints:
| Endpoint | Supported HTTP Methods | Description |
|---|---|---|
| /fx/trades/{company-id}/{trade-id} | GET | Retrieve details of a specific FX trade or deposit based on a completed or rejected trade ID. This will include information about the FX rate used and other relevant information of each trade. |
| /fx/trades/{company-id} | GET | For a given company ID, retrieve a list of all trades and their details based on a date range. The response will contain all possible trades that match the company id where trade date is within the two provided dates. Additionally, you can provide a parameter specifying whether you would also like to include trades maturing during this period into the response. Further, it is possible to provide a comma-separated list of trade statuses, e.g. OPEN,SETTLED,CANCELLED. |
| /fx/trades | GET | For all company IDs associated with your client-id, retrieve a list of all trades and their details based on a date range. The response will contain all possible trades where trade date is within the two provided dates. Additionally, you can provide a parameter specifying whether you would also like to include trades maturing during this period into the response. Further, it is possible to provide a comma-separated list of trade statuses, e.g. OPEN,SETTLED,CANCELLED. This endpoint is intended for customers with a large number of subsidiaries. |
| /fx/trades/block/{parent-trade-id} | GET | Retrieve details of a specific FX block trade by its parent trade ID. |
The developer portal version (or sandbox or “Try in API console”) is based on mocked data only so it is not possible to retrieve your real FX trades and Money market deposits. It is intended to give you a realistic picture of possible output from the production API.
Availability of trades
Due to processing time required to correctly settle trades by our backend systems, an executed trade will not be immediately available via the API.
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. This company ID should match with the shortname you are using for trading against Nordea Markets.
Auxiliary Trades
Auxiliary trades are special type of derivative that allows you to either extend the value date of an existing trade, or alternatively to bring the value date forward to an earlier date. This can also be a partial amount from the original trade. This trade type is only available on our single dealer portals. In practice, this trade type translates to an FX Swap constituting of the position on the original value date and the new position on the new value date. As a result, this trade is represented in FX Trade Retriever API under special product type codes:
- FX_HRET: Historical Rate early-take up
- FX_MRET: Market Rate early-take up
- FX_HREXT: Historical Rate Extension
- FX_MREXT: Market Rate Extension
On the main trade level of all auxiliary trades, the field prev_settlement_no links to the settlement_no of a leg in a previous trade (of any type) that has been changed using an auxiliary. And since it is possible to execute multiple partial auxiliaries on the same original trade, it is possible that many auxiliary trades as a result refer to the same settlement number.
For example, an extension to SPOT trade A will have its prev_settlement_no refer to the settlement number in A’s single leg. However, an extension to FX Swap trade B can in principle have its prev_settlement_no refer to either the near leg or the far leg of B.
Additionally, it is important to note that although both are represented as two-leg FX Swaps in the Trade Retriever API, early take-ups and extensions are effectively different legs. In early take-ups, since you are effectively bringing your position to an earlier date, the all-in rates relevant to you are in the near leg of the auxiliary. To the contrary in an extension, you are moving your position to a later date, so the all-in rates relevant to you will be found in the far leg of the auxiliary trade. The other leg in each is known as the offset trade that offsets your original position.
In auxiliaries, near leg is your new position in early take-ups, and far-leg is your new position in extensions.
API Timeout Values
You must specify a REST timeout of minimum 95 seconds before abandoning each call. While nearly all queries will complete within seconds of the query, very large trade sets may take some time to retrieve. This is the case if you are querying for a wide date range and you have executed trades at a high volume during this period.
Before 95 seconds have passed you are guaranteed either a response or an error message.
This can also be the case during extraordinary circumstances and technical difficulties.
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 Trade Retriever 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 or your Nordea representative for additional information.
API Examples
Here you can find examples on how to use the FX Trade Retriever API endpoints. All examples can also be tried in the API Console.
Note that in all example cURL commands below, 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 API call.
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
Retrieve a specific trade (/fx/trades/{company-id}/{trade-id})
GET trade-retriever-api/v1/fx/trades/:company-id/:trade-id HTTP/1.1The following cURL can be used to query for a specific trade created by company id COMPANY_A
$ curl --request GET 'https://api.nordeaopenbanking.com/trade-retriever-api/v1/fx/trades/COMPANY_A/051BCGGKJBM8DK6A87YB' -i \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'x-ibm-client-id: CLIENT_ID' \
-H 'x-ibm-client-secret: CLIENT_SECRET'Example response with single trade details. NOTE: If you have executed an auxiliary trade that affects this trade, the list of trades will also include all of these trades.
{
"fx_trades": [
{
"product_type": "FX_SPOT",
"counterparty": "Nordea Bank Abp",
"nordea_trade_id": "051BCGGKJBM8DK6A87YB",
"trade_date": "20200206",
"transaction_time": "2020-02-06T09:55:55Z",
"trade_status": "OPEN",
"currency_pair": "EUR/USD",
"client_reference": "clientref123",
"legs": [
{
"leg_type": "STANDARD",
"company_id": "COMPANY_A",
"settl_date": "20200210",
"buy_amount": "10000",
"buy_currency": "EUR",
"buy_account": "DK0020005036024153",
"sell_amount": "11132",
"sell_currency": "USD",
"sell_account": "DK0020005005888701",
"spot_rate": "1.1132",
"all_in_rate": "1.1132",
"settlement_no": "012312355123",
"outstanding_buy_amount": "10000",
"outstanding_sell_amount": "11132",
"fixed_amount_currency": "EUR"
}
]
"venue": "OPEN_BANKING"
}
]
}Retrieve a list of trades for a specific date range (either /fx/trades/{company-id} or /fx/trades/)
In this example we are requesting a list of all trades between 24 October 2019 - 28 November 2019 for COMPANY_A. Additionally we are including two OPTIONAL flags, i.e. you can omit these:
- Include trades maturing during the same period (i.e. settlement dates). The default value is false.
- Filter trades with trade statuses OPEN and SETTLED. The default value is OPEN,SETTLED,CANCELLED (i.e. all possible statuses)
During the retrieval process of trades, a trade hierarchy might occur. Let’s say a trade has an accociated auxiliary trade, in total 2. If a trade status filter is applied (for example OPEN), and one trade is in state SETTLED and the other one in OPEN, the SETTLED trade will be excluded. That is, the filter is applied at last during the retrieval process and the trade hierarchy is not considered in the filter.
GET trade-retriever-api/v1/fx/trades/:company-id?fromDate=:fromDate&toDate=:toDate HTTP/1.1$ curl --request GET 'https://api.nordeaopenbanking.com/trade-retriever-api/v1/fx/trades/COMPANY_A?fromDate=20191024&toDate=20191128&includeMaturing=true&tradeStatuses=OPEN,SETTLED' -i \
-H 'accept: application/json' \
-H 'x-ibm-client-id: CLIENT_ID' \
-H 'x-ibm-client-secret: CLIENT_SECRET' Example response contains a FX SPOT trade, a FX Forward trade, a FX Swap trade, a FX NDF trade, an auxiliary trade of type market rate extension on the original SPOT trade and a Deposit:
{
"fx_trades": [
{
"product_type": "FX_SPOT",
"counterparty": "Nordea Bank Abp",
"nordea_trade_id": "051BCGGKJBM8DK6A87YB",
"trade_date": "20200206",
"transaction_time": "2020-02-06T09:57:31.566Z",
"trade_status": "OPEN",
"currency_pair": "EUR/USD",
"client_reference": "clientref123",
"legs": [
{
"leg_type": "STANDARD",
"company_id": "COMPANY_A",
"settl_date": "20200210",
"buy_amount": "10000",
"buy_currency": "EUR",
"sell_amount": "11132",
"sell_currency": "USD",
"spot_rate": "1.1132",
"all_in_rate": "1.1132",
"settlement_no": "012312355123",
"fixed_amount_currency": "EUR"
}
]
},
{
"product_type": "FX_FORWARD",
"counterparty": "Nordea Bank Abp",
"nordea_trade_id": "051BCGGKJBM8DK6A87YC",
"trade_date": "20200206",
"transaction_time": "2020-02-06T09:57:31.566Z",
"trade_status": "OPEN",
"currency_pair": "EUR/USD",
"client_reference": "clientref345",
"legs": [
{
"leg_type": "STANDARD",
"company_id": "COMPANY_A",
"settl_date": "20200217",
"buy_amount": "10000",
"buy_currency": "EUR",
"sell_amount": "11135",
"sell_currency": "USD",
"spot_rate": "1.1132",
"forward_points": "0.0003",
"all_in_rate": "1.1135",
"settlement_no": "012312355124",
"fixed_amount_currency": "EUR"
}
]
},
{
"product_type": "FX_SWAP",
"counterparty": "Nordea Bank Abp",
"nordea_trade_id": "051BCGGKJBM8DK6A87YD",
"trade_date": "20200206",
"transaction_time": "2020-02-06T09:57:31.566Z",
"trade_status": "OPEN",
"currency_pair": "EUR/USD",
"client_reference": "clientref678",
"legs": [
{
"leg_type": "SWAP_NEAR_LEG",
"company_id": "COMPANY_A",
"settl_date": "20200206",
"buy_amount": "10000",
"buy_currency": "EUR",
"sell_amount": "11131.8",
"sell_currency": "USD",
"spot_rate": "1.1132",
"forward_points": "-0.00002",
"all_in_rate": "1.11318",
"settlement_no": "012312355125",
"fixed_amount_currency": "EUR"
},
{
"leg_type": "SWAP_FAR_LEG",
"company_id": "COMPANY_A",
"settl_date": "20200217",
"buy_amount": "11135",
"buy_currency": "USD",
"sell_amount": "10000",
"sell_currency": "EUR",
"spot_rate": "1.1132",
"forward_points": "0.0003",
"all_in_rate": "1.1135",
"settlement_no": "012312355126",
"fixed_amount_currency": "EUR"
}
]
"transaction_cost_currency": "USD",
"transaction_cost_base": "0.00041",
"transaction_cost_points": "0.000658",
"transaction_cost_amount": "2149.6",
"transaction_cost_percentage": "32.3318",
"venue": "OPEN_BANKING"
},
{
"product_type": "FX_NDF",
"counterparty": "Nordea Bank Abp",
"nordea_trade_id": "051BCGGKJBM8DK6A87YE",
"trade_date": "20200206",
"transaction_time": "2020-02-06T09:57:31.567Z",
"trade_status": "OPEN",
"currency_pair": "EUR/BRL",
"client_reference": "clientref999",
"legs": [
{
"leg_type": "NDF",
"company_id": "COMPANY_A",
"settl_date": "20200217",
"buy_amount": "4650",
"buy_currency": "BRL",
"sell_amount": "1000",
"sell_currency": "EUR",
"spot_rate": "4.64",
"forward_points": "0.01",
"all_in_rate": "4.65",
"settlement_no": "012312355127",
"ndf_details": {
"ndf_settle_currency": "EUR",
"ndf_settle_amount": "-8.53",
"ndf_fixing_date": "20200206",
"ndf_fixing_rate": "4.69"
},
"fixed_amount_currency": "EUR"
}
]
"transaction_cost_currency": "BRL",
"transaction_cost_base": "0.00041",
"transaction_cost_points": "0.000658",
"transaction_cost_amount": "2149.6",
"transaction_cost_percentage": "32.3318",
"venue": "OPEN_BANKING"
},
{
"product_type": "FX_MREXT",
"counterparty": "Nordea Bank Abp",
"nordea_trade_id": "051BCGGKJBM8DK6A87YF",
"prev_settlement_no": "012312355123",
"trade_date": "20200206",
"transaction_time": "2020-02-06T09:57:31.567Z",
"trade_status": "OPEN",
"currency_pair": "EUR/USD",
"client_reference": "clientref002",
"legs": [
{
"leg_type": "SWAP_NEAR_LEG",
"company_id": "COMPANY_A",
"settl_date": "20200210",
"buy_amount": "11132",
"buy_currency": "USD",
"sell_amount": "10000",
"sell_currency": "EUR",
"spot_rate": "1.1132",
"forward_points": "0",
"all_in_rate": "1.1132",
"settlement_no": "012312355128",
"fixed_amount_currency": "EUR"
},
{
"leg_type": "SWAP_FAR_LEG",
"company_id": "COMPANY_A",
"settl_date": "20200217",
"buy_amount": "10000",
"buy_currency": "EUR",
"sell_amount": "11132",
"sell_currency": "USD",
"spot_rate": "1.1132",
"forward_points": "0.003",
"all_in_rate": "1.1162",
"settlement_no": "012312355129",
"fixed_amount_currency": "EUR"
}
]
"venue": "OPEN_BANKING"
}
],
"mm_trades": [
{
"product_type": "MM_DEPOSIT",
"client_reference": "clientrefDEP",
"counterparty": "Nordea Danmark, Filial af Nordea Bank Abp, Finland",
"nordea_trade_id": "051BCGGKJBM8DK6A87YE",
"trade_date": "20200206",
"transaction_time": "2020-02-06T09:57:31Z",
"trade_status": "SETTLED",
"company_id": "COMPANY_A",
"currency": "EUR",
"value_date": "20211215",
"maturity_date": "20211216",
"principal_amount": "5000",
"maturity_amount": "5000.26",
"interest_rate": "1.84",
"interest_amount": "0.26",
"day_count_convention": "Act/360",
"settlement_no": "012312355130"
}
}Retrieve a list of trades for a specific date range for all your subsidiaries
In this example we are requesting a list of all trades between 24 October 2019 - 28 November 2019 for all configured subsidiaries. Additionally we are including two OPTIONAL flags, i.e. you can omit these:
- Include trades maturing during the same period (i.e. settlement dates). The default value is false.
- Filter trades with trade statuses OPEN and SETTLED. The default value is OPEN,SETTLED,CANCELLED (i.e. all possible statuses)
GET trade-retriever-api/v1/fx/trades?fromDate=:fromDate&toDate=:toDate HTTP/1.1$ curl --request GET 'https://api.nordeaopenbanking.com/trade-retriever-api/v1/fx/trades?fromDate=20191024&toDate=20191128&includeMaturing=true&tradeStatuses=OPEN,SETTLED' -i \
-H 'accept: application/json' \
-H 'x-ibm-client-id: CLIENT_ID' \
-H 'x-ibm-client-secret: CLIENT_SECRET' Example response contains a FX SPOT trade, a FX Forward trade, a FX Swap trade, a FX NDF trade, an auxiliary trade of type market rate extension on the original SPOT trade and a Deposit:
{
"fx_trades": [
{
"product_type": "FX_SPOT",
"counterparty": "Nordea Bank Abp",
"nordea_trade_id": "051BCGGKJBM8DK6A87YB",
"trade_date": "20200206",
"transaction_time": "2020-02-06T09:57:31.566Z",
"trade_status": "OPEN",
"currency_pair": "EUR/USD",
"client_reference": "clientref123",
"legs": [
{
"leg_type": "STANDARD",
"company_id": "COMPANY_A",
"settl_date": "20200210",
"buy_amount": "10000",
"buy_currency": "EUR",
"sell_amount": "11132",
"sell_currency": "USD",
"spot_rate": "1.1132",
"all_in_rate": "1.1132",
"settlement_no": "012312355123",
"fixed_amount_currency": "EUR"
}
]
"venue": "OPEN_BANKING"
},
{
"product_type": "FX_FORWARD",
"counterparty": "Nordea Bank Abp",
"nordea_trade_id": "051BCGGKJBM8DK6A87YC",
"trade_date": "20200206",
"transaction_time": "2020-02-06T09:57:31.566Z",
"trade_status": "OPEN",
"currency_pair": "EUR/USD",
"client_reference": "clientref345",
"legs": [
{
"leg_type": "STANDARD",
"company_id": "COMPANY_A",
"settl_date": "20200217",
"buy_amount": "10000",
"buy_currency": "EUR",
"sell_amount": "11135",
"sell_currency": "USD",
"spot_rate": "1.1132",
"forward_points": "0.0003",
"all_in_rate": "1.1135",
"settlement_no": "012312355124",
"fixed_amount_currency": "EUR"
}
]
"venue": "OPEN_BANKING"
},
{
"product_type": "FX_SWAP",
"counterparty": "Nordea Bank Abp",
"nordea_trade_id": "051BCGGKJBM8DK6A87YD",
"trade_date": "20200206",
"transaction_time": "2020-02-06T09:57:31.566Z",
"trade_status": "OPEN",
"currency_pair": "EUR/USD",
"client_reference": "clientref678",
"legs": [
{
"leg_type": "SWAP_NEAR_LEG",
"company_id": "COMPANY_A",
"settl_date": "20200206",
"buy_amount": "10000",
"buy_currency": "EUR",
"sell_amount": "11131.8",
"sell_currency": "USD",
"spot_rate": "1.1132",
"forward_points": "-0.00002",
"all_in_rate": "1.11318",
"settlement_no": "012312355125",
"fixed_amount_currency": "EUR"
},
{
"leg_type": "SWAP_FAR_LEG",
"company_id": "COMPANY_A",
"settl_date": "20200217",
"buy_amount": "11135",
"buy_currency": "USD",
"sell_amount": "10000",
"sell_currency": "EUR",
"spot_rate": "1.1132",
"forward_points": "0.0003",
"all_in_rate": "1.1135",
"settlement_no": "012312355126",
"fixed_amount_currency": "EUR"
}
]
"transaction_cost_currency": "USD",
"transaction_cost_base": "0.00041",
"transaction_cost_points": "0.000658",
"transaction_cost_amount": "2149.6",
"transaction_cost_percentage": "32.3318",
"venue": "OPEN_BANKING"
},
{
"product_type": "FX_NDF",
"counterparty": "Nordea Bank Abp",
"nordea_trade_id": "051BCGGKJBM8DK6A87YE",
"trade_date": "20200206",
"transaction_time": "2020-02-06T09:57:31.567Z",
"trade_status": "OPEN",
"currency_pair": "EUR/BRL",
"client_reference": "clientref999",
"legs": [
{
"leg_type": "NDF",
"company_id": "COMPANY_A",
"settl_date": "20200217",
"buy_amount": "4650",
"buy_currency": "BRL",
"sell_amount": "1000",
"sell_currency": "EUR",
"spot_rate": "4.64",
"forward_points": "0.01",
"all_in_rate": "4.65",
"settlement_no": "012312355127",
"fixed_amount_currency": "EUR"
"ndf_details": {
"ndf_settle_currency": "EUR",
"ndf_settle_amount": "-8.53",
"ndf_fixing_date": "20200206",
"ndf_fixing_rate": "4.69"
}
}
]
"transaction_cost_currency": "BRL",
"transaction_cost_base": "0.00041",
"transaction_cost_points": "0.000658",
"transaction_cost_amount": "2149.6",
"transaction_cost_percentage": "32.3318",
"venue": "OPEN_BANKING"
},
{
"product_type": "FX_MREXT",
"counterparty": "Nordea Bank Abp",
"nordea_trade_id": "051BCGGKJBM8DK6A87YF",
"prev_settlement_no": "012312355123",
"trade_date": "20200206",
"transaction_time": "2020-02-06T09:57:31.567Z",
"trade_status": "OPEN",
"currency_pair": "EUR/USD",
"client_reference": "clientref002",
"legs": [
{
"leg_type": "SWAP_NEAR_LEG",
"company_id": "COMPANY_A",
"settl_date": "20200210",
"buy_amount": "11132",
"buy_currency": "USD",
"sell_amount": "10000",
"sell_currency": "EUR",
"spot_rate": "1.1132",
"forward_points": "0",
"all_in_rate": "1.1132",
"settlement_no": "012312355128",
"fixed_amount_currency": "EUR"
},
{
"leg_type": "SWAP_FAR_LEG",
"company_id": "COMPANY_A",
"settl_date": "20200217",
"buy_amount": "10000",
"buy_currency": "EUR",
"sell_amount": "11132",
"sell_currency": "USD",
"spot_rate": "1.1132",
"forward_points": "0.003",
"all_in_rate": "1.1162",
"settlement_no": "012312355129",
"fixed_amount_currency": "EUR"
}
]
"venue": "OPEN_BANKING"
}
],
"mm_trades": [
{
"product_type": "MM_DEPOSIT",
"client_reference": "clientrefDEP",
"counterparty": "Nordea Danmark, Filial af Nordea Bank Abp, Finland",
"nordea_trade_id": "051BCGGKJBM8DK6A87YE",
"trade_date": "20200206",
"transaction_time": "2020-02-06T09:57:31Z",
"trade_status": "SETTLED",
"company_id": "COMPANY_A",
"currency": "EUR",
"value_date": "20211215",
"maturity_date": "20211216",
"principal_amount": "5000",
"maturity_amount": "5000.26",
"interest_rate": "1.84",
"interest_amount": "0.26",
"day_count_convention": "Act/360",
"settlement_no": "012312355130"
}
}
```