How do I create a currency?

Your LUSID domain is prepopulated with a basket of currencies, so creating a new currency should not be a common operation. However, you can do so if you need to model a currency that is not in the list, for example a cryptocurrency.

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": "XTS",
            "identifiers": {
                "Currency": "XTS",
                "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: