Understanding instrument scopes

Related resources:

Like most LUSID entities, instruments are stored in a scope. This has the following benefits:

• You can maintain completely different instrument masters for different clients in the same LUSID domain by loading their instruments into separate scopes.
• You can assign access control permissions to scopes, in order to hide sensitive commercial information. For example, you could store CFD instruments (in which the contract is embedded in the definition) in a custom scope that only managers are allowed to access.
• You can duplicate a particular set of instruments in different scopes and configure a portfolio to resolve transactions against each one in turn. This means you could test the economic impact of changing some or all of the instrument definitions in one of the scopes, for example flow conventions for swaps.

Note: For the purpose of resolving transactions (and other data items) to instruments, scopes exhibit a hierarchy, so for example you can store non-sensitive instruments (such as equities) in the built-in default scope, sensitive instruments in an access-controlled custom scope, and expect a portfolio to resolve transactions first against instruments in the custom scope, before falling back to the default scope.

Partitioning your LUSID instrument master into multiple scopes is optional. If you choose not to create custom scopes, then instruments are automatically stored in the built-in default scope, and you can ignore scopes entirely when interacting with instruments.

Note: All instruments mastered before January 2022 are automatically stored in the default scope. If you create a custom scope and do not explicitly specify it when listing or finding instruments, only the default scope is searched. When searching, LUSID does not fall back to searching the default scope from a custom scope in the same way as it does when resolving transactions to instruments.

Upserting instruments to a particular scope

Providing you have appropriate access control permissions, you can call the LUSID UpsertInstruments API to upsert an instrument to a particular scope. Note the following:

• You can upsert the ‘same’ instrument to different scopes (that is, create identical instrument definitions representing the same financial asset in multiple scopes). This means that unique market identifiers such as FIGIs are actually only unique to their scope; two instrument definitions can have the same FIGI in different scopes.
• However, LUSID always generates a globally unique LUID for an instrument. This means that two identical instrument definitions in two scopes may have the same FIGI but will always have different LUIDs.
• Currency instruments only exist in the default scope. LUSID is prepopulated with a basket of currencies so you should not need to create currency instruments, but if you do then you cannot upsert them to a custom scope.
• You cannot change the scope of an instrument that has already been upserted. You would need to deactivate the instrument in one scope and upsert it again to another.
• If you do not explicitly specify a scope, an instrument is upserted to the default scope.

For example, to upsert an equity instrument representing BP PLC $0.25 shares to mysecretscope (the scope will be automatically created if it does not exist):

curl -X POST "https://<your-domain>.lusid.com/api/api/instruments?scope=mysecretscope"
   -H "Authorization: Bearer <your-API-access-token>"
   -H "Content-Type: application/json-patch+json"
   -d '{"upsert-request-1": {
    "name": "BP $0.25 LDN",
    "identifiers": {
      "Figi": {"value": "BBG000C05BD1"}
      },
    "definition": {
      "instrumentType": "Equity",
      "domCcy": "GBP",
      }
  }
}'

The response confirms the scope:

{
 "values": {
   "upsert-request-1": {
     "href": "https://<your-domain>.lusid.com/api/api/instruments/LusidInstrumentId/LUID_00003D5P?scope=mysecretscope",
     "scope": "mysecretscope",
     "lusidInstrumentId": "LUID_00003D5P",
     ...

Configuring a portfolio to resolve transactions against a hierarchy of scopes

You have the option to specify an instrument scope when you create a portfolio. If you do, LUSID attempts to resolve transactions booked into the portfolio to instruments stored in that scope. If it cannot, or you do not specify an instrument scope, LUSID automatically falls back to the instruments in the default scope. If LUSID still cannot resolve transactions, it maps them to the unknown instrument.

Note the following:

• You can assign an instrument scope to a transaction portfolio and to a reference portfolio. A derived transaction portfolio inherits the instrument scope of its parent, if specified.
• You cannot (currently) specify more than one instrument scope for a portfolio at a time.

For example, to create a transaction portfolio that requires LUSID to resolve transactions first against instruments in mysecretscope, before falling back to the default scope:

curl -X POST "https://<your-domain>.lusid.com/api/api/transactionportfolios/test"
   -H "Authorization: Bearer <your-API-access-token>"
   -H "Content-Type: application/json-patch+json"
   -d '{
    "displayName": "Portfolio UK",
    "code": "PortfolioUk",
    "baseCurrency": "GBP",
    "instrumentScopes": [
      "mysecretscope"
    ],
    ...
}'

A note about corporate actions

You can also specify an instrument scope when you create a corporate action source, in the same way as a portfolio.

If a portfolio with a custom instrument scope subscribes to a corporate action source with a different instrument scope, then resulting corporate actions in that portfolio will not be applied to holdings. One resolution would be to duplicate the corporate action source and give it the same instrument scope as the portfolio (assuming it is the only portfolio that subscribes).

A note about orders and allocations

LUSID must also resolve orders and allocations to instruments, in the same way as transactions and corporate actions.

When you create an order or allocation, if you reference a portfolio that exists and that portfolio has a custom instrument scope, then LUSID attempts to resolve the order or allocation to instruments in that scope. If not, LUSID falls back to the default scope.