Exchanges

Exchanges are requests to sell an amount of source currency for a target currency (Sell exchange), or to buy a specific amount in a target currency using a source currency (Buy exchange). The source currency is always the currency sold, the target currency is always the currency bought.

Root endpoint

The root endpoint for OData queries for exchanges is /api/v1/Accounts({AccountId})/Exchanges.

Exchange lifecycle

Creating an exchange

POST /api/v1/Exchanges/Create HTTP/1.1
Host: portal.wearefreemarket.com
Authorization: Bearer {authToken}
Content-Type: application/json

{
    "AccountId": 12345,
    "Goal": 10000,
    "GoalType": "Sell",
    "SourceCurrencyCode": "EUR",
    "TargetCurrencyCode": "GBP",
    "UseAvailableFunds": true,
    "ReceiverLei": "01234567890123456789"
}

parameter	description	data type	validation rules
AccountId	the account that the exchange will be created for	int	required
Goal	the amount to exchange (buy or sell)	decimal	required
GoalType	the type of exchange goal, either "Buy" or "Sell"	string	required
SourceCurrencyCode	the currency to be sold	string	required
TargetCurrencyCode	the currency to be bought	string	required
UseAvailableFunds	a flag indicating whether the exchange will be allocated using available account balance	boolean	optional, false by default
ReceiverLei	A Legal Entity Identifier (LEI) is a 20-character alphanumeric code that uniquely identifies a legal entity engaged in financial transactions - Search for a LEI. For more information around LEIs, please click here.	string	conditional - only required when the CurrencyCode is GBP and the beneficiary is a company with a Vertical of FI and the Industry is Banks or Building Societies

Exchange allocation

In order for an exchange to be eligible to participate in the next scheduled round of exchanges, it needs to have sufficient funds allocated. When sufficient available funds were present on account during the creation of the exchange and the UseAvailableFunds parameter was set to true, the exchange will be allocated automatically. In all other cases, the exchange needs to be allocated after it was created.

After an exchange has been created, but not allocated, there are two options to allocate it, either by transferring-in the necessary funds (typically from a client's bank) using the exchange reference, or by allocating existing funds from the available account balance.

Allocating using a bank transfer

A bank transfer will be used to fund an existing exchange, if the expected amount and bank transfer reference was used. To find out what the correct amount and reference is, the API query endpoint for exchange bank transfer can be used:

GET /api/v1/Exchanges({exchangeId})/Deposits HTTP/1.1
Host: portal.wearefreemarket.com
Authorization: Bearer {authToken}

Based on the sample OData response below, for the funding of the exchange {exchangeId} there is a bank transfer required of 10,000.00 EUR with the reference A123456789ABC.

{
  "@odata.context": "https://portal.wearefreemarket.com/api/v1/$metadata#Exchanges({exchangeId})/Deposits",
  "value": [
    {
      "Id": 123,
      "CurrencyCode": "EUR",
      "Amount": 10000.0000,
      "Reference": "A123456789ABC",
      "StatusCode": "E",
      "Status": "Enabled"
    }
  ]
}

When the bank transfer arrives and is reconciled towards this exchange, the exchange automatically becomes funded and the associated bank transfer changes status to Completed.

Note

The bank transfer amount and reference has to exactly match the expected amount and reference in order to be applied towards the exchange. Use of the word ‘deposit’ in any API endpoint or webhook does not indicate or suggest that Freemarket offers regulated deposits or deposit accounts.

Allocating using available account balance

If there are sufficient available funds on the account, the API endpoint for exchange allocation can be used to allocate them towards the exchange.

POST /api/v1/Exchanges/{exchangeId}/Allocate HTTP/1.1
Host: portal.wearefreemarket.com
Authorization: Bearer {authToken}

Webhook events

Exchange created

This event is raised when an exchange has been created.

 [
    {
        "EntityType": "Instruction",
        "EntityId": 1234,
        "Reason": "InstructionCreated",
        "ApiUrl": "https://portal.wearefreemarket.com/api/v1/Exchanges(1234)"
    }
]

Exchange completed

This event is raised when an exchange has been completed and the target funds have been credited to the account.

 [
    {
        "EntityType": "Instruction",
        "EntityId": 1234,
        "Reason": "InstructionCompleted",
        "ApiUrl": "https://portal.wearefreemarket.com/api/v1/Exchanges(1234)"
    }
]