FX Service API
Available APIs
APIs (application programming interfaces) are integration points that allow two different programs or systems to communicate with each other. In the realm of Foreign Exchange, APIs enable tasks that would traditionally necessitate phone calls or the use of separate platforms to be fully automated. To harness the potential of FX APIs, either client-facing third-party system providers or clients themselves may integrate their systems to communicate their FX business with the bank.
FX Trade RetrieverThe Trade Retriever assists clients in automating their post-trade management by enabling them to retrieve both settled and unsettled FX arrangements they hold with the bank. To use this API, users will provide a settlement span, and the API will return details about every FX arrangement the client has within the given span. Use-cases for this API includes automated bookkeeping and reconciliation.
FX Indicative RatesThe Indicative Rates API is crafted to furnish clients with pre-trade price awareness capabilities. Indicative quotes mirror the FX rates available for trading through the Market Order API. A use-case might involve obtaining an indicative market rate before initiating a trade. The available products include Spot rates, Forward all-in rates, and Swap points.
Market OrderThe Market Order API is tailored for straightforward currency conversions carried out at the prevailing market rate. Designed for simplicity, the API streamlines this process with a single request/reply. It enables clients to execute the conversion as a spot transaction or on a date of the users preference, including the option to move FX cashflows with a Swap.
API Description
Overall information
This section provides information that are common for all endpoints
Authorization
For use of API, a token must be fetched according to the instructions Here
Each request must contain these headers:
Authorization which should contain a bearer token with the BASE64-encoded JWT
X-IBM-Client-Id
this header contains the unique identifier of your application, that you get when you are onboarded to a Premium API.
FX Trade Retriever
The Trade Retriever assists clients in automating their post-trade management by enabling them to retrieve both settled and unsettled FX arrangements they hold with the bank
GET /premium/v1/premium-fx-trade-retriever/{orgNr}/fx-trades
Path ParametersorgNr The organization number of the company.MANDATORY
Query Parameters
from-date Start date of the transactions in ISO 8601 format. Mandatory.
to-date End date of the transactions in ISO 8601 format.
Mandatory.
When successful, the payload consists of an array with an object with the following fields:
| Name | Description |
|---|---|
| orderId | OrderId assigned by Bank as string |
| tradeId | Trade id as string |
| clientOrderRef | Unique identifier for the order as assigned by client as string. This will be echoed back from the request |
| legId | leg identifier as number |
| side | Side of the Order. Can be either SELL or BUY. In the case of a Swap, the side should reflect the far leg of the transaction. E.g. on a sell/buy, BUY and bid price should be used from near leg and offer price should be used from far leg. |
| tradingCurrency | ISO 4217 Currency code |
| contraCurrency | ISO 4217 Currency code |
| transactionAmount | transaction amount as fractional digit |
| rate | Price of the trade as fractional digit (Spot rate for Spots, All-in rate for Outrights, Near leg all in for Swaps). |
| spotRate | The spot rate of the trade as number. |
| forwardPoints | F/X forward points added to SpotRate as fractional digit. May be a negative value. Expressed in formatted form. For example, 61.99 points |
| symbols | Currency pair in format CCY1CCY2. ISO 4217 Currency code (3 character) values |
| valueDate | Value date according to ISO 8601. I.e. yyyy-MM-dd |
| executionDate | Timestamp when the business transaction represented by the message occurred. Represented in UTC (Universal Time Coordinated) in ISO 8601 format yyyy-MM-dd HH:MM:SS |
| product | Product. Must be one of SPOT, FORWARD, SWAP, BLOCK, NDF |
| tenor | Specifies the tenor for the order |
curl /premium-fx-trade-retriever/5560451808/fx-trades?from-date=2024-01-23&to-date=2025-01-23
Response
[{
"contraCurrency": "SEK",
"executionDate": "2025-03-06 14:16:48",
"forwardPoints": 0.0,
"legSource": "NEAR",
"orderId": "889453",
"product": "SPOT",
"rate": 10.23456,
"side": "SELL",
"spotRate": 10.2322,
"symbol": "EUR/SEK",
"tradeId": "FX.112023",
"tradingCurrency": "EUR",
"transactionAmount": 1000000.0,
"valueDate": "2025-01-17"
},{
"contraCurrency": "SEK",
"executionDate": "2025-03-0614:16:48",
"forwardPoints": 1.22,
"legSource": "NEAR",
"orderId": "889454",
"product": "FORWARD",
"rate": 10.23456,
"side": "SELL",
"spotRate": 10.2322,
"symbol": "EUR/SEK",
"tenor": "1M",
"tradeId": "FX.112824",
"tradingCurrency": "EUR",
"transactionAmount": 1000000.0,
"valueDate": "2025-02-17"
}]
On non 2xx-status codes the response will be an error response describing the problem. The format is compliant with problem+json
| Code | Description |
|---|---|
| 200 | Successful, transaction found within the time range |
| 204 | Successful, no transaction found within the time range |
| 400 | Requested organization has no account for FX trades or invalid values for parameters |
| 401 | Service provide is not authorized to make requests for this customer |
| 503 | Service not available at the moment |
example curl requests
FX Indicative Rates
Indicative quotes mirror the FX rates available for trading through the Market Order API.
GET /premium-fx-indicative-rates/{orgNr}/spot
GET /premium-fx-indicative-rates/{orgNr}/swap
GET /premium-fx-indicative-rates/{orgNr}/fwd
Path ParametersorgNr The organization number of the company.MANDATORY
Query Parameters
ccy-pairs - the requested ccy-pairs, a ccy-pair is two concatenated currency codes Mandatory.
value-dates - A comma separated list of requested value dates. Each Value date according to ISO 8601. I.e. yyyy-MM-dd
tenors - A comma-seaprated list of requested tenors. Supported tenors are described further down in the page
at least one value-date or tenor is required but a query can mix a combination of tenors and value dates in the query. Please note limitations applies how may tenors/dates that can be requested in the same query
ResponsesWhen successful, the payload consists of an array for each requested ccy-pair given values-dates and/or tenors object with the following fields:
| name | description | spot | swap | fwd |
|---|---|---|---|---|
| symbol | Currency pair in format CCY1CCY2. ISO 4217 Currency code (3 character) values | x | x | x |
| bid | bid as string | x | x | x |
| ask | ask as string | x | x | x |
| valueDate | Value date according to ISO 8601. I.e. yyyy-MM-dd | x | x | x |
| timeOfUpdate | Timestamp when the rate was updated. Represented in UTC (Universal Time Coordinated) in ISO 8601 format yyyy-MM-dd'T'HH:mm:ss.SSSXXX | x | x | x |
| rateStatus | Status. Must be one of ok, na or stale |
x | x | x |
On non 2xx-status codes the response will be an error response describing the problem. The format is compliant with problem+json
| Code | Description |
|---|---|
| 200 | Successful, all requested prices are found |
| 206 | Successful, but only a partial set of prices could be found |
| 400 | Invalid request |
| 401 | Service provider is not authorized to make requests for this customer |
| 404 | Could not find any prices |
| 503 | Service not available (Temporary) |
Request
curl /premium-fx-indicative-rates/5560451808/spot?ccy-pairs=SEKUSD
Response
[{
"ask": "0.09212",
"bid": "0.08939",
"rateStatus": "ok",
"symbol": "SEKUSD",
"timeOfUpdate": "2025-01-23T11:38:49.444Z",
"valueDate": "2025-01-27"
}]
FX Market Order
Enables clients to execute the conversion as a spot transaction or on a date of the users preference,
POST /premium/v1/premium-fx-market-order/{id}/spot
POST /premium/v1/premium-fx-market-order/{id}/swap
POST /premium/v1/premium-fx-market-order/{id}/fwd
Path ParametersorgNr The organization number of the company.MANDATORY
Query Parameters
There are no query paremeters for the request
PayloadThe Market Order API accepts a payload with the following fields:
m=mandatory, o=optional, n/a=forbidden
| name | description | spot | fwd | swap |
|---|---|---|---|---|
| ccyPair | CCY pair in format CCY1CCY2. ISO 4217 Currency code (3 character) values | m | m | m |
| amount | Order Amount as fractional digit | m | m | m |
| amountCcy | Currency that amount is expressed in. ISO 4217 Currency code (3 character) values | m | m | m |
| companyId | Identifier for the company | m | m | m |
| acocunt | Account ID of the company that the request is done for. Absence of this field will default to CompanyId | o | o | o |
| valueDate | Near value date according to ISO 8601. I.e. yyyy-MM-dd | o | * | * |
| tenor | Specifies the tenor for the order | o | o | o |
| user | Name of trader or user responisble for this order | o | o | o |
| side | Side of the order. Must be either SELL or BUY | m | m | m |
| farLegAmount | Order Amount of far leg for swaps as number. Absence of this field will default to ner leg amount | n/a | n/a | o |
| farLegValueDate | Far value date according to ISO 8601. I.e. yyyy-MM-dd | n/a | n/a | ** |
| farLegTenor | Specifies the tenor for the far leg of an FX Swap. | n/a | n/a | ** |
| clientOrderRef | Unique identifier for the order as assigned by client. | o | o | o |
*) the valueDate or tenor must be set, not both **) the farLegValueDate or farLegTenor must be set, not both
ResponseWhen successful, the payload consists of an object with the following fields:
| name | description | spot | fwd | swap |
|---|---|---|---|---|
| orderId | OrderID as string assigned by Bank | x | x | x |
| tradeId | TradeID as string | x | x | x |
| clientOrderRef | Unique identifier for the order as assigned by client. This will be echoed back from the request | x | x | x |
| legId | LegID as number | x | x | x |
| side | Side of the Order. Can be either SELL or BUY. In the case of a Swap, the side should reflect the far leg of the transaction. E.g. on a sell/buy, BUY and bid price should be used from near leg and offer price should be used from far leg. | x | x | x |
| tradingCurrency | ISO 4217 Currency code for currency that amount is expressed in. | x | x | x |
| contraCurrency | ISO 4217 Currency code for contra currency | x | x | x |
| transactionAmount | transaction amount as fractional digit | x | x | x |
| rate | Price of the trade as fractional digit (Spot rate for Spots, All-in rate for Outrights, Near leg all in for Swaps). | x | x | x |
| spotRate | The spot rate of the trade as number. | x | x | x |
| forwardPoints | F/X forward points added to SpotRate. May be a negative value. Expressed in formatted form. For example, 61.99 points | x | x | x |
| symbol | Currency pair in format CCY1CCY2. ISO 4217 Currency code (3 character) values | x | x | x |
| valueDate | Value date according to ISO 8601. I.e. yyyy-MM-dd | x | x | x |
| executionDate | Timestamp when the business transaction represented by the message occurred. Represented in UTC (Universal Time Coordinated) in ISO 8601 format yyyy-MM-dd HH:MM:SS | x | x | x |
| product | Product. Must be one of SPOT, FORWARD, SWAP, BLOCK, NDF | x | x | x |
| tenor | Specifies the tenor for the order. | x | x | x |
| status | status | x | x | x |
| Code | Description |
|---|---|
| 200 | Successful |
| 400 | Invalid request |
| 401 | Service provider is not authorized to make requests for this customer |
| 503 | Service not available (Temporary) |
POST /v1/premium-fx-market-order/{id}/spot
{
"ccyPair": "EURUSD",
"amount": 1000,
"amountCcy": "EUR",
"companyId": "string",
"account": "string",
"valueDate": "2030-05-20",
"tenor": "SP",
"user": "Gordon Gekko",
"side": "string",
"clientOrderRef": "MyUniqueId-12345"
}
{
"orderId": 123,
"tradeId": "FX.15532",
"clientOrderRef": "Order#1234",
"legId": 0,
"side": "SELL",
"tradingCurrency": "EUR",
"contraCurrency": "USD",
"transactionAmount": 10,
"rate": 3.4,
"spotRate": 1.2,
"forwardPoints": 1.2,
"symbol": "EURUSD",
"valueDate": "2024-04-23",
"executionDate": "2024-04-24",
"product": "SPOT",
"tenor": "SP",
"status": "ok"
}
Limitations
Supported tenorsThe following tenors are supported:
TD, TM, SP, SN, 1W, 2W, 3W, 1M, 2M, 3M, 4M, 5M, 6M, 7M, 8M, 9M, 10M, 11M, 1Y, 13M, 14M, 15M, 18M, 21M, 2Y
Limitations applies how big queries can be sent to the system. The limitation applies both the number of requested items (currency-pairs, values-dates and tenors) are requested, how wide time-ranges that can be searched in the same query and the number of sent queries per minutes. In this case the api will return back an error code.