# Currency lookup

`currency-lookup` · version 1.0.0 · Money & pricing · free, no key needed

Look up an ISO 4217 alphabetic or numeric currency code: name, minor-unit exponent, entities, active or withdrawn.

**Use when you need to: what is the ISO 4217 code for a currency · how many decimal places does ISK have · currency numeric code 978.**

## Decide before calling

Read the [versioned contract](/v1/tools/currency-lookup/versions/1.0.0) and the supported scope below. Reuse `currency-lookup@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `currency-lookup@1.0.0` for what is the ISO 4217 code for a currency. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- what is the ISO 4217 code for a currency
- how many decimal places does ISK have
- currency numeric code 978
- is HRK still a valid currency code
- minor unit of Kuwaiti dinar
- ISO 4217 code 532
- which countries use CHF
- is XAU a currency with decimals

## Not supported

- exchange rates or currency conversion
- search by currency name or country name
- symbols, locale formatting or cash rounding rules
- currency codes not in the pinned ISO 4217 snapshot (cryptocurrencies, ISO 3166 country codes)

## Behavior

- Input is one field "code": exactly 3 ASCII letters (case-insensitive, echoed upper-case) or exactly 3 ASCII digits (numeric code, leading zeros kept). No trimming: " USD", "US", "USDX" and non-ASCII digits are invalid_input. A code over 64 UTF-8 bytes is limit_exceeded, checked before the pattern.
- Data is the pinned snapshot named by data_version (ISO 4217 List One current and List Three historic rows; datasets/currency-codes commit 7cdc784, ODC-PDDL-1.0). Nothing is looked up online; rows without an alphabetic code are ignored.
- An unknown code (ZZZ, 000) is not an error: found is false and every other field except data_version is null.
- A code with at least one current row is active: name and minor_unit come from its current row, entities are the distinct current entities sorted ascending, withdrawn is null. Codes with earlier withdrawn rows under the same code (EUR, PEN, RON, TRY) are active and the withdrawn rows are ignored.
- A code whose rows are all withdrawn is historic: name, numeric and entities come from the rows with the latest withdrawal date, withdrawn is that date normalized to YYYY-MM (HRK "2023-01", ANG "2025-03"): dates already in YYYY-MM are kept, a range ("1989 to 1990", "1990-07 to 1990-09") uses its end ("1990-12", "1990-09"), a bare year Y becomes "Y-12"; the latest row is chosen after normalization; minor_unit is null.
- minor_unit is the ISO exponent (ISK 0, JPY 0, TND 3, KWD 3, CLF 4, UYW 4) and null for historic codes and for active codes without one (XAU, XAG, XDR, XXX).
- A numeric lookup prefers the active code (532 is XCG, not ANG; 008 is ALL); with several active codes the alphabetically smallest wins; with none, the latest withdrawal wins (191 is HRK). The numeric field is a 3-digit string.
- currency-lookup only reports what the record says; the money tools additionally reject historic codes and codes without a minor unit as unsupported_input.

## Input

- `code` (string, required): min length 3; max length 3; pattern `^([A-Za-z]{3}|[0-9]{3})$`; ISO 4217 alphabetic code (3 ASCII letters, case-insensitive) or numeric code (3 ASCII digits, leading zeros kept).

## Output

- `found` (boolean, required)
- `code` (string or null, required): pattern `^[A-Z]{3}$`
- `numeric` (string or null, required): pattern `^[0-9]{3}$`; Numeric code as a 3-digit string, leading zeros kept ("008").
- `name` (string or null, required): min length 1; max length 120
- `minor_unit` (integer or null, required): min 0; max 4; Minor-unit exponent; null for historic codes and for active codes with no minor unit (XAU, XDR, XXX, ...).
- `entities` (array or null, required): max items 100
- `status` (one of "active", "historic", null, required)
- `withdrawn` (string or null, required): min length 1; max length 32; Withdrawal month as YYYY-MM, normalized from the dataset (a range such as "1989 to 1990" uses its end, "1990-12"); null unless status is historic.
- `data_version` (constant "iso4217-datasets-7cdc784-2026-07-27", required)

## Limits

- max code bytes: 64

## Example

Request input:

```json
{
  "code": "JPY"
}
```

Response:

```json
{
  "result": {
    "found": true,
    "code": "JPY",
    "numeric": "392",
    "name": "Yen",
    "minor_unit": 0,
    "entities": [
      "JAPAN"
    ],
    "status": "active",
    "withdrawn": null,
    "data_version": "iso4217-datasets-7cdc784-2026-07-27"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "currency-lookup",
  "version": "1.0.0",
  "input": {
    "code": "JPY"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/currency-lookup/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"code":"JPY"}'
```

The machine-readable contract is at [/v1/tools/currency-lookup/versions/1.0.0](/v1/tools/currency-lookup/versions/1.0.0).

### CLI

```sh
node cli.mjs run currency-lookup 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Fraction to decimal expand](/tools/fraction-to-decimal-expand): Expand an integer fraction into its exact decimal with the minimal repeating block marked, e.g. 1/7 as 0.(142857).
- [Money convert at rate](/tools/money-convert-at-rate): Convert an amount between two ISO 4217 currencies at a caller-supplied rate with explicit quote direction and rounding.
- [Decimal divide](/tools/decimal-divide): Divide two decimal strings exactly, rounding the quotient once to a fixed scale, and report the exact remainder.
- [Money minor units convert](/tools/money-minor-units-convert): Convert a decimal money amount to integer minor units (cents, fils, yen) or back, using the ISO 4217 exponent.
- [Decimal power](/tools/decimal-power): Raise a decimal string to an integer power exactly, with optional single rounding to a fixed scale.
- [Decimal sum](/tools/decimal-sum): Add up to 10,000 decimal strings exactly and report count, smallest and largest, with optional final rounding.