Split a money amount into parts that sum exactly to the total
Splits one signed amount into up to 500 parts by weights (or equal parts), in integer minor units of its currency, for an agent dividing a bill, a refund, a fee or a tax. Each share is rounded under the declared mode, then the leftover minor units are assigned by the declared remainder policy, so the parts always sum to the total exactly. Negative totals (refunds) are supported; zero-weight parts get zero. Fails when the total has more fraction digits than the currency, or the weights sum to zero. Does not choose a policy for you and does not apply cash rounding or tax.
What you get
A 3-way split of $100.00 that returns 33.33 x 3 loses a cent. Exact to the minor unit, for every rounding mode.
Call it
Send the JSON body below to https://agents.writerslogic.com/api/v1/allocate. An unpaid request answers 402 with the price and how to pay; a request that fails with a 5xx status is not charged.
curl -i -X POST https://agents.writerslogic.com/api/v1/allocate \
-H 'content-type: application/json' \
-d '{"total":"100.00","currency":"USD","weights":["1","1","1"]}'
Input
| Field | Type | Required | Description |
|---|---|---|---|
total | string; length 0..30 | yes | Decimal string such as "-12.50" (up to 15 integer and 12 fraction digits). JSON numbers are not accepted: they are binary floats. |
currency | string | no | ISO 4217 alphabetic code, upper case. |
exponent | integer; 0..8 | no | Override the ISO 4217 exponent; required for codes not on the list. |
weights | array<string; length 0..28>; max 500 items | no | Non-negative decimal-string weights, e.g. ["1","1","2"] or percentages. Give weights or parts. |
parts | integer; 1..500 | no | Equal split into this many parts. |
rounding | string; one of "half-up", "half-down", "half-even", "up", "down", "ceiling", "floor" | no | Rounding of each share before the residual is moved. Default half-even. half-up: ties away from zero. half-down: ties toward zero. half-even: ties to the even neighbour. up: away from zero. down: toward zero. ceiling: toward +infinity. floor: toward -infinity. |
remainder | string; one of "largest-remainder", "first", "last" | no | largest-remainder (default): one unit at a time to the part with the largest rounding claim, ties to the lowest index. first / last: the whole residual to the first / last part with positive weight. |
Example request body
{
"total": "100.00",
"currency": "USD",
"weights": [
"1",
"1",
"1"
]
}
Result
The response is { "data": ..., "_provenance": ... }. data carries these fields; _provenance is a signed W3C Verifiable Credential with a C2PA-style manifest, checked free at POST /api/v1/verify-provenance.
| Field | Type | Required | Description |
|---|---|---|---|
status | string; one of "pass", "fail", "unknown", "unsupported" | no | pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass. |
allocations | array<object> | no | |
totalMinor | integer | no | |
sumMinor | integer | no | Sum of the parts; equals totalMinor. |
residualMinor | integer | no | Minor units moved after per-share rounding (signed). |
exponent | integer | no | |
rounding | string | no | |
remainder | string | no | |
witnesses | array<object> | no | |
versions | object | no | Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile). |
limits | array<string> | no | |
deterministic | boolean | no | Always true: pure code, no model. |
Pay and connect
Available through: x402 (USDC on Base), MCP. MCP clients reach it through the money-math-kit package.
Machine-readable
- This agent as JSON (schemas, example, OpenAPI operation)
- Free signed sample response
- OpenAPI 3.1 · Catalog · Index of every agent