{"id":"minor-units","title":"ISO 4217 minor units: decimal amount to integer minor units and back","description":"Converts up to 200 money amounts between decimal strings and integer minor units (cents, yen, fils) using the ISO 4217 exponent from the SIX Group list, for an agent about to send an amount to a payment API. Returns the exponent, the integer minor amount and the canonical decimal string; JPY is 0, KWD and BHD are 3, CLF is 4. An amount with more fraction digits than the currency allows fails with the excess digits unless a rounding mode is given. Codes with no minor unit (XAU, XXX) are unsupported and codes not on the list are unknown; an exponent is never guessed. Does not convert between currencies and does not apply cash rounding (see cash-rounding).","roi":"A wrong exponent is a 100x or 1000x charge. 200 conversions per $0.005 call, from the official list.","audience":"business","package":"money-math-kit","channels":["x402","mcp"],"endpoint":{"method":"POST","url":"https://agents.writerslogic.com/api/v1/minor-units","path":"/api/v1/minor-units","contentType":"application/json"},"price":{"amount":"0.005","currency":"USDC","network":"base","perCall":true,"failedCallsCharged":false},"inputSchema":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"object","required":["currency"],"properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 alphabetic code, upper case."},"amount":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal amount to convert to minor units. Give amount or minor, or neither to look up the exponent."},"minor":{"type":"integer","minimum":-999999999999999,"maximum":999999999999999,"description":"Integer minor units to convert to a decimal string."},"exponent":{"type":"integer","minimum":0,"maximum":8,"description":"Override for currencies absent from ISO 4217 list one or without a minor unit. Wins over the list."},"rounding":{"type":"string","enum":["half-up","half-down","half-even","up","down","ceiling","floor"],"description":"Only used when amount has more fraction digits than the exponent. 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."}},"additionalProperties":false}}}},"resultSchema":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"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."},"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"status":{"type":"string","enum":["pass","fail","unknown","unsupported"]},"currency":{"type":"string"},"exponent":{"type":"integer","description":"Absent when unknown or unsupported."},"minor":{"type":"integer"},"amount":{"type":"string","description":"Canonical decimal with exactly `exponent` fraction digits."},"roundedFrom":{"type":"string","description":"The input amount, when a rounding mode changed it."}}}},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"outputSchema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"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."},"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"status":{"type":"string","enum":["pass","fail","unknown","unsupported"]},"currency":{"type":"string"},"exponent":{"type":"integer","description":"Absent when unknown or unsupported."},"minor":{"type":"integer"},"amount":{"type":"string","description":"Canonical decimal with exactly `exponent` fraction digits."},"roundedFrom":{"type":"string","description":"The input amount, when a rounding mode changed it."}}}},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]},"example":{"items":[{"currency":"JPY","amount":"1500"},{"currency":"KWD","minor":12345},{"currency":"USD","amount":"19.999"}]},"openapiOperation":{"operationId":"minor_units","summary":"ISO 4217 minor units: decimal amount to integer minor units and back","description":"Converts up to 200 money amounts between decimal strings and integer minor units (cents, yen, fils) using the ISO 4217 exponent from the SIX Group list, for an agent about to send an amount to a payment API. Returns the exponent, the integer minor amount and the canonical decimal string; JPY is 0, KWD and BHD are 3, CLF is 4. An amount with more fraction digits than the currency allows fails with the excess digits unless a rounding mode is given. Codes with no minor unit (XAU, XXX) are unsupported and codes not on the list are unknown; an exponent is never guessed. Does not convert between currencies and does not apply cash rounding (see cash-rounding).\n\nPrice: 0.005 USDC on Base (x402).","x-x402-price-usdc":"0.005","x-x402-amount":"5000","x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.005"}},"x-audience":"business","x-sample-url":"https://agents.writerslogic.com/api/v1/samples/minor-units","security":[{"x402":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"object","required":["currency"],"properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 alphabetic code, upper case."},"amount":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal amount to convert to minor units. Give amount or minor, or neither to look up the exponent."},"minor":{"type":"integer","minimum":-999999999999999,"maximum":999999999999999,"description":"Integer minor units to convert to a decimal string."},"exponent":{"type":"integer","minimum":0,"maximum":8,"description":"Override for currencies absent from ISO 4217 list one or without a minor unit. Wins over the list."},"rounding":{"type":"string","enum":["half-up","half-down","half-even","up","down","ceiling","floor"],"description":"Only used when amount has more fraction digits than the exponent. 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."}},"additionalProperties":false}}}},"example":{"items":[{"currency":"JPY","amount":"1500"},{"currency":"KWD","minor":12345},{"currency":"USD","amount":"19.999"}]}}}},"responses":{"200":{"description":"Paid result with provenance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"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."},"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"status":{"type":"string","enum":["pass","fail","unknown","unsupported"]},"currency":{"type":"string"},"exponent":{"type":"integer","description":"Absent when unknown or unsupported."},"minor":{"type":"integer"},"amount":{"type":"string","description":"Canonical decimal with exactly `exponent` fraction digits."},"roundedFrom":{"type":"string","description":"The input amount, when a rounding mode changed it."}}}},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]}}}},"400":{"description":"Invalid request (no payment consumed)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"401":{"description":"Invalid X-API-KEY","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"402":{"description":"Payment required or invalid","content":{"application/json":{"schema":{"type":"object","description":"x402 v2 PaymentRequired (also base64 in the PAYMENT-REQUIRED header)","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"code":{"type":"string"},"resource":{"type":"object"},"accepts":{"type":"array","items":{"type":"object"}},"extensions":{"type":"object"}}}}}},"502":{"description":"Upstream failure; the payment is released or not settled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}},"links":{"docs":"https://agents.writerslogic.com/docs/minor-units/","docsJson":"https://agents.writerslogic.com/docs/minor-units.json","sample":"https://agents.writerslogic.com/api/v1/samples/minor-units","openapi":"https://agents.writerslogic.com/openapi.json","catalog":"https://agents.writerslogic.com/api/v1/catalog","verifyProvenance":"https://agents.writerslogic.com/api/v1/verify-provenance","index":"https://agents.writerslogic.com/docs/index.json"}}