colinhacks · ykhedher · Jul 29, 2025
diff --git a/packages/docs/content/api.mdx b/packages/docs/content/api.mdx
@@ -227,6 +227,7 @@ To validate against some common string formats:
 
 ```ts
 z.email();
+z.currency()
 z.uuid();
 z.url();
 z.hostname();
@@ -286,6 +287,28 @@ z.email({ pattern: z.regexes.rfc5322Email });
 z.email({ pattern: z.regexes.unicodeEmail });
 ```
 
+### Currencies
+
+To validate ISO 4217 currency codes:
+
+```ts
+z.currency();
+```
+
+This method ensures the string is a valid 3-letter currency code, such as "USD", "EUR", or "TND". It checks that the input exactly matches one of the official ISO 4217 codes.
+You can find here the full list of the ISO 4217 Currencies: https://en.wikipedia.org/wiki/ISO_4217
+
+By default, this validator is case-sensitive and expects uppercase codes. Inputs like "usd" or "eur" will fail validation.
+
+```ts
+const schema = z.currency();
+
+schema.parse("USD"); // ✅
+schema.parse("TND"); // ✅
+schema.parse("eur"); // ❌ 
+schema.parse("XYZ"); // ❌ Invalid ISO 4217 currency
+```
+
 ### UUIDs
 
 To validate UUIDs:

diff --git a/packages/docs/content/packages/core.mdx b/packages/docs/content/packages/core.mdx
@@ -202,6 +202,7 @@ export type $ZodStringFormatTypes =
   | $ZodGUID
   | $ZodUUID
   | $ZodEmail
+  | $ZodCurrency
   | $ZodURL
   | $ZodEmoji
   | $ZodNanoID
@@ -316,6 +317,7 @@ export type $ZodStringFormatChecks =
   | $ZodGUID
   | $ZodUUID
   | $ZodEmail
+  | $ZodCurrency
   | $ZodURL
   | $ZodEmoji
   | $ZodNanoID

diff --git a/packages/zod/src/v4/classic/schemas.ts b/packages/zod/src/v4/classic/schemas.ts
@@ -391,6 +391,22 @@ export function email(params?: string | core.$ZodEmailParams): ZodEmail {
   return core._email(ZodEmail, params);
 }
 
+// ZodCurrency
+export interface ZodCurrency extends ZodStringFormat<"currency"> {
+  _zod: core.$ZodCurrencyInternals;
+}
+export const ZodCurrency: core.$constructor<ZodCurrency> = /*@__PURE__*/ core.$constructor(
+  "ZodCurrency",
+  (inst, def) => {
+    core.$ZodCurrency.init(inst, def);
+    ZodStringFormat.init(inst, def);
+  }
+);
+
+export function currency(params?: string | core.$ZodCurrencyParams): ZodCurrency {
+  return core._currency(ZodCurrency, params);
+}
+
 // ZodGUID
 export interface ZodGUID extends ZodStringFormat<"guid"> {
   _zod: core.$ZodGUIDInternals;

diff --git a/packages/zod/src/v4/core/api.ts b/packages/zod/src/v4/core/api.ts
@@ -102,6 +102,22 @@ export function _email<T extends schemas.$ZodEmail>(
   });
 }
 
+// Currency
+export type $ZodCurrencyParams = StringFormatParams<schemas.$ZodCurrency, "when">;
+export type $ZodCheckCurrencyParams = CheckStringFormatParams<schemas.$ZodCurrency, "when">;
+export function _currency<T extends schemas.$ZodCurrency>(
+  Class: util.SchemaClass<T>,
+  params?: string | $ZodEmailParams | $ZodCheckEmailParams
+): T {
+  return new Class({
+    type: "string",
+    format: "currency",
+    check: "string_format",
+    abort: false,
+    ...util.normalizeParams(params),
+  });
+}
+
 // GUID
 export type $ZodGUIDParams = StringFormatParams<schemas.$ZodGUID, "pattern" | "when">;
 export type $ZodCheckGUIDParams = CheckStringFormatParams<schemas.$ZodGUID, "pattern" | "when">;

diff --git a/packages/zod/src/v4/core/currencies.ts b/packages/zod/src/v4/core/currencies.ts
@@ -0,0 +1,182 @@
+// A full set of ISO 4217 currency codes used for validating international currencies, exclusing 'XXX'
+// Source: https://en.wikipedia.org/wiki/ISO_4217
+export const currencies = new Set([
+  "AED",
+  "AFN",
+  "ALL",
+  "AMD",
+  "AOA",
+  "ARS",
+  "AUD",
+  "AWG",
+  "AZN",
+  "BAM",
+  "BBD",
+  "BDT",
+  "BGN",
+  "BHD",
+  "BIF",
+  "BMD",
+  "BND",
+  "BOB",
+  "BOV",
+  "BRL",
+  "BSD",
+  "BTN",
+  "BWP",
+  "BYN",
+  "BZD",
+  "CAD",
+  "CDF",
+  "CHE",
+  "CHF",
+  "CHW",
+  "CLF",
+  "CLP",
+  "CNY",
+  "COP",
+  "COU",
+  "CRC",
+  "CUP",
+  "CVE",
+  "CZK",
+  "DJF",
+  "DKK",
+  "DOP",
+  "DZD",
+  "EGP",
+  "ERN",
+  "ETB",
+  "EUR",
+  "FJD",
+  "FKP",
+  "GBP",
+  "GEL",
+  "GHS",
+  "GIP",
+  "GMD",
+  "GNF",
+  "GTQ",
+  "GYD",
+  "HKD",
+  "HNL",
+  "HTG",
+  "HUF",
+  "IDR",
+  "ILS",
+  "INR",
+  "IQD",
+  "IRR",
+  "ISK",
+  "JMD",
+  "JOD",
+  "JPY",
+  "KES",
+  "KGS",
+  "KHR",
+  "KMF",
+  "KPW",
+  "KRW",
+  "KWD",
+  "KYD",
+  "KZT",
+  "LAK",
+  "LBP",
+  "LKR",
+  "LRD",
+  "LSL",
+  "LYD",
+  "MAD",
+  "MDL",
+  "MGA",
+  "MKD",
+  "MMK",
+  "MNT",
+  "MOP",
+  "MRU",
+  "MUR",
+  "MVR",
+  "MWK",
+  "MXN",
+  "MXV",
+  "MYR",
+  "MZN",
+  "NAD",
+  "NGN",
+  "NIO",
+  "NOK",
+  "NPR",
+  "NZD",
+  "OMR",
+  "PAB",
+  "PEN",
+  "PGK",
+  "PHP",
+  "PKR",
+  "PLN",
+  "PYG",
+  "QAR",
+  "RON",
+  "RSD",
+  "RUB",
+  "RWF",
+  "SAR",
+  "SBD",
+  "SCR",
+  "SDG",
+  "SEK",
+  "SGD",
+  "SHP",
+  "SLE",
+  "SOS",
+  "SRD",
+  "SSP",
+  "STN",
+  "SVC",
+  "SYP",
+  "SZL",
+  "THB",
+  "TJS",
+  "TMT",
+  "TND",
+  "TOP",
+  "TRY",
+  "TTD",
+  "TWD",
+  "TZS",
+  "UAH",
+  "UGX",
+  "USD",
+  "USN",
+  "UYI",
+  "UYU",
+  "UYW",
+  "UZS",
+  "VED",
+  "VES",
+  "VND",
+  "VUV",
+  "WST",
+  "XAD",
+  "XAF",
+  "XAG",
+  "XAU",
+  "XBA",
+  "XBB",
+  "XBC",
+  "XBD",
+  "XCD",
+  "XCG",
+  "XDR",
+  "XOF",
+  "XPD",
+  "XPF",
+  "XPT",
+  "XSU",
+  "XTS",
+  "XUA",
+  "YER",
+  "ZAR",
+  "ZMW",
+  "ZWG",
+]);
diff --git a/packages/zod/src/v4/core/schemas.ts b/packages/zod/src/v4/core/schemas.ts
@@ -1,6 +1,7 @@
 import type { $ZodTypeDiscriminable } from "./api.js";
 import * as checks from "./checks.js";
 import * as core from "./core.js";
+import { currencies } from "./currencies.js";
 import { Doc } from "./doc.js";
 import type * as errors from "./errors.js";
 import { safeParse, safeParseAsync } from "./parse.js";
@@ -413,6 +414,37 @@ export const $ZodEmail: core.$constructor<$ZodEmail> = /*@__PURE__*/ core.$const
   }
 );
 
+//////////////////////////////   ZodCurrency   //////////////////////////////
+
+export function isValidCurrency(currency: string): boolean {
+  return currencies.has(currency);
+}
+
+export interface $ZodCurrencyDef extends $ZodStringFormatDef<"currency"> {}
+export interface $ZodCurrencyInternals extends $ZodStringFormatInternals<"currency"> {}
+export interface $ZodCurrency extends $ZodType {
+  _zod: $ZodCurrencyInternals;
+}
+
+export const $ZodCurrency: core.$constructor<$ZodCurrency> = /*@__PURE__*/ core.$constructor(
+  "$ZodCurrency",
+  (inst, def): void => {
+    $ZodStringFormat.init(inst, def);
+
+    inst._zod.check = (payload) => {
+      if (isValidCurrency(payload.value)) return;
+
+      payload.issues.push({
+        code: "invalid_format",
+        format: "currency",
+        input: payload.value,
+        inst,
+        continue: !def.abort,
+      });
+    };
+  }
+);
+
 //////////////////////////////   ZodURL   //////////////////////////////
 
 export interface $ZodURLDef extends $ZodStringFormatDef<"url"> {

diff --git a/packages/zod/src/v4/mini/schemas.ts b/packages/zod/src/v4/mini/schemas.ts
@@ -121,6 +121,20 @@ export function email(params?: string | core.$ZodEmailParams): ZodMiniEmail {
   return core._email(ZodMiniEmail, params);
 }
 
+// ZodMiniCurrency
+export interface ZodMiniCurrency extends _ZodMiniString<core.$ZodCurrencyInternals> {}
+export const ZodMiniCurrency: core.$constructor<ZodMiniCurrency> = /*@__PURE__*/ core.$constructor(
+  "ZodMiniCurrency",
+  (inst, def) => {
+    core.$ZodCurrency.init(inst, def);
+    ZodMiniStringFormat.init(inst, def);
+  }
+);
+
+export function currency(params?: string | core.$ZodCurrencyParams): ZodMiniCurrency {
+  return core._currency(ZodMiniCurrency, params);
+}
+
 // ZodMiniGUID
 export interface ZodMiniGUID extends _ZodMiniString<core.$ZodGUIDInternals> {
   // _zod: core.$ZodGUIDInternals;

diff --git a/packages/zod/src/v4/mini/tests/string.test.ts b/packages/zod/src/v4/mini/tests/string.test.ts
@@ -86,6 +86,19 @@ test("z.email", () => {
   expect(z.safeParse(d, "bad email").error!.issues[0].message).toEqual("bad email");
 });
 
+test("z.currency", () => {
+  const a = z.currency();
+  expect(z.parse(a, "USD")).toEqual("USD");
+  expect(z.parse(a, "TND")).toEqual("TND");
+  expect(z.safeParse(a, "XXX").error!.issues[0].message).toEqual("Invalid input");
+  expect(() => z.parse(a, "eur")).toThrow();
+  expect(() => z.parse(a, "USDT")).toThrow();
+  expect(() => z.parse(a, "US")).toThrow();
+  expect(() => z.parse(a, "$€£")).toThrow();
+  expect(() => z.parse(a, "123")).toThrow();
+  expect(() => z.parse(a, 23)).toThrow();
+});
+
 test("z.url", () => {
   const a = z.url();
   // valid URLs