# Money minor units convert

`money-minor-units-convert` · version 1.0.0 · Money & pricing · free, no key needed

Convert a decimal money amount to integer minor units (cents, fils, yen) or back, using the ISO 4217 exponent.

**Use when you need to: convert dollars to cents · 12.345 KWD in minor units · yen amount to minor units.**

## Decide before calling

Read the [versioned contract](/v1/tools/money-minor-units-convert/versions/1.0.0) and the supported scope below. Reuse `money-minor-units-convert@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 `money-minor-units-convert@1.0.0` for convert dollars to cents. 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

- convert dollars to cents
- 12.345 KWD in minor units
- yen amount to minor units
- KWD three decimals to fils
- cents to dollars string
- amount in smallest currency unit for a payment API
- minor units to decimal amount
- round amount to currency precision then convert to cents

## Not supported

- exchange rate conversion between currencies
- currency symbol or locale number formatting
- cash rounding to 0.05 or other increments
- amounts given as JSON numbers or scientific notation

## Behavior

- direction to_minor: amount is a decimal string in major units and the result minor_units is amount x 10^scale as an integer string. direction from_minor: amount must be an integer string of minor units (a fraction part such as "12.0" is invalid_input, reason not_integer) and the output amount is minor_units / 10^scale with exactly scale fraction digits.
- Exactly one of currency or scale is required. currency is a 3-letter ISO 4217 code (case-insensitive, echoed upper-case) that must be active with a numeric minor unit (USD 2, JPY 0, KWD 3, CLF 4); unknown, historic (HRK, SLL, ANG) and minor-unit-less codes (XAU, XDR, XXX) are unsupported_input. scale is an integer 0..18 for non-ISO units and then currency is null.
- Excess precision is judged on value: to_minor accepts "12.500" at scale 2 but "12.505" without rounding is invalid_input with details.reason excess_precision. When rounding is given, an amount x 10^scale that is not an integer is rounded once by that mode and exact is false.
- The ten rounding modes act on the exact value: half_even, half_up (ties away from zero: -2.5 gives -3), half_down, half_ceiling (-2.5 gives -2), half_floor, up, down, ceiling, floor, and unnecessary (an inexact result is not_computable, reason rounding_necessary). rounding is validated when present in either direction but has no effect on from_minor.
- Zero has no sign: "-0" and results that round to zero give minor_units "0" and amount "0.00" (scale-formatted), never "-0".
- Decimal strings match ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$ with at most 60 digits and 40 fraction digits (invalid_input); a string over 62 characters is limit_exceeded, checked before the syntax. A JSON number is invalid_input.
- Data is the pinned ISO 4217 snapshot named by data_version; no clock, locale or network.
- Disclaimer: arithmetic calculation only; not financial, tax, legal, or investment advice.

## Input

- `amount` (string, required): min length 1; max length 62; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`; to_minor: money amount as a decimal string (major units). from_minor: an integer string of minor units (no fraction part).
- `direction` (one of "to_minor", "from_minor", required)
- `currency` (string, optional): min length 3; max length 3; pattern `^[A-Za-z]{3}$`; Active ISO 4217 alphabetic code with a minor unit (case-insensitive). Give exactly one of currency or scale.
- `scale` (integer, optional): min 0; max 18; Fraction digits for non-ISO units. Give exactly one of currency or scale.
- `rounding` (one of "half_even", "half_up", "half_down", "half_ceiling", "half_floor", "up", "down", "ceiling", "floor", "unnecessary", optional): Only used by to_minor when amount has more precision than the scale. If omitted then, invalid_input excess_precision.

## Output

- `amount` (string, required): min length 1; max length 400; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`; Amount in major units with exactly `scale` fraction digits (after rounding for to_minor).
- `minor_units` (string, required): min length 1; max length 400; pattern `^-?(0|[1-9][0-9]*)$`
- `currency` (string or null, required): pattern `^[A-Z]{3}$`
- `scale` (integer, required): min 0; max 18
- `exact` (boolean, required): false only when to_minor rounded a non-integer number of minor units.
- `data_version` (constant "iso4217-datasets-7cdc784-2026-07-27", required)

## Limits

- max decimal chars: 62
- max decimal digits: 60
- max fraction digits: 40
- max scale: 18

## Example

Request input:

```json
{
  "amount": "19.99",
  "direction": "to_minor",
  "currency": "USD"
}
```

Response:

```json
{
  "result": {
    "amount": "19.99",
    "minor_units": "1999",
    "currency": "USD",
    "scale": 2,
    "exact": true,
    "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": "money-minor-units-convert",
  "version": "1.0.0",
  "input": {
    "amount": "19.99",
    "direction": "to_minor",
    "currency": "USD"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/money-minor-units-convert/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"amount":"19.99","direction":"to_minor","currency":"USD"}'
```

The machine-readable contract is at [/v1/tools/money-minor-units-convert/versions/1.0.0](/v1/tools/money-minor-units-convert/versions/1.0.0).

### CLI

```sh
node cli.mjs run money-minor-units-convert 1.0.0 --input input.json --base-url https://computefirst.net
```

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

## Related tools

- [Money allocate](/tools/money-allocate): Split a money amount by weights or into equal parts with the largest remainder method; shares sum exactly to the total.
- [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.
- [Currency lookup](/tools/currency-lookup): Look up an ISO 4217 alphabetic or numeric currency code: name, minor-unit exponent, entities, active or withdrawn.
- [Decimal divide](/tools/decimal-divide): Divide two decimal strings exactly, rounding the quotient once to a fixed scale, and report the exact remainder.
- [Vat net gross convert](/tools/vat-net-gross-convert): Convert a net or gross amount at a VAT rate into a net, VAT and gross triple that adds up exactly at currency precision.
- [Decimal multiply](/tools/decimal-multiply): Multiply two decimal strings exactly, optionally rounding the product once to a fixed scale with a chosen mode.