How do I create a currency?

Providing you are a LUSID user with sufficient privileges, you can create an instrument modelling a new currency in the LUSID instrument master.

Note that your LUSID domain is prepopulated with a basket of currencies, so this should not be a common operation. However, there may be circumstances in which you need to create a new currency instrument, for example to represent a cryptocurrency.

Note: If you are the LUSID domain owner, you are automatically assigned the built-in lusid-administrator role, which has all the permissions necessary to perform the operations in this article.

Each currency is identified in the LUSID instrument master by its ISO 4217 currency code (for example GBP) and an automatically-generated LUSID Unique ID (or LUID) that prefixes the currency code with CCY_ (so for example CCY_GBP). Note the following LUIDs are reserved:

• CCY_ZZZ for the unknown currency. Note that, unlike non-currency instruments, LUSID does not automatically map unknown cash transactions to the unknown currency, so these data load operations will fail.

• CCC_XXX for a 'transaction' involving no currency.

Note: To see how to model a non-currency instrument such as an Equity, Bond, Future, Swap and more, start with this article.

Using the LUSID REST API

You can create up to 2000 instruments in a single API request.

1. Obtain an API access token.

2. Call the LUSID UpsertInstruments API for your LUSID domain, passing in your API access token and, for each currency instrument:

   • An ephemeral ID (to track errors in the response)

   • A display name

   • A single unique identifier of type Currency.

   • An identifier value consisting of the ISO 4217 code of the currency you want to create.

   Note that a new instrument is created if the display name and identifier value you specify in the API request do not yet exist in the built-in default instrument scope. Otherwise, an existing instrument is updated. Note currency instruments only exist in the default scope; you cannot upsert a currency to a custom scope.

   For example, to create a new instrument representing the ISO 4217 test code XTS (note this is not a meaningful currency):

   curl -X POST "https://<your-domain>.lusid.com/api/api/instruments"
      -H "Authorization: Bearer <your-API-access-token>"
      -H "Content-Type: application/json"
      -d '{"upsert-request-1": {
       "name": "XTS",
       "identifiers": {
         "Currency": {"value": "XTS"}
         }
     }
   }'

   If the request is successful, the response reveals the LUID for the instrument, in this case CCY_XTS:

   {
       "values": {
           "upsert-request-1": {
               "href": "https://<your-domain>.lusid.com/api/api/instruments/LusidInstrumentId/CCY_XTS",
               "scope": "default",
               "lusidInstrumentId": "CCY_XTS",
               "version": {
                   "effectiveFrom": "0001-01-01T00:00:00.0000000+00:00",
                   "asAtDate": "2021-11-24T16:12:00.7264710+00:00"
               },
               "name": "XTZ",
               "identifiers": {
                   "Currency": "XTZ",
                   "LusidInstrumentId": "CCY_XTS"
               },
               "properties": [],
               "state": "Active",
               "assetClass": "Unknown",
               "domCcy": "ZZZ"
           }
       },
       ...
   }

Using the LUSID web app

1. Sign in to the LUSID web app using the credentials of a LUSID administrator.

2. From the left-hand menu, select Data Management > Instruments.

3. On the Instruments dashboard, click the Create instrument button.

4. Enter a unique Instrument name and add an Instrument identifier of type Currency and a value of the ISO 4217 code, for example XTS:
    

   If the request is successful, LUSID automatically generates a LUID consisting of the prefix CCY_ and the code, so in this case CCY_XTS.

Listing the prepopulated basket of currencies

You can list the basket of currencies in the LUSID instrument master by calling the LUSID ListInstruments API with a filter of identifiers['Currency'] exists, for example:

curl -X GET "https://<your-domain>.lusid.com/api/api/instruments?filter=identifiers%5B%27Currency%27%5D%20exists"
  -H "Authorization: Bearer <your-API-access-token>"

Alternatively, sign in to the LUSID web app and enter the prefix CCY_ in the LUSID Instrument ID column of the Instruments dashboard: