Money splitter API
Split an amount by ratios or into equal parts so the shares are whole cents and add up exactly to the amount.
POST https://api.curatedapi.com/v1/calc/money/allocate
- Version 1
- MCP tool
calc_money_allocate - Try it in the browser
Splits an amount of money between several parts, by ratios (70/30, 1:2:3, percentages) or into equal parts, so that every share is a whole number of the currency's minor unit and the shares add up to the amount exactly: no cent is lost or invented. Rounding each share on its own does not work: 10.00 split three ways rounds to 3.33 three times, which is 9.99. Here each part first gets its exact share rounded down, and the few cents left over are handed out one at a time. Use it for splitting bills, revenue shares, commission, refunds across order lines, or a discount across invoice lines. The currency sets the minor unit: cents for USD and EUR, whole yen for JPY, fils (0.001) for KWD.
Formula
units = amount × 10^decimals; share_i = ⌊units × r_i ÷ Σr⌋, then the units − Σshare_i leftover units go one each to the largest remainders (or the first parts)
- The shares always add up to the amount exactly.
- With largest_remainder (the default), the leftover units go to the parts whose exact shares lost the most when rounded down, so every share is less than one minor unit from its exact share. With in_order they go to the first parts with a ratio above 0, as in Dinero.js, even if a part's exact share was already a whole number of cents, so a share can be a full minor unit off. Both give the same result for equal parts.
- A negative amount is split as if it were positive and every share is made negative, so a refund mirrors the charge.
- To split a whole invoice line by line (for example a discount across items), use the line amounts as the ratios.
Inputs
Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).
| Input | Type | Description |
|---|---|---|
amount required |
decimal (string) | The amount to split. A negative amount (a refund) is split the same way and every share is negative. Allowed: >= -1000000000000000 and <= 1000000000000000. Unit: currency. |
currency required |
string | ISO 4217 code of the currency, such as USD, EUR, JPY or KWD. It sets the number of decimals (the minor unit): 2 for most currencies, 0 for JPY, 3 for KWD. At most 3 characters. |
ratios |
list of decimal (string) | The parts' ratios, in order. Only their proportions matter: [70, 30], [7, 3] and [0.7, 0.3] split the same way. A ratio of 0 gets nothing. Give ratios or parts. 1 to 1000 items. Each item: >= 0 and <= 1000000000000000. |
parts |
integer | Number of equal parts (instead of ratios). Allowed: >= 1 and <= 1000. |
method |
largest_remainder | in_order default largest_remainder |
Who gets the minor units left over after every share is rounded down. Options: largest_remainder: the leftover minor units go to the parts whose exact shares were cut the most, earlier parts first on a tie (Hamilton's method); in_order: the leftover minor units go to the first parts, one each, skipping parts with a ratio of 0 (the rule of Dinero.js and Martin Fowler's Money pattern) |
rounding |
half_up | half_even | half_down | up | down | ceiling | floor default half_up |
How to round the amount to the currency's minor unit first, if it has more decimals (a warning says so). Options: half_up: to nearest, ties away from zero (2.5 → 3, -2.5 → -3); half_even: to nearest, ties to even (2.5 → 2, 3.5 → 4): banker's rounding; half_down: to nearest, ties towards zero (2.5 → 2); up: away from zero (2.1 → 3, -2.1 → -3); down: towards zero, i.e. truncate (2.9 → 2); ceiling: towards +∞ (2.1 → 3, -2.1 → -2); floor: towards −∞ (2.9 → 2, -2.1 → -3) |
Result
Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.
| Result | Type | Description |
|---|---|---|
total | string | The amount that was split, in the currency's minor unit; the shares add up to exactly this. |
shares | list of string | The shares, in the order of the parts. |
leftover_units | integer | How many minor units were left after rounding every share down, and handed out one each. |
decimals | integer | The currency's number of decimals (ISO 4217 minor unit). |
allocation | list of object | Each part: ratio, exact share and share. |
Examples
100 USD split 70/20/10
curl https://api.curatedapi.com/v1/calc/money/allocate \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": "100",
"currency": "USD",
"ratios": ["70", "20", "10"]
}'
{
"calculator": "money/allocate@1",
"result": {
"total": "100.00",
"shares": [
"70.00",
"20.00",
"10.00"
],
"leftover_units": 0,
"decimals": 2,
"allocation": [
{
"part": 1,
"ratio": "70",
"exact_share": "70",
"share": "70.00",
"extra_unit": false
},
{
"part": 2,
"ratio": "20",
"exact_share": "20",
"share": "20.00",
"extra_unit": false
},
{
"part": 3,
"ratio": "10",
"exact_share": "10",
"share": "10.00",
"extra_unit": false
}
]
},
"exactness": {},
"precision": null,
"inputs": {
"amount": "100",
"currency": "USD",
"ratios": [
"70",
"20",
"10"
],
"method": "largest_remainder",
"rounding": "half_up"
},
"formula": "units = amount × 10^decimals; share_i = ⌊units × r_i ÷ Σr⌋, then the units − Σshare_i leftover units go one each to the largest remainders (or the first parts)",
"references": [
{
"title": "Dinero.js: allocate (10.03 split 50/50 gives 5.02 and 5.01; a ratio of 0 gets nothing)",
"url": "https://www.dinerojs.com/api/mutations/allocate"
},
{
"title": "Largest remainder method (Hamilton's method), with a worked example",
"url": "https://en.wikipedia.org/wiki/Quota_method"
},
{
"title": "ISO 4217 List One, current currencies and funds (SIX, the maintenance agency)",
"url": "https://www.six-group.com/en/products-services/financial-information/market-reference-data/data-standards.html"
},
{
"title": "ISO 4217 amendment 180: Bulgaria adopts the euro (1 January 2026)",
"url": "https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/amendments/dl-currency-iso-amendment-180.pdf"
}
],
"warnings": []
}
10 USD in 3 equal parts
curl https://api.curatedapi.com/v1/calc/money/allocate \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": "10",
"currency": "USD",
"parts": 3
}'
{
"calculator": "money/allocate@1",
"result": {
"total": "10.00",
"shares": [
"3.34",
"3.33",
"3.33"
],
"leftover_units": 1,
"decimals": 2,
"allocation": [
{
"part": 1,
"ratio": "1",
"exact_share": "10/3",
"share": "3.34",
"extra_unit": true
},
{
"part": 2,
"ratio": "1",
"exact_share": "10/3",
"share": "3.33",
"extra_unit": false
},
{
"part": 3,
"ratio": "1",
"exact_share": "10/3",
"share": "3.33",
"extra_unit": false
}
]
},
"exactness": {},
"precision": null,
"inputs": {
"amount": "10",
"currency": "USD",
"parts": 3,
"method": "largest_remainder",
"rounding": "half_up"
},
"formula": "units = amount × 10^decimals; share_i = ⌊units × r_i ÷ Σr⌋, then the units − Σshare_i leftover units go one each to the largest remainders (or the first parts)",
"references": [
{
"title": "Dinero.js: allocate (10.03 split 50/50 gives 5.02 and 5.01; a ratio of 0 gets nothing)",
"url": "https://www.dinerojs.com/api/mutations/allocate"
},
{
"title": "Largest remainder method (Hamilton's method), with a worked example",
"url": "https://en.wikipedia.org/wiki/Quota_method"
},
{
"title": "ISO 4217 List One, current currencies and funds (SIX, the maintenance agency)",
"url": "https://www.six-group.com/en/products-services/financial-information/market-reference-data/data-standards.html"
},
{
"title": "ISO 4217 amendment 180: Bulgaria adopts the euro (1 January 2026)",
"url": "https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/amendments/dl-currency-iso-amendment-180.pdf"
}
],
"warnings": []
}
0.05 EUR split 70/30, largest remainder
curl https://api.curatedapi.com/v1/calc/money/allocate \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": "0.05",
"currency": "EUR",
"ratios": ["70", "30"]
}'
{
"calculator": "money/allocate@1",
"result": {
"total": "0.05",
"shares": [
"0.04",
"0.01"
],
"leftover_units": 1,
"decimals": 2,
"allocation": [
{
"part": 1,
"ratio": "70",
"exact_share": "0.035",
"share": "0.04",
"extra_unit": true
},
{
"part": 2,
"ratio": "30",
"exact_share": "0.015",
"share": "0.01",
"extra_unit": false
}
]
},
"exactness": {},
"precision": null,
"inputs": {
"amount": "0.05",
"currency": "EUR",
"ratios": [
"70",
"30"
],
"method": "largest_remainder",
"rounding": "half_up"
},
"formula": "units = amount × 10^decimals; share_i = ⌊units × r_i ÷ Σr⌋, then the units − Σshare_i leftover units go one each to the largest remainders (or the first parts)",
"references": [
{
"title": "Dinero.js: allocate (10.03 split 50/50 gives 5.02 and 5.01; a ratio of 0 gets nothing)",
"url": "https://www.dinerojs.com/api/mutations/allocate"
},
{
"title": "Largest remainder method (Hamilton's method), with a worked example",
"url": "https://en.wikipedia.org/wiki/Quota_method"
},
{
"title": "ISO 4217 List One, current currencies and funds (SIX, the maintenance agency)",
"url": "https://www.six-group.com/en/products-services/financial-information/market-reference-data/data-standards.html"
},
{
"title": "ISO 4217 amendment 180: Bulgaria adopts the euro (1 January 2026)",
"url": "https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/amendments/dl-currency-iso-amendment-180.pdf"
}
],
"warnings": []
}
1000 JPY in 3 parts (yen have no decimals)
curl https://api.curatedapi.com/v1/calc/money/allocate \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": "1000",
"currency": "JPY",
"parts": 3
}'
{
"calculator": "money/allocate@1",
"result": {
"total": "1000",
"shares": [
"334",
"333",
"333"
],
"leftover_units": 1,
"decimals": 0,
"allocation": [
{
"part": 1,
"ratio": "1",
"exact_share": "1000/3",
"share": "334",
"extra_unit": true
},
{
"part": 2,
"ratio": "1",
"exact_share": "1000/3",
"share": "333",
"extra_unit": false
},
{
"part": 3,
"ratio": "1",
"exact_share": "1000/3",
"share": "333",
"extra_unit": false
}
]
},
"exactness": {},
"precision": null,
"inputs": {
"amount": "1000",
"currency": "JPY",
"parts": 3,
"method": "largest_remainder",
"rounding": "half_up"
},
"formula": "units = amount × 10^decimals; share_i = ⌊units × r_i ÷ Σr⌋, then the units − Σshare_i leftover units go one each to the largest remainders (or the first parts)",
"references": [
{
"title": "Dinero.js: allocate (10.03 split 50/50 gives 5.02 and 5.01; a ratio of 0 gets nothing)",
"url": "https://www.dinerojs.com/api/mutations/allocate"
},
{
"title": "Largest remainder method (Hamilton's method), with a worked example",
"url": "https://en.wikipedia.org/wiki/Quota_method"
},
{
"title": "ISO 4217 List One, current currencies and funds (SIX, the maintenance agency)",
"url": "https://www.six-group.com/en/products-services/financial-information/market-reference-data/data-standards.html"
},
{
"title": "ISO 4217 amendment 180: Bulgaria adopts the euro (1 January 2026)",
"url": "https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/amendments/dl-currency-iso-amendment-180.pdf"
}
],
"warnings": []
}
References
- Dinero.js: allocate (10.03 split 50/50 gives 5.02 and 5.01; a ratio of 0 gets nothing)
- Largest remainder method (Hamilton's method), with a worked example
- ISO 4217 List One, current currencies and funds (SIX, the maintenance agency)
- ISO 4217 amendment 180: Bulgaria adopts the euro (1 January 2026)
Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.
Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.