Banking Circle offers a multitude of different options to execute foreign exchange (FX) transactions. These can be grouped into three high-level styles:

• Multicurrency payments: Where the foreign exchange transaction is a part of a payment between two different currencies
• Fully automated FX risk management: FX Trades executed via our Banking Circle FX API
• Active risk and liquidity management: Manual trading scenarios on Banking Circle Connect (BCC) or on our Real Time FX platform (RTFX)

Each scenario further supports a variety of workflows ranging from basic FX trading at live market rates to more advanced risk management and treasury related functions.

This page will give you an overview of these workflows and guide your developers on how to interact with our FX APIs.

Banking Circle FX

Banking Circle FX API enables your business to programmatically execute foreign exchange conversions between your currency accounts at Banking Circle using a simple REST API that supports both two different workflow types: FX trading in market order fashion, and Request For Quote (RFQ).

These workflows are primarily intended for FX Risk management purposes. For scenarios relating to payments, please refer to the Multicurrency payments workflow that is better suited for pay-out purposes.

FX Trading

For scenarios where simplicity and automation is of key importance, our BC FX Trade endpoint enables you to execute trades using a simple POST request.

The transaction will be done in market order fashion: your deal will be filled at the prevailing FX market rate and you will receive an instant confirmation with the relevant trade details such as the exchange rate and converted amounts.

Each transaction will be settled on your currency accounts immediately following our confirmation, with the exception of bank holidays where the settlement moves to the next available date instead. You may specify 'TN' in the tenor field for next-day or 'SPOT' for SPOT settlement.

📘

Multiple legal entities?

If you have multiple legal entities or a company structure that requires the use of multiple companies in Banking Circle context, you should additionally specify the (optional) customerId field in the order to ensure the trade lands on correct bank accounts. You can retrieve the customerId by calling the Accounts endpoint. Here the parameter is called companyNumber.

Below is an example FX Trade POST request where you are buying 10,000 EUR against GBP with value date today. The customerId field is optional and should be used only in case of multiple legal entities.

{  
  "clientOrderId": "YourUniqueReference",  
  "buyCurrency": "EUR",  
  "sellCurrency": "GBP",  
  "amount": 10000,  
  "amountCurrency": "EUR",  
  "tenor": "ON",  
  "customerId": "000012356"  
}

// customerId is optional: use it if you have multiple legal entities

In response, our API will confirm the trade with exchange rate and your sold GBP amount.

{  
  "tradeStatus": "Filled",  
  "clientOrderId": "YourUniqueReference",  
  "bankingCircleRef": "2110081351166",  
  "customerId": "000012356",  
  "boughtCurrency": "EUR",  
  "boughtAmount": 10000,  
  "soldCurrency": "GBP",  
  "soldAmount": 8492.99,  
  "currencyPair": "EURGBP",  
  "exchangeRate": 0.8492993,  
  "valueDate": "2021-10-08"  
}

Similarly, you can choose to buy X EUR by selling 10,000 GBP, in which case the converted amount will be in EUR.

📘

Use clientOrderId or bankingCircleRef to query for or reconcile your FX transactions

The client order id in your order as well as the banking circle reference in your trade confirmation can be used as search criteria to retrieve further details about your transactions via our FX transactions endpoint. BankingCircleRef is furthermore available in the account reconciliation endpoint in field PaymentDetails3.

Trading Limits

For each of our supported currencies, we also have a maximum amount you may trade in a single trade. These are listed below.

If your workflow requires single trades higher than these limits, we would like to hear from you as we may potentially be able to increase our limits. Please contact your account manager in this case. Alternatively, you may also split your trade into multiple trades, provided you leave a sufficient period in between each trade (such as 30-60 seconds).

Request For Quote (RFQ)

In some scenarios it is necessary to know the exchange rate ahead of executing a transaction. Our Request For Quote (RFQ) workflow enables you to fetch a firm (tradable) foreign exchange quote that is valid for 30 seconds at a time for any of our supported value dates (today, tomorrow, and SPOT). In principle, this is exactly the rate that you would have executed on if you had submitted a trade in market order fashion at the same time.

The quote contains both an expiration timestamp as well as an id that can be attached as a part of an BCFX order. This will guarantee that your order will be completed at this exchange rate.

Each transaction will be settled on your currency accounts immediately following your confirmation, provided your original request was for today's value date and you are not utilizing a trading/credit line. Transactions with a value date in the future, such as TN (tomorrow) or SPOT, will not be settled until the value date arrives and you have sufficient funding on your account.

📘

Multiple legal entities?

If you have multiple legal entities or a company structure that requires the use of multiple companies in Banking Circle context, you should additionally specify the (optional) customerId field in the order to ensure the trade lands on correct bank accounts.

Just like with trades submitted as market orders, settlement with value date today is not possible during a bank holiday in either currency, in which case only value date tomorrow and SPOT are available.

To request a quote for trading, you only need to supply the two currencies involved, the trade amount, the desired tenor, and indicate the currency of the amount.

Below is an example GET request for retrieving a quote to be used for trading 10,000 EUR against GBP with value today (use TN for value date tomorrow, or SPOT):

// Add the optional request parameter &customerId=<your-customer-id> if you have multiple legal entities  
Our API will then respond with a firm quote featuring a quote ID and the expiry time.
Note, outside our opening hours, you'll receive an indicative quote instead, which cannot be used for trading.
{  
  "quoteType": "Tradable",  
  "currencyPair": "EURGBP",  
  "exchangeRateBid": 0.848001,  
  "exchangeRateAsk": 0.8491892,  
  "expiryTime": "2021-10-08T13:55:17.4276206+00:00",  
  "quoteId": "bf56e3bc-269a-4db5-be4d-71ccf789d5ab"  
}

You can then use this quote to execute a Banking Circle FX order using a POST request - in this example we are buying 10,000 EUR (do not submit a tenor field in the RFQ workflow as it is derived from your quote):

📘

Tradable quote types

Only 'Tradable' quote types can be used for trading. Each quote can only be used once.

{  
  "clientOrderId": "YourUniqueReference",  
  "buyCurrency": "EUR",  
  "sellCurrency": "GBP",  
  "amount": 10000,  
  "amountCurrency": "EUR",  
  "quoteId": "bf56e3bc-269a-4db5-be4d-71ccf789d5ab",  
  "customerId": "000012356"  
}  
// customerId is optional, but must be specified if used in quote retrieval

Our API will then respond to your trade with a confirmation:

{  
  "tradeStatus": "Filled",  
  "clientOrderId": "YourUniqueReference",  
  "bankingCircleRef": "2110081357029",  
  "customerId": "000012356",  
  "boughtCurrency": "EUR",  
  "boughtAmount": 10000,  
  "soldCurrency": "GBP",  
  "soldAmount": 8491.89,  
  "currencyPair": "EURGBP",  
  "exchangeRate": 0.8491892,  
  "valueDate": "2021-10-08"  
}

📘

Use clientOrderId or bankingCircleRef to query for or reconcile your FX transactions

The client order id in your order as well as the banking circle reference in your trade confirmation can be used as search criteria to retrieve further details about your transactions via our FX transactions endpoint. BankingCircleRef is furthermore available in the account reconciliation endpoint in field PaymentDetails3.

Held Rates

In case you need to retrieve a rate that is valid for more than 30 seconds, you can request a held rate specifying the validity time period for the quote in minutes, up to 24 hours. The workflow is mostly the same as for RFQ with a few differences. The quote is not limited to one trade, it is not amount specific, and the only supported tenor is ON (today). Furthermore, held rate trades are subject to maximum EUR equivalent amount per day limit and are continuously available throughout the week starting from Sydney open (Sunday evening in Europe) until 5pm New York time.

To request a held rate, you need to supply the two currencies involved and time of quote being valid in minutes.

Below is an example GET request for retrieving a held rate to be used for trading EUR against GBP valid for 24 hours (1440 minutes):

HTTP GET /api/v1/fx/rates/held-rates/EUR/GBP?validForMinutes=1440

Add the optional request parameter &customerId=<your-customer-id> if you have multiple legal entities.

Our API will respond with a firm quote exactly as RFQ featuring a quote ID and expiry time.

{  
  "quoteType": "Tradable",  
  "currencyPair": "EURGBP",  
  "exchangeRateBid": 0.8674233,  
  "exchangeRateAsk": 0.8687751,  
  "expiryTime": "2023-05-12T10:08:54.9242534+00:00",  
  "quoteId": "faef3f2f-6ef1-4331-9c70-813adfaf77p9"  
}

You may use the quote multiple times until it expires by executing Banking Circle FX orders, using exactly the same workflow as in our request-for-quote workflow above.

The main difference is that our API may sometimes respond to your orders with tradeStatus as Pending. A pending trade can be considered filled provided the sell account has sufficient funding, and simply means that the booking of the trade is delayed (for example due to operations relating to end of day calculations, or in case of technical issues with our settlement system)

In such a case, you can query for your trade status using our FX Held Rate status endpoint as below:

HTTP GET /api/v2/fx/held-rates/status?clientOrderId=YourUniqueReference

Table of Operations

It is possible to execute exactly four different combinations of buy and sell orders using our API. This will allow you to place your fixed amount on either currency, whether you are selling or buying that currency.

The four possibilities:

The 'X' amount is calculated using the prevailing FX rate

Supported Tenors and Value Dates

Banking Circle currently supports the following tenors for settlement: ON for value date today, TN for value date tomorrow, and SPOT for settlement at T+2 (or T+1 for some currency pairs).

Value date ON will typically settle immediately following a filled trade confirmation, unless you are utilizing a trading line or our collateral setup to defer settlement until you have sufficient funding on your account. In this case, the trade will settle immediately after sufficient funding arrives on your account.

Value date tomorrow and SPOT will settle as the value date arrives, provided you have sufficient funding on your account. Otherwise, the settlement will take place during the day when your account is credited with enough balance to cover the sold amount.

During bank holidays in either currency, the value dates will move forward accordingly. For example, trading EURDKK with value date SPOT on the Wednesday preceding Easter will settle on the following Wednesday, due to DKK bank holidays on Thursday, Friday, and Monday.

Multicurrency Payments

This is our product for payments between two different currencies either on your own accounts, or for outgoing and incoming payments. We support both a fully automated and a request-for-quote type of a workflow for payments.

The fully automated flow allows you to instruct payments in all of our supported currencies, where the foreign exchange conversion is completed as a part of your payment automatically when the payment is processed. This applies for both incoming and outgoing payments.

Multicurrency Payments RFQ

It is possible to request a foreign exchange quote upfront for a single payment using our Multicurrency Payments RFQ endpoint.

This quote is valid for 30 seconds at a time and can be attached to a payment instruction using the single payment instruction endpoint. The payment will then be processed using exactly this exchange rate.

The prerequisite for using instructing a payment with an exchange rate is that your execution date is today's date, and that you have pre-funded your debit account. Workflows where your debit account is not funded prior to the payment instruction are not supported for Multicurrency Payments RFQ, and will be processed with the prevailing exchange rate at the time of processing when your account has been funded.

In order to request an Multicurrency Payments quote, you only need to supply your intended debit currency, the credit (transfer) currency, the expected payment amount, and indicate whether the payment amount is in the debit or credit currency terms.

Below is an example request for requesting a quote to be used for a multicurrency payment where you are sending 17,500 DKK from your DKK account to a recipient in JPY:

//Our API will respond with an exchange rate which will be valid for 30 seconds
{  
  "quoteType": "Tradable",  
  "currencyPair": "JPYDKK",  
  "exchangeRate": 0.057962,  
  "quoteId": "416f5058-660f-4b2e-a62f-44d2b0e83fd8",  
  "expiryTime": "2021-10-08T14:04:01.2295277+00:00"  
}
 

You can then use the quoteId from the quote to instruct a single payment:

Other unrelated fields omitted for brevity

{
  "debtorAccount": {
    "account": "DK7189000000010504",
    "country": "DK",
    "financialInstitution": "SXPYDKKKXXX"
  },
  "currencyOfTransfer": "JPY",
  "amount": {
    "amount": "17500",
    "currency": "DKK"
  },
  "creditorAccount": {
    "account": "DK0989000000010359",
    "financialInstitution": "SXPYDKKKXXX",
    "country": "DK"
  },
  "fxQuoteId": "416f5058-660f-4b2e-a62f-44d2b0e83fd8"
}

Notice that the quote id is attached to the fxQuoteId field, and that all amounts and currencies match with the original request.

📘

RFQ for Bulk payments

Request for quote is currently not available for bulk payments

Multicurrency Payments RFQ - Table of Operations

When submitting a Multicurrency Payment and specifying a previously requested quote, the currency and the amount used must match in both requests.

For example, if your intention is to debit your DKK account by exactly 17.500 DKK, and convert it to a JPY amount, and send that JPY amount to your beneficiary, you must also use these parameters in your FX rate request. In your payment instruction, you should subsequently use DKK as the amount currency and 17.500 (or less) as the amount.

Conversely, if your intention is to send an exact amount of JPY to your beneficiary by debiting your DKK amount, you should use JPY as your amount currency in your FX rate request.

The possible combinations for the different fields are shown in the table below.

The 'X' amount is calculated using the prevailing FX rate

Indicative Rates

It is possible to retrieve an indicative foreign exchange quote from Banking Circle using a simple GET request. This will give you a rough approximation of the exchange rate currently available if you were to initiate either a cross-border payment or an Banking Circle FX order at the time of the request.

The Foreign Exchange market moves rapidly - volatile periods can result in thousands of microscopic price movements per second. As such, querying the endpoint multiple times for the same two currencies will not usually produce the same quote. In most payment scenarios, however, these movements are relatively insignificant.

Indicative rates can be retrieved from the Banking Circle FX request-for-quote (RFQ) endpoint as described above. Outside of our opening hours and during periods where the FX market is closed, it is only possible to retrieve indicative quotes.

Retrieving FX Transactions

Our API supports querying for your FX trades executed with us using various filtering criteria, including any transactions completed on our Real Time FX platform.

For example, if you have recently traded using YourUniqueReference in the clientOrderId field, you can query for this transaction using the FX Transactions endpoint as follows:

 {  
      "bankingCircleRef": "2110081357029",  
      "clientOrderId": "YourUniqueReference",  
      "tradeDate": "2023-05-01T09:24:23.952569",  
      "valueDate": "2023-05-03T00:00:00",  
      "boughtAmount": 10000,  
      "boughtCurrency": "EUR",  
      "boughtAccount": {  
        "accountId": "5fefb9c7-dd52-bb8b-3326-d79af1c7728",  
        "bankAccount": "DK7789000000000114"  
      },  
      "soldAmount": 8491.89,  
      "soldCurrency": "GBP",  
      "soldAccount": {  
        "accountId": "f88a4aad-5ca8-dc04-4941-1d97fbab6128",  
        "bankAccount": "DK9389000000000214"  
      },  
      "exchangeRate": 0.8491892,  
      "transactionStatus": "Settled"  
    }  
  ],  
  "pageInfo": {  
    "currentPage": 1,  
    "pageSize": 1  
  } 

Our API would then respond with your transaction details, including the settlement accounts used in the transaction:

You can also filter your transactions using other criteria, such as dates, accounts used, or currencies involved. All available filtering criteria are described in our API Reference section.

📘

Multicurrency Payments

Multicurrency Payments are not available from this endpoint as they are considered payments rather than FX trades. Please refer to the Single or Bulk Payments documentation for details on how to query for payments information

Trade lifecycle

All FX trades contain a transaction status when retrieved through the transactions endpoint. This status will indicate the current state of the transaction. All trades follow a standard lifecycle, which is as follows:

• Value date today with immediate settlement: Settled -> (only if cancelled) Cancelled
• Value date in the future, or without immediate settlement: Open -> Settled -> (only if cancelled) Cancelled

For example, let's assume you decide to buy 10,000 EUR against USD at value SPOT. If you were to retrieve this transaction immediately afterward, it would be marked as Open as the settlement would take place in two banking days time (unless there are any holidays in between). If you retrieve that same transaction again on the same or a later date, it would be marked as Settled, as the money will have been debited and credited from your two currency accounts accordingly.

Real Time FX (RTFX)

Real Time FX is our single dealer platform where you can execute FX trades and monitor market activity in a state-of-the-art graphical user interface.

Real Time FX supports FX SPOT, short-dated FX Forwards (T+0/T+1), and FX Swaps.

In addition to the user interface, it is also possible to integrate to the platform via a FIX API, which will give you access to electronic streaming prices (ESP). This integration is intended for sophisticated FX market participants only. Please contact us for more information.