---
title: "Currency lookup: ISO 4217 codes, names, minor units and cash rounding"
method: GET
path: "/v1/ref/currency"
tags: ["deterministic", "no-api-key", "ref", "finance", "currency", "iso-4217"]
---

# Currency lookup: ISO 4217 codes, names, minor units and cash rounding

`GET /v1/ref/currency`

## Request

- Base URL: `https://api.duoleads.com`
- URL: `https://api.duoleads.com/v1/ref/currency`
- Auth: none declared

Currency lookup by ISO 4217 alphabetic or numeric code: the official English name, minor-unit exponent, fund flag, the smallest cash denomination where it differs from the minor unit, the territories that use it, and historic codes on request. Returns the correct rounding increment for cash amounts, which is what a caller needs to render or settle a price. This route returns currency facts only and never an exchange rate.

**Output (`data`):** found, code, numeric (3-digit string per ISO 4217; null for the three historic codes XFO, XFU, XRE), name (ISO 4217 English name, e.g. Lek, Forint, Rupiah), minor_units (ISO 4217 exponent, e.g. IDR 2, HUF 2, JPY 0, KWD 3; null where ISO lists N.A.: precious metals XAU, XAG, XPT, XPD, XDR, XXX and the other X-codes; null for historic codes), cash_minor_units (equals minor_units unless CLDR gives a cash digit count, e.g. SEK 0), cash_rounding (number|null: CLDR cash rounding increment expressed in ISO minor units, e.g. 5 for CHF and CAD means 0.05, 50 for DKK, 500 for HUF meaning 5.00; null when none), is_fund (boolean: the ISO 4217 fund flag, true for BOV, CHE, CHW, CLF, COU, MXV, USN, UYI, UYW and XAD, false otherwise), territories (ISO 3166-1 alpha-2 codes, sorted, when include has territories; territory sets come from CLDR), status (current|historic), withdrawn (ISO withdrawal date as published, usually YYYY-MM, historic codes only). Historic codes come from ISO 4217 list three and are only found with include=historic, by alphabetic or numeric code (e.g. DEM 276, ZWD 716); a code that is in both lists (EUR, RON) is current. Some numeric codes were reused by several historic codes: the most recently withdrawn code is returned and the others are listed in numeric_shared_with. With country=XX the response is {found, country, currencies: [the same record for each legal-tender currency in use there per CLDR]}. Never an exchange rate.

Deterministic: identical input returns identical output, so the response is served with `Cache-Control: private, max-age=31536000, immutable` (the paying client may cache it indefinitely; shared caches must not, because the response is paid).

Sources: iso-4217 SIX list one 2026-09-17, list three 2026-01-01 (published 2026-09-17, Public data (owner decision 2026-09-29)); cldr-currency-data 48.2.2 (published 2026-09-28, Unicode-3.0). Echoed in `meta.sources`.

Price: $0.05 USDC per call (x402, Base). Route contract version 1.0.0. Docs: https://api.duoleads.com/docs#ref-currency

## Query parameters

- `code` string
- `country` string
- `include` string

## Response `200`

Paid and settled. `data` is route-specific; a route that judges its input returns 200 with `data.valid: false` for a bad value.

- object
  - `ok` unknown, required
  - `route` '/v1/ref/currency', required
  - `version` '1.0.0', required
  - `data` object, required: found, code, numeric (3-digit string per ISO 4217; null for the three historic codes XFO, XFU, XRE), name (ISO 4217 English name, e.g. Lek, Forint, Rupiah), minor_units (ISO 4217 exponent, e.g. IDR 2, HUF 2, JPY 0, KWD 3; null where ISO lists N.A.: precious metals XAU, XAG, XPT, XPD, XDR, XXX and the other X-codes; null for historic codes), cash_minor_units (equals minor_units unless CLDR gives a cash digit count, e.g. SEK 0), cash_rounding (number|null: CLDR cash rounding increment expressed in ISO minor units, e.g. 5 for CHF and CAD means 0.05, 50 for DKK, 500 for HUF meaning 5.00; null when none), is_fund (boolean: the ISO 4217 fund flag, true for BOV, CHE, CHW, CLF, COU, MXV, USN, UYI, UYW and XAD, false otherwise), territories (ISO 3166-1 alpha-2 codes, sorted, when include has territories; territory sets come from CLDR), status (current|historic), withdrawn (ISO withdrawal date as published, usually YYYY-MM, historic codes only). Historic codes come from ISO 4217 list three and are only found with include=historic, by alphabetic or numeric code (e.g. DEM 276, ZWD 716); a code that is in both lists (EUR, RON) is current. Some numeric codes were reused by several historic codes: the most recently withdrawn code is returned and the others are listed in numeric_shared_with. With country=XX the response is {found, country, currencies: [the same record for each legal-tender currency in use there per CLDR]}. Never an exchange rate.
    - `found` boolean, required
    - `code` string
    - `numeric` string, nullable
    - `name` string
    - `minor_units` integer, nullable
    - `cash_minor_units` integer, nullable
    - `cash_rounding` number, nullable
    - `is_fund` boolean
    - `status` string
    - `territories` string[]
    - `withdrawn` string
    - `numeric_shared_with` string[]
    - `country` string
    - `currencies` object[]
      - `code` string, required
      - `numeric` string, nullable, required
      - `name` string, required
      - `minor_units` integer, nullable, required
      - `cash_minor_units` integer, nullable, required
      - `cash_rounding` number, nullable, required
      - `is_fund` boolean, required
      - `status` string, required
      - `territories` string[]
  - `meta` Meta, required
    - `disclaimer` string, required: Legal short disclaimer, identical on every response.
    - `request_id` string, required: ULID.
    - `computed_at` string, date-time, required: RFC 3339 UTC with milliseconds.
    - `price_usd` string, required: Decimal string, "0.05".
    - `deterministic` boolean, required
    - `sources` object[]: Present only on routes that read a vendored dataset: the exact edition that answered.
      - `id` string, required
      - `version` string, required
      - `published` string, required
      - `attribution` string
      - `licence` string

## Other responses

- `400`: MISSING_PARAM, INVALID_PARAM or UNSUPPORTED_VALUE. Not charged: validation runs before the paywall.
- `402`: Payment required. No valid PAYMENT-SIGNATURE was supplied: read the base64 PAYMENT-REQUIRED header (or this body) for the price ($0.05 = 50000 atomic USDC on eip155:8453), sign an EIP-3009 authorization and retry. Also returned when settlement is declined (PAYMENT_FAILED). Nothing is charged on a 402.
- `404`: NOT_FOUND: unknown path. Not charged.
- `405`: METHOD_NOT_ALLOWED: only GET and HEAD are served. Not charged.
- `413`: INPUT_TOO_LARGE: a parameter exceeded its documented maximum length. Not charged.
- `500`: INTERNAL: a server bug. Not charged.

---

[API](https://skmtc.dev/duoleads/apis/duo-data-utilities-iban-isin-vat-tax-id-barcode-timezone-geo.md) · [All operations](https://skmtc.dev/duoleads/apis/duo-data-utilities-iban-isin-vat-tax-id-barcode-timezone-geo/llms.txt) · [OpenAPI document](https://skmtc.dev/duoleads/apis/duo-data-utilities-iban-isin-vat-tax-id-barcode-timezone-geo/revisions/18790d59615e?raw)