> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crypto.westminister.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Fiat Currencies

> Shared fiat_currencies catalog for KES, USD, EUR, and other ISO 4217 codes

EmaalCoin maintains a single **`fiat_currencies`** catalog for every product that accepts a fiat leg. OTC deposits and withdrawals, pricing resolve, marketplace orders, remittance, and country defaults all validate against **active** rows in this table.

## Discover Active Codes

Authenticated clients list active currencies for pickers:

```http theme={null}
GET /api/v1/auth/fiat-currencies
Authorization: Bearer <access_token>
```

**Example response**

```json theme={null}
{
  "fiat_currencies": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "iso_code": "KES",
      "display_name": "Kenyan Shilling",
      "fraction_digits": 2,
      "sort_order": 70
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "iso_code": "USD",
      "display_name": "US Dollar",
      "fraction_digits": 2,
      "sort_order": 10
    }
  ]
}
```

Seeded codes include **USD**, **GBP**, **EUR**, **ETB**, **UGX**, **TZS**, and **KES**.

## Admin Catalog Management

| Method   | Path                                 | Purpose                                                          |
| -------- | ------------------------------------ | ---------------------------------------------------------------- |
| `GET`    | `/api/v1/auth/fiat-currencies/admin` | List all rows including inactive                                 |
| `GET`    | `/api/v1/auth/fiat-currencies/{id}`  | Fetch one row by UUID                                            |
| `POST`   | `/api/v1/auth/fiat-currencies`       | Create a currency                                                |
| `PATCH`  | `/api/v1/auth/fiat-currencies/{id}`  | Update display name, fraction digits, sort order, or `is_active` |
| `DELETE` | `/api/v1/auth/fiat-currencies/{id}`  | Hard-delete when not referenced                                  |

Admin-only routes require `role: admin`.

### Create

Send nested `{ "fiat_currency": { ... } }` or flat JSON at the root.

```json theme={null}
{
  "fiat_currency": {
    "iso_code": "NGN",
    "display_name": "Nigerian Naira",
    "fraction_digits": 2,
    "sort_order": 80,
    "is_active": true
  }
}
```

`iso_code` is normalized to uppercase and must be a three-letter ISO 4217 code. `iso_code` cannot be changed after create.

### Update

Patch at least one field. To retire a currency without breaking history, set **`is_active`** to **`false`** instead of deleting.

```json theme={null}
{
  "fiat_currency": {
    "is_active": false
  }
}
```

### Delete

**DELETE** removes the row permanently. The API returns **409** when another table references the code (for example **`countries.default_fiat_currency`**). Use **PATCH** with **`is_active: false`** in that case.

## Validation in Other APIs

Any request field named **`fiat_currency`** must match an **active** `iso_code` in **`fiat_currencies`**. Inactive or unknown codes are rejected before business logic runs. Load the catalog with **GET /api/v1/auth/fiat-currencies** before building OTC, pricing, or order forms.