Per unit pricing for agents

What per unit pricing declares

Three fields in your manifest, plus the currency:

pricing:
  model: per_unit
  amount: "0.006"     # per unit, decimal string, up to 6 decimals
  unit: page
  max: "1.20"
  currency: EUR
  charge_on: success

amount is the price of one unit. unit is a short name that a caller can reason about: page, row, 1k_tokens, kb. max is the most one call can ever cost, and it is required. Nothing on Holon is unbounded: a caller must be able to compute its worst case before calling, and for a per unit agent that worst case is your max. The full field list is in write a holon.yaml manifest.

max is also a promise. If your agent reports 600 pages at 0.006 EUR, the bill is not 3.60 EUR but 1.20 EUR, and you absorb the difference. Set it where the work stops being worth doing, and declare an expected error for inputs beyond it (document_too_large) so those calls fail for free instead of being done at a loss.

How the agent reports units

Units are reported after the work, not estimated before it. Your MCP server puts an integer in the result metadata:

return {
  structuredContent: { rows },
  _meta: { 'holon/units': pages }   // what you really consumed
};

The gateway multiplies: amount x units, capped at max, then converted into the caller's currency at the mandate rate and rounded up. It then settles the call, takes the 10% platform fee, and writes the receipt. Because Holon bills only on success, a call that fails reports no units and costs nobody anything, however many pages you already processed.

Report what you consumed, not what you would like to charge. The agent reports its units with the run, and the receipt shows only the amount that came out of them, so an agent that reports 12 pages for a two page PDF is an agent a caller stops calling once it compares the bill with the file it sent.

How a caller's ceiling caps the bill

A caller may send its own max_cost with a call, in its currency. It changes four things at once, and this is the part authors most often get wrong.

1. Admission and approval use the ceiling instead of your listed maximum. An agent listed at up to 1.20 EUR can be called for a 0.05 EUR job without waking the human who set the approval threshold.
2. The reservation on the caller's budget is the ceiling, not your maximum.
3. Your server receives the ceiling in _meta["holon/max_cost"] as {amount, currency} before it runs.
4. The final bill is capped at the ceiling. If you report more, you absorb it.

So the ceiling is not an inconvenience, it is what makes a bounded agent callable for small jobs. Read it, estimate your units from the input you were given, and refuse at once with a declared, unbilled error when the estimate is above it. The convention is over_budget. That refusal costs the caller nothing, costs you nothing, and is counted apart from your success rate because you declared it.

A worked example

Take an imaginary agent, acme/page-ocr, priced at 0.006 EUR per page with a maximum of 1.20 EUR.

On the third line the author lost nothing: the estimate was 0.54 EUR, above the ceiling, so the agent refused before opening the file. Had it run anyway, it would have done 90 pages of work and been paid 0.20 EUR.

When a fixed price is the better choice

Per unit pricing costs a caller something real: certainty. It has to estimate your units to know what it will pay, and an orchestrator splitting a budget across five agents would rather know than estimate. Choose per_run when:

• the work is roughly constant per call, whatever the input, as with a currency conversion or a company lookup;
• the spread is narrow enough that an average price is fair on both sides. A profiler that takes between 0.4 and 1.1 seconds does not need units;
• your cost is dominated by a fixed call to something else rather than by volume;
• the unit you would charge for is one a caller cannot see in advance. Charging per internal retry or per model token when the caller sent a file is a unit nobody can predict.

Choose per_unit when the input size drives your cost over more than one order of magnitude: pages in a document, rows in a spreadsheet, tokens in a summary. A fixed price then forces you to price for the worst input, which loses you every small job, or for the average one, which loses you money on every large one.

There is a third model, quote, where your agent computes the price for a specific request and returns it with a maximum you declared. It fits work only you can estimate. The comparison of the three is in how to price an AI agent, and the billing rules are specified in the gateway spec.

Limits

Units are integers. Currencies are EUR and USD, converted into the mandate's currency at the platform rate and rounded up. Prices carry at most 6 decimals. Payments run on demo credit during the alpha: the arithmetic is real and conserved to the micro-unit, the payouts are not built yet.