Tiered usage pricing: graduated or volume tiers, included quantity, package units, minimum charge

$0.005 USDC per call · Business, finance and compliance · POST /api/v1/metered-price · Id metered-price

Prices a usage quantity against up to 50 tiers, graduated (each tier prices only its own units) or volume (the tier holding the whole quantity prices all of it), for an agent checking a usage bill or quoting a plan. Order of operations: subtract the included quantity, convert to billing packages (per N units, rounded up, down or not at all), price the tiers, add flat fees, apply the minimum charge, round once to the currency's minor unit. Tier `upTo` bounds are inclusive and strictly ascending; only the last tier may omit it. Unit prices may carry sub-cent precision. A quantity above the last bounded tier fails. Flat fees apply when a tier holds units (graduated) or is the matching tier (volume) and quantity is above zero. Does not meter usage or apply tax.

What you get

Tier boundaries are where invoices go wrong: 100, 101 and 1000 units priced exactly, with a per-tier breakdown.

Call it

Send the JSON body below to https://agents.writerslogic.com/api/v1/metered-price. 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/metered-price \
  -H 'content-type: application/json' \
  -d '{"quantity":"250","mode":"graduated","tiers":[{"upTo":"100","unitPrice":"0.10"},{"upTo":"1000","unitPrice":"0.08"},{"unitPrice":"0.05"}],"currency":"USD"}'

Input

Field	Type	Required	Description
`quantity`	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.
`mode`	string; one of "graduated", "volume"	yes
`tiers`	array<object>; max 50 items	yes
`included`	string; length 0..30	no	Free quantity subtracted before packaging and tiers (never below zero).
`per`	string; length 0..30	no	Units per billing package (default 1). Tiers are expressed in packages.
`packageRounding`	string; one of "up", "down", "none"	no	How a partial package is billed when per > 1. Default up.
`minimum`	string; length 0..30	no	Minimum charge in major units, applied after the tiers.
`currency`	string	no	ISO 4217 alphabetic code, upper case.
`exponent`	integer; 0..8	no
`rounding`	string; one of "half-up", "half-down", "half-even", "up", "down", "ceiling", "floor"	no	Final rounding to the minor unit. Default half-up. 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.

Example request body

{
  "quantity": "250",
  "mode": "graduated",
  "tiers": [
    {
      "upTo": "100",
      "unitPrice": "0.10"
    },
    {
      "upTo": "1000",
      "unitPrice": "0.08"
    },
    {
      "unitPrice": "0.05"
    }
  ],
  "currency": "USD"
}

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.
`charge`	string	no	Final charge at the currency's precision.
`chargeMinor`	integer	no
`exponent`	integer	no
`billableUnits`	string	no	Billing units after included quantity and packaging.
`breakdown`	array<object>	no
`unroundedTotal`	string	no
`minimumApplied`	boolean	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