Transactions and exchange rates

When you create a transaction, the mandatory fields in the request assume that the transaction, settlement and portfolio currencies are the same.

For example, to buy 10 units of BP @ £20, paying and settling in GBP in a GBP-denominated portfolio, you only need set the totalConsideration.currency field to GBP and the totalConsideration.amount field to £200. Note the transactionPrice field is optional and shown below only for illustration; this is an informational field and not used for calculations by LUSID.

LUSID automatically sets the transactionCurrency field to GBP, the exchangeRate field to 1, the TradeToPortfolioRate system property to 1, and the SettledToPortfolioRate calculated field to 1 (more on these in the next section).

{
  "transactionRequest-1": {
    "transactionId": "Txn-0000001",
    "type": "Buy",
    "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000C6K6G9"},
    "transactionDate": "2023-05-15T00:00:00.0000000+00:00",
    "settlementDate": "2023-05-18T00:00:00.0000000+00:00",
    "units": 10,
    "transactionPrice": {"price": 20, "type": "Price"},
    "totalConsideration": {"amount": 200, "currency": "GBP"},
  }
}

Handling different transaction, settlement and portfolio currencies

Consider the following example, to buy 100 units of MSFT @ $30, paying in USD but settling in GBP in a EUR-denominated portfolio:

• The transactionCurrency field is the transaction currency, USD.
• The totalConsideration.currency field is the settlement currency, GBP.
• The totalConsideration.amount field is the trade amount in the settlement currency, £2,400.
• The exchangeRate field (rate from transaction to settlement currency) is the USD/GBP spot rate, 0.8. This enables LUSID to calculate the trade amount in the transaction currency: £2,400 / 0.8 = $3,000.
• The TradeToPortfolioRate system property records the USD/EUR spot rate, 0.9. This enables LUSID to calculate the trade amount in the portfolio currency, thereby maintaining the cost basis of the portfolio: $3,000 * 0.9 = €2,700. Note you can specify a system setting to automatically add the TradeToPortfolioRate system property to all transactions upon upsert.

{
  "transactionRequest-2": {
    "transactionId": "Txn-0000002",
    "type": "Buy",
    "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000BPH459"},
    "transactionDate": "2023-05-15T00:00:00.0000000+00:00",
    "settlementDate": "2023-05-18T00:00:00.0000000+00:00",
    "units": 100,
    "transactionPrice": {"price": 30, "type": "Price"},
    "transactionCurrency": "USD",
    "totalConsideration": {"amount": 2400, "currency": "GBP"},
    "exchangeRate": 0.8,
    "properties": {
      "Transaction/default/TradeToPortfolioRate": {
        "key": "Transaction/default/TradeToPortfolioRate",
        "value": {
          "metricValue": {"value": 0.9, "unit": ""}
        }
      }
    }
  }
}

Note: LUSID automatically sets the SettledToPortfolioRate calculated field to TradeToPortfolioRate / exchangeRate: 0.9 / 0.8 = 1.125. This means you do not need to supply a GBP/EUR spot rate. This field can be used in the rate field of a side.

Booking FX transactions

Exchanging two currencies at the spot rate

Consider the following example, to sell GBP and buy USD at a spot rate of 1.2:

• The instrumentIdentifiers field maps the transaction to the sell currency instrument, GBP. Note all major currency instruments are pre-mastered in LUSID.
• The transactionCurrency field is the currency to sell, GBP.
• The units field is the amount to sell, £100,000.
• The totalConsideration.currency field is the currency to buy, USD.
• The totalConsideration.amount field is the trade amount in the buy currency, $120,000.
• The exchangeRate field is the GBP/USD spot rate, 1.2. This enables LUSID to calculate the trade amount in the sell currency: $120,000 / 1.2 = £100,000.

{
  "transactionRequest-3": {
    "transactionId": "Txn-0000003",
    "type": "FwdFxSell",
    "instrumentIdentifiers": {"Instrument/default/Currency": "GBP"},
    "transactionDate": "2023-05-15T00:00:00.0000000+00:00",
    "settlementDate": "2023-05-18T00:00:00.0000000+00:00",
    "transactionCurrency": "GBP",
    "units": 100000,
    "transactionPrice": {"price": 1, "type": "Price"},
    "totalConsideration": {"amount": 120000, "currency": "USD"},
    "exchangeRate": 1.2
 }
}

Modelling a FxForward as a transaction

Note: The recommended way to model a foreign exchange or currency forward contract ("FxForward") is to master an instrument in the LUSID Security Master and then book a unitised transaction in a portfolio. This is a small amount of extra setup, but LUSID's full suite of analytical capability is guaranteed to be available. See how to do this.

Alternatively, you can forgo mastering an instrument and book a forward-settled cash transaction directly in a portfolio with different buy and sell currencies, using the FwdFxBuy and FwdFxSell built-in transaction types provided with LUSID.

Consider the following example, of a transaction to sell GBP and buy USD in a EUR-denominated portfolio in 6 months' time at a strike rate of 1.2:

• The transaction type field is set to FwdFxSell but this could equally be FwdFxBuy with the amounts and rates reversed.
• The instrumentIdentifiers field maps the transaction to the sell currency instrument, GBP. Note all major currency instruments are pre-mastered in LUSID.
• The transactionDate field marks the start of the contract.
• The settlementDate field is the maturity date.
• The transactionCurrency field is the currency to sell, GBP.
• The units field is the amount to sell, £100,000.
• The totalConsideration.currency field is the currency to buy, USD.
• The totalConsideration.amount field is the trade amount in the buy currency: $120,000.
• The exchangeRate is the GBP/USD strike rate: 1.2. This enables LUSID to calculate the trade amount in the sell currency: $120,000 / 1.2 = £100,000.
• The TradeToPortfolioRate system property records the GBP/EUR spot rate, 1.1. This enables LUSID to calculate the trade amount in the portfolio currency, thereby maintaining the cost basis of the portfolio: £100,000 * 1.1 = €110,000.

curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/Funds/Managed/transactions/$batchUpsert?successMode=Partial' 
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
  "transactionRequest-4": {
    "transactionId": "Txn-0000004",
    "type": "FwdFxSell",
    "instrumentIdentifiers": {"Instrument/default/Currency": "GBP"},
    "transactionDate": "2023-06-07T00:00:00.0000000+00:00",
    "settlementDate": "2023-12-11T00:00:00.0000000+00:00",
    "transactionCurrency": "GBP",
    "units": 100000,
    "transactionPrice": {"price": 1, "type": "Price"},
    "totalConsideration": {"amount": 120000, "currency": "USD"},
    "exchangeRate": 1.2,
    "properties": {
      "Transaction/default/TradeToPortfolioRate": {
        "key": "Transaction/default/TradeToPortfolioRate",
        "value": {
          "metricValue": {
            "value": 1.1, "unit": ""
          }
        }
      }
    }
  }
}'

LUSID generates two temporary holdings for each FxForward booked as a transaction while the contract is live, one per currency. Note the holding type is Forward FX on the inception date, 7 June 2023, and that no units are settled:

When the contract matures, LUSID automatically updates the main cash holdings in the two currencies and removes the temporary holdings. Note the holding type is Cash Balance on the maturity date, 11 December 2023, and that all units are now settled: