# Currencies

Currency directory of your Bitrix24 account, with exchange rates. The currency ID is a string code (`USD`, `EUR`, …).

Bitrix24 API: `crm.currency.*`
Scope: `crm`

## Operations

- [Create currency](./currencies/create.md) — `POST /v1/currencies`
- [List currencies](./currencies/list.md) — `GET /v1/currencies`
- [Get currency](./currencies/get.md) — `GET /v1/currencies/:id`
- [Update currency](./currencies/update.md) — `PATCH /v1/currencies/:id`
- [Delete currency](./currencies/delete.md) — `DELETE /v1/currencies/:id`
- [Search currencies](./currencies/search.md) — `POST /v1/currencies/search`
- [Currency fields](./currencies/fields.md) — `GET /v1/currencies/fields`
- [Aggregate currencies](./currencies/aggregate.md) — `POST /v1/currencies/aggregate`

## Base currency and localizations

- [Base currency](./currencies/base.md) — `GET /v1/currencies/base`
- [Currency localizations](./currencies/localizations.md) — display settings by language.

## Key fields

| Field | Description |
|------|---------|
| `id` | Three-letter Latin currency code, for example `USD`. Set at creation and used as the identifier in the path: `GET /v1/currencies/USD`. Pass it in the deal's `currencyId` field |
| `amount` | Exchange rate relative to the base currency |
| `amountCnt` | Denomination — the number of currency units the `amount` rate applies to |
| `base` | Whether this is the Bitrix24 account's base currency. Cannot be changed through the API |
| `fullName` | Currency name |
| `formatString` | Amount display template, for example `# $`. The `#` character is the placeholder for the number |
| `lang` | Display settings by language. Returned in get, create and update responses |

Full list of fields — [`GET /v1/currencies/fields`](./currencies/fields.md).

## What to know before you start

1. **The identifier is a currency code, not a number.** `id` is set at creation: three Latin letters, for example `XTS`. A code of any other form is rejected with `422 BITRIX_ERROR`.
2. **There is one base currency per Bitrix24 account.** It has `base: true`; the rates of all other currencies are relative to it. To find it, call [`GET /v1/currencies/base`](./currencies/base.md). The base currency cannot be changed through the API: `base` in an update body returns `400 READONLY_FIELD`, and deleting the base currency returns `422 BITRIX_ERROR`.
3. **The request body is flat.** On create and update, fields go at the JSON root, without a `fields` wrapper.
4. **Name and format are written for the API key's language.** `fullName`, `formatString`, `decimals`, `decPoint` and `thousandsSep` are saved to the display settings of the key's language. Values for other languages are set through [currency localizations](./currencies/localizations.md). The `lang` object cannot be sent in the body — `400 READONLY_FIELD`.
5. **There is no server-side filtering.** Any `filter` key in a list, search or aggregate request returns `400 UNSUPPORTED_FILTER`. The directory holds only a handful of records: fetch it in full and select the currencies you need on the client side.
6. **`lang` is not returned in the list.** The object with per-language settings is returned by get, create and update. List and search items do not include it.

## Typical scenario

Add a currency and use it in deals:

1. Fetch the directory: [`GET /v1/currencies`](./currencies/list.md) — make sure the code does not exist yet.
2. Create the currency: [`POST /v1/currencies`](./currencies/create.md) with `id`, `amount`, `amountCnt` and `formatString`.
3. Update the rate: [`PATCH /v1/currencies/:id`](./currencies/update.md) with a new `amount`.
4. Pass the currency code in `currencyId` when [creating a deal](/docs/entities/deals/create).

## Limits

| Limit | Value |
|-------|----------|
| Records per page | `limit`, default `50` |
| Pagination | `offset` and `meta.hasMore` |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Rate limit | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Deals](/docs/entities/deals)
- [Entity API](/docs/entity-api)
- [Batch](/docs/batch)
- [API reference](/docs/api-reference)