Enabling instrument events in your LUSID domain

Instrument events are disabled by default to prevent unintended changes to existing portfolios. To enable them you must:

Create a recipe that, as a minimum, can locate suitable market data for the instruments you hold.
Register that recipe with every portfolio you wish instrument events to impact.

Note that an instrument event is either:

An instrument lifecycle event. See a list.
A corporate action event. See a list.

Creating a portfolio recipe

A recipe is a hierarchical, modular document whose primary purpose is to govern valuation operations. More information.

Note: You can create a recipe that both enables instrument events for portfolios and governs valuation operations on those same portfolios. You do not have to create separate recipes.

For simple instruments such as equities and fixed-rate bonds, we recommend creating a basic recipe that is able to locate FX spot rates loaded in the LUSID Quote Store. This is to ensure that LUSID can calculate cost basis correctly in circumstances where transaction, settlement and/or portfolio currencies are not the same.

For more complex instruments, your recipe will likely be required to locate other market data. For example, LUSID requires fixings for inflation-linked bonds in order to calculate coupon amounts correctly.

As a minimum, we recommend calling the UpsertConfigurationRecipe API to create a basic recipe as follows. See Appendix A for a more sophisticated recipe for more complex instruments.

curl -X POST 'https://<your-domain>.lusid.com/api/api/recipes'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
  "configurationRecipe": {
    "scope": "MyRecipes",
    "code": "MyBasicPortfolioRecipe",
    "description": "Recipe for enabling instrument events and locating FX rates",
    "market": {
      "marketRules": [
        {
          "key": "Fx.*.*",
          "supplier": "Lusid",
          "dataScope": "MyFxRates",
          "quoteType": "Rate",
          "field": "mid",
          "quoteInterval": "1D.0D"
        }
      ]
    }
  }
}'

Note that, to comply with this example, FX rates loaded into the LUSID Quote Store must be encapsulated in a MyFxRates quote scope. You can change the dataScope field above to specify a more suitably-named quote scope.

You can of course also change the scope and code fields of the recipe itself to more suitable values, providing the latter is unique within the former.

Registering the recipe with portfolios

Existing portfolios

Call the PatchPortfolioDetails API to register the scope and code of the recipe with each existing portfolio in turn, for example:

curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/US-Equities/Income/details'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '[
  {
    "value": {
      "scope": "MyRecipes",
      "code": "MyBasicPortfolioRecipe"
    },
    "path": "/instrumentEventConfiguration/recipeId",
    "op": "add"
  }
]'

In the LUSID web app, navigate to the Data Management > Portfolios dashboard, locate the portfolio, click the Edit button (at the end of the row), click Next to open the Details screen and then select the recipe from the Holdings recipe dropdown:

New portfolios

Call the CreatePortfolio API and specify an instrumentEventConfiguration object to register the recipe when you create a portfolio, for example:

curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/US-Equities'
-H 'Authorization: Bearer <your-API-access-token>'
-H 'Content-Type: application/json-patch+json'
-d '{
  "displayName": "Income portfolio for US equities",
  "code": "Income",
  "created": "2024-10-30T00:00:00Z",
  "baseCurrency": "USD",
  "instrumentEventConfiguration": {
    "recipeId": {
      "scope": "MyRecipes",
      "code": "MyBasicPortfolioRecipe"
    }
  }
}'

In the LUSID web app, navigate to the Data Management > Portfolios dashboard, click the Create portfolio button and follow the instructions, making sure to select the recipe from the Holdings recipe dropdown on the Details screen:

Appendix A

The following recipe might be suitable for looking up fixings for floating rate bonds and for inflation-linked bonds as well as FX spot rates:

curl -X POST 'https://<your-domain>.lusid.com/api/api/recipes'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
  "configurationRecipe": {
    "scope": "MyRecipes",
    "code": "MyComplexPortfolioRecipe",
    "description": "Recipe for enabling instrument events and locating FX rates and fixings",
    "market": {
      "marketRules": [
        {
          "key": "Fx.*.*",
          "supplier": "Lusid",
          "dataScope": "MyFxRates",
          "quoteType": "Rate",
          "field": "mid",
          "quoteInterval": "1D.0D"
        },
        {
          "key": "Quote.RIC.*",
          "supplier": "Lusid",
          "dataScope": "MyFloatingBondFixings",
          "quoteType": "Rate",
          "field": "mid",
          "quoteInterval": "1D.0D"
        },
        {
          "key": "Inflation.InflationIndex.*",
          "supplier": "Lusid",
          "dataScope": "MyInflationIndexFixings",
          "quoteType": "Index",
          "field": "mid",
          "quoteInterval": "1D.0D"
        }
      ]
    }
  }
}'