{"id":"metered-price","title":"Tiered usage pricing: graduated or volume tiers, included quantity, package units, minimum charge","description":"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.","roi":"Tier boundaries are where invoices go wrong: 100, 101 and 1000 units priced exactly, with a per-tier breakdown.","audience":"business","package":"money-math-kit","channels":["x402","mcp"],"endpoint":{"method":"POST","url":"https://agents.writerslogic.com/api/v1/metered-price","path":"/api/v1/metered-price","contentType":"application/json"},"price":{"amount":"0.005","currency":"USDC","network":"base","perCall":true,"failedCallsCharged":false},"inputSchema":{"type":"object","additionalProperties":false,"required":["quantity","mode","tiers"],"properties":{"quantity":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal string such as \"-12.50\" (up to 15 integer and 12 fraction digits). JSON numbers are not accepted: they are binary floats."},"mode":{"type":"string","enum":["graduated","volume"]},"tiers":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["unitPrice"],"properties":{"upTo":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Inclusive upper bound in billing units. Omit on the last tier for unlimited."},"unitPrice":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Price per billing unit in major units; sub-cent precision allowed."},"flatFee":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Fee in major units charged with this tier."}},"additionalProperties":false}},"included":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Free quantity subtracted before packaging and tiers (never below zero)."},"per":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Units per billing package (default 1). Tiers are expressed in packages."},"packageRounding":{"type":"string","enum":["up","down","none"],"description":"How a partial package is billed when per > 1. Default up."},"minimum":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Minimum charge in major units, applied after the tiers."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 alphabetic code, upper case."},"exponent":{"type":"integer","minimum":0,"maximum":8},"rounding":{"type":"string","enum":["half-up","half-down","half-even","up","down","ceiling","floor"],"description":"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."}}},"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."},"charge":{"type":"string","description":"Final charge at the currency's precision."},"chargeMinor":{"type":"integer"},"exponent":{"type":"integer"},"billableUnits":{"type":"string","description":"Billing units after included quantity and packaging."},"breakdown":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"integer"},"units":{"type":"string"},"unitPrice":{"type":"string"},"flatFee":{"type":"string"},"subtotal":{"type":"string","description":"Unrounded; exact unless packageRounding is none and per does not divide the quantity, then rounded to 90 significant digits for display only (the charge is exact)."}}}},"unroundedTotal":{"type":"string"},"minimumApplied":{"type":"boolean"},"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."},"charge":{"type":"string","description":"Final charge at the currency's precision."},"chargeMinor":{"type":"integer"},"exponent":{"type":"integer"},"billableUnits":{"type":"string","description":"Billing units after included quantity and packaging."},"breakdown":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"integer"},"units":{"type":"string"},"unitPrice":{"type":"string"},"flatFee":{"type":"string"},"subtotal":{"type":"string","description":"Unrounded; exact unless packageRounding is none and per does not divide the quantity, then rounded to 90 significant digits for display only (the charge is exact)."}}}},"unroundedTotal":{"type":"string"},"minimumApplied":{"type":"boolean"},"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":{"quantity":"250","mode":"graduated","tiers":[{"upTo":"100","unitPrice":"0.10"},{"upTo":"1000","unitPrice":"0.08"},{"unitPrice":"0.05"}],"currency":"USD"},"openapiOperation":{"operationId":"metered_price","summary":"Tiered usage pricing: graduated or volume tiers, included quantity, package units, minimum charge","description":"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.\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/metered-price","security":[{"x402":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["quantity","mode","tiers"],"properties":{"quantity":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal string such as \"-12.50\" (up to 15 integer and 12 fraction digits). JSON numbers are not accepted: they are binary floats."},"mode":{"type":"string","enum":["graduated","volume"]},"tiers":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["unitPrice"],"properties":{"upTo":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Inclusive upper bound in billing units. Omit on the last tier for unlimited."},"unitPrice":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Price per billing unit in major units; sub-cent precision allowed."},"flatFee":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Fee in major units charged with this tier."}},"additionalProperties":false}},"included":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Free quantity subtracted before packaging and tiers (never below zero)."},"per":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Units per billing package (default 1). Tiers are expressed in packages."},"packageRounding":{"type":"string","enum":["up","down","none"],"description":"How a partial package is billed when per > 1. Default up."},"minimum":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Minimum charge in major units, applied after the tiers."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 alphabetic code, upper case."},"exponent":{"type":"integer","minimum":0,"maximum":8},"rounding":{"type":"string","enum":["half-up","half-down","half-even","up","down","ceiling","floor"],"description":"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":{"quantity":"250","mode":"graduated","tiers":[{"upTo":"100","unitPrice":"0.10"},{"upTo":"1000","unitPrice":"0.08"},{"unitPrice":"0.05"}],"currency":"USD"}}}},"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."},"charge":{"type":"string","description":"Final charge at the currency's precision."},"chargeMinor":{"type":"integer"},"exponent":{"type":"integer"},"billableUnits":{"type":"string","description":"Billing units after included quantity and packaging."},"breakdown":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"integer"},"units":{"type":"string"},"unitPrice":{"type":"string"},"flatFee":{"type":"string"},"subtotal":{"type":"string","description":"Unrounded; exact unless packageRounding is none and per does not divide the quantity, then rounded to 90 significant digits for display only (the charge is exact)."}}}},"unroundedTotal":{"type":"string"},"minimumApplied":{"type":"boolean"},"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/metered-price/","docsJson":"https://agents.writerslogic.com/docs/metered-price.json","sample":"https://agents.writerslogic.com/api/v1/samples/metered-price","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"}}