# Money allocate

`money-allocate` · version 1.0.0 · Money & pricing · free, no key needed

Split a money amount by weights or into equal parts with the largest remainder method; shares sum exactly to the total.

**Use when you need to: split 100 dollars three ways · divide amount by weights without losing a cent · allocate 1003 cents 50/50.**

## Decide before calling

Read the [versioned contract](/v1/tools/money-allocate/versions/1.0.0) and the supported scope below. Reuse `money-allocate@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-allocate@1.0.0` for split 100 dollars three ways. 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

- split 100 dollars three ways
- divide amount by weights without losing a cent
- allocate 1003 cents 50/50
- split bill into equal payments remainder to first
- largest remainder method money
- distribute payment across invoices by percentage
- installments that sum to the total
- split cents evenly

## Not supported

- dividing a number without a currency precision or scale
- interest, fees or amortization schedules for installments
- tax or VAT splitting
- seat apportionment with quotas other than largest remainder

## Behavior

- Give amount, exactly one of currency (active ISO 4217 code with a minor unit) or scale (0..18), and exactly one of weights (1..1000 non-negative decimal strings, not all zero) or parts (integer 1..1000, an equal split). remainder_to is "first" (default) or "last".
- amount must be a multiple of the minor unit by value ("100" and "100.000" are fine at USD, "0.005" is invalid_input with reason excess_precision). Weights carry any precision up to 60 digits and 40 fraction digits.
- Algorithm, exact and on absolute minor units: M = |amount| x 10^scale; each share is floor(M x w_i / W) with W the sum of weights; the leftover minor units go one each to the items with the largest fractional remainders. Ties between equal remainders go to the lower index when remainder_to is "first" and to the higher index when "last". A zero-weight item never receives a leftover.
- The sign is applied afterwards to every share, so a negative amount gives the negatives of the shares of its absolute value. Zero is written "0.00", never "-0.00". The sum of allocations equals total exactly; no rounding mode exists.
- Outputs have exactly scale fraction digits in input order. Examples: 100.00 USD in 3 parts gives 33.34, 33.33, 33.33 (remainder_to "last": 33.33, 33.33, 33.34); 0.05 by weights 70 and 30 gives 0.04 and 0.01.
- More than 1000 weights or a parts value above 1000 is limit_exceeded (checked before the items); a decimal string over 62 characters is limit_exceeded (before syntax). Empty weights, all-zero weights (reason weights_all_zero), negative weights, both or neither of weights and parts, and parts below 1 or non-integer are 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]+)?$`; Amount to split, at the currency precision (value-based; 12.500 is fine at scale 2).
- `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.
- `weights` (array of string, optional): min items 1; max items 1000; each min length 1; each max length 62; each pattern `^(0|[1-9][0-9]*)(\.[0-9]+)?$`; Give exactly one of weights or parts.
- `parts` (integer, optional): min 1; max 1000; Equal split into this many parts.
- `remainder_to` (one of "first", "last", optional): default `"first"`; Order in which tied remainders receive the leftover minor units.

## Output

- `allocations` (array of string, required): min items 1; max items 1000; each min length 1; each max length 400; each pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `total` (string, required): min length 1; max length 400; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`; The amount at fixed scale; equals the sum of allocations exactly.
- `currency` (string or null, required): pattern `^[A-Z]{3}$`
- `scale` (integer, required): min 0; max 18
- `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
- max weights: 1000
- max parts: 1000

## Example

Request input:

```json
{
  "amount": "100.00",
  "currency": "USD",
  "parts": 3
}
```

Response:

```json
{
  "result": {
    "allocations": [
      "33.34",
      "33.33",
      "33.33"
    ],
    "total": "100.00",
    "currency": "USD",
    "scale": 2,
    "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-allocate",
  "version": "1.0.0",
  "input": {
    "amount": "100.00",
    "currency": "USD",
    "parts": 3
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/money-allocate/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"amount":"100.00","currency":"USD","parts":3}'
```

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

### CLI

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

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

## Related tools

- [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.
- [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.
- [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.
- [Discount stack apply](/tools/discount-stack-apply): Apply an ordered stack of percent and fixed-amount discounts to a price, rounding each step or only at the end.
- [Decimal multiply](/tools/decimal-multiply): Multiply two decimal strings exactly, optionally rounding the product once to a fixed scale with a chosen mode.