Usage Bill Reconstructor

Recomputes a usage-based bill from a customer-supplied tariff (graduated per-meter tiers, optional included allowances, optional fixed charges) and aggregated metered usage, using exact decimal arithmetic. Does not fetch or embed any vendor pricing; it only applies the rules the caller provides, and checks the result against an optional supplied invoice total.

Pricing

0.05 per analysis

Requires x402 capable MCP client with wallet for payment settlement.

Input Schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "currency",
    "minor_unit_digits",
    "meters"
  ],
  "properties": {
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{1,10}$"
    },
    "minor_unit_digits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 6
    },
    "meters": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "quantity",
          "tiers"
        ],
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "quantity": {
            "type": "string",
            "description": "nonnegative decimal, <=6 fractional digits"
          },
          "included_quantity": {
            "type": "string",
            "description": "nonnegative decimal, <=6 fractional digits"
          },
          "tiers": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "up_to",
                "unit_price"
              ],
              "properties": {
                "up_to": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "nonnegative decimal or null for the final unlimited tier"
                },
                "unit_price": {
                  "type": "string",
                  "description": "nonnegative decimal, <=9 fractional digits"
                }
              }
            }
          }
        }
      }
    },
    "fixed_charges": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "amount"
        ],
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "amount": {
            "type": "string",
            "description": "nonnegative decimal, <=9 fractional digits"
          }
        }
      }
    },
    "invoice_total": {
      "type": "string",
      "description": "nonnegative decimal, at most minor_unit_digits fractional digits; never rounded"
    }
  }
}

Example Input

{
  "currency": "USD",
  "minor_unit_digits": 2,
  "meters": [
    {
      "id": "requests",
      "quantity": "1250000",
      "included_quantity": "1000000",
      "tiers": [
        {
          "up_to": "100000",
          "unit_price": "0.0000005"
        },
        {
          "up_to": "500000",
          "unit_price": "0.0000003"
        },
        {
          "up_to": null,
          "unit_price": "0.0000002"
        }
      ]
    },
    {
      "id": "storage_gb_hours",
      "quantity": "500.5",
      "tiers": [
        {
          "up_to": null,
          "unit_price": "0.02"
        }
      ]
    }
  ],
  "fixed_charges": [
    {
      "id": "platform_fee",
      "amount": "5.00"
    },
    {
      "id": "support_plan",
      "amount": "12.345"
    }
  ],
  "invoice_total": "27.46"
}

Example Output

{
  "ok": true,
  "currency": "USD",
  "minor_unit_digits": 2,
  "meters": [
    {
      "id": "requests",
      "usage_quantity": "1250000",
      "included_quantity": "1000000",
      "billable_quantity": "250000",
      "tiers": [
        {
          "quantity": "100000",
          "unit_price": "0.0000005",
          "unrounded_cost": "0.05"
        },
        {
          "quantity": "150000",
          "unit_price": "0.0000003",
          "unrounded_cost": "0.045"
        },
        {
          "quantity": "0",
          "unit_price": "0.0000002",
          "unrounded_cost": "0"
        }
      ],
      "total_minor": "10"
    },
    {
      "id": "storage_gb_hours",
      "usage_quantity": "500.5",
      "included_quantity": "0",
      "billable_quantity": "500.5",
      "tiers": [
        {
          "quantity": "500.5",
          "unit_price": "0.02",
          "unrounded_cost": "10.01"
        }
      ],
      "total_minor": "1001"
    }
  ],
  "fixed_charges": [
    {
      "id": "platform_fee",
      "total_minor": "500"
    },
    {
      "id": "support_plan",
      "total_minor": "1235"
    }
  ],
  "total_minor": "2746",
  "invoice_total_minor": "2746",
  "difference_minor": "0",
  "matches_invoice": true
}

Limitations

• Pure computation only: never fetches vendor data and asserts nothing about any real vendor's actual pricing.
• Trusts the tariff and usage figures supplied by the caller; does not verify them against any account or provider.
• Excludes tax, foreign-exchange conversion, and calendar-based proration unless the caller encodes them as fixed_charges.
• Distinguishes "calculation under supplied rules" from "account bill verification": a match against invoice_total only means the supplied rules reproduce that total, not that the rules or invoice are correct.
• Bounded input: 128KiB serialized, 100 meters, 20 tiers per meter, 100 fixed charges, 15 integer digits per numeric field.
• All monetary and quantity fields must be plain nonnegative decimal strings (no exponents, no negative values); precision beyond the contract is rejected, never silently rounded.
• Results at most 96 KiB; retry identical input and authorization within 24 hours to recover a purchase.

Connect via MCP

Add to your MCP client configuration:

{
  "mcpServers": {
    "usage-bill-reconstructor": {
      "type": "http",
      "url": "https://mcp-factory.bowling-anthony.workers.dev/usage-bill-reconstructor/mcp"
    }
  }
}