---
title: "How do I create a currency?"
slug: "how-do-i-create-a-currency"
tags: ["currency", "instrument"]
updated: 2025-02-27T10:04:50Z
published: 2025-02-27T10:04:50Z
canonical: "support.lusid.com/how-do-i-create-a-currency"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.lusid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How do I create a currency?

Your LUSID domain is [prepopulated with a basket of currencies](/v1/docs/how-do-i-create-a-currency#listing-the-prepopulated-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](https://en.wikipedia.org/wiki/ISO_4217) (for example GBP) and an automatically-generated [LUSID Unique ID](/v1/docs/what-is-a-lusid-instrument-id-or-luid) (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](/v1/docs/what-is-the-unknown-instrument-or-luid-zzzzzzzz#a-note-on-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](https://en.wikipedia.org/wiki/ISO_4217#X_currencies).

> **Note**: To see how to model a non-currency instrument such as an Equity, Bond, Future, Swap and more, start with [this article](/v1/docs/how-do-i-master-an-instrument).

## Using the LUSID REST API

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

1. [Obtain an API access token](/v1/docs/how-do-i-obtain-and-use-a-short-lived-api-access-token-from-okta).
2. Call the LUSID [UpsertInstruments](https://www.lusid.com/docs/api#operation/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](/v1/docs/understanding-instrument-scopes). 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):

```json
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`:

```json
{
    "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](https://www.lusid.com/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`: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/1b5cb329-0c6b-4c34-9557-0146a63be081.png?sv=2026-02-06&spr=https&st=2026-11-04T01%3A47%3A09Z&se=2026-11-04T02%3A47%3A09Z&sr=c&sp=r&sig=GRzbgeRzuOpIGahgQcYQMpSB8vKsO41HrVS%2BAZams2E%3D)

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](https://www.lusid.com/docs/api#operation/ListInstruments) API with a filter of `identifiers['Currency'] exists`, for example:

```json
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](https://www.lusid.com/app/home) and enter the prefix `CCY_` in the **LUSID Instrument ID** column of the **Instruments** dashboard:

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/1e0500e4-80f2-4ba6-a5c9-3bafa98a660a.png?sv=2026-02-06&spr=https&st=2026-11-04T01%3A47%3A09Z&se=2026-11-04T02%3A47%3A09Z&sr=c&sp=r&sig=GRzbgeRzuOpIGahgQcYQMpSB8vKsO41HrVS%2BAZams2E%3D)