Fiat Currencies

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:

GET /api/v1/auth/fiat-currencies
Authorization: Bearer <access_token>

Example response

{
  "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.

{
  "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.

{
  "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.

Getting Started

Guides

Discover Active Codes

Admin Catalog Management

Create

Update

Delete

Validation in Other APIs

​Discover Active Codes

​Admin Catalog Management

​Create

​Update

​Delete

​Validation in Other APIs

Discover Active Codes

Admin Catalog Management

Create

Update

Delete

Validation in Other APIs