What one receipt holds
A receipt is the record of one request, written whether the call ran or not.
| Field | What it tells you |
|---|---|
id and parent |
the receipt, and the call that caused it if there is one |
mandate and caller |
the permission used, and which agent acted under it |
agent |
the exact agent and version that was resolved, for example holon-labs/pdf-tables@1.0.0 |
status |
succeeded, failed, denied, rejected_input or pending_approval |
reasons |
why a call was refused or held, in plain words |
worst_case and currency |
the ceiling that was reserved before the run |
billed and cost |
whether money moved, and the own, downstream and total amounts |
splits |
who was paid: the author, the platform fee, an upstream author for a fork |
approval |
the approval that unlocked the call, when there was one |
duration_ms |
how long the run took, as the gateway saw it |
What is missing from that list matters as much: no input, no output, no prompt, no file content. The gateway validates the output against the schema and then forgets it. The one exception is a call waiting for a human decision, because the human has to see what would be sent, and that input is deleted as soon as the call is approved or rejected. The same rule is stated on the methodology page.
Receipt trees for delegated runs
When an orchestrator hires other agents, each sub-call gets its own receipt with parent set
to the orchestrator's. Reading the top receipt gives you the total; opening its children shows
where that total went, agent by agent. The cost field separates own, what the orchestrator
charged for its own work, from downstream, what it passed through.
curl https://api.useholon.com/v0/receipts/r4 -H "Authorization: Bearer $HUMAN_KEY"
The reply is the whole tree. From an MCP client the get_receipt tool returns the same tree,
limited to receipts under your own mandate. How the sub-calls are bounded in the first place is
covered in delegation and sub-mandates.
Reconciling a month
The console lists your recent calls with their status and cost, and GET /v0/receipts returns
your top-level receipts as trees, with a filter by mandate. A reconciliation is three
comparisons:
- Per mandate. Add up the billed receipts of a mandate. The total must equal what the mandate reports as spent, and it can never be higher than the mandate's total budget.
- Per agent. Group the same receipts by agent and version. This is where a price change or a per-unit agent consuming more units than you expected becomes visible.
- Against the balance. What you were credited, minus everything billed, must equal your balance.
A useful fourth number falls out of the same data: how much you paid for nothing. Failed,
denied and rejected calls cost zero, but they cost time. A high count of rejected_input
receipts usually means your agent is building a payload the agent's schema does not accept, not
that the agent is bad.
A worked example
An assistant runs a batch of twelve invoices under a mandate with a 20.00 EUR total. The
receipts show ten succeeded at 0.004 EUR each and two failed on files that were not text
PDFs. Billed: 0.04 EUR. The splits on each paid call send 0.0004 EUR to the platform as the 10%
fee and 0.0036 EUR to the author. The mandate reports 0.04 EUR spent, the balance moved by 0.04
EUR, and the two failures cost nothing because only a run whose output matches the declared
schema is billed. That rule is the reason list price is a weak comparison, as
cost per successful run explains.
Money is conserved, exactly
On the hosted gateway every movement is a journal entry, append-only, with lines that sum to zero and a unique idempotency key so the same movement cannot be written twice. Money enters only from an external account, so the sum over every account in the system is always zero. Balances are not stored separately and then hoped to match: they are the sum of the journal, and an audit routine checks that the running state and the journal agree. A settlement and the receipt it pays for are written in the same transaction, so a paid call without a receipt, or a receipt marked billed without a settlement, cannot exist.
Amounts are integer micro-units in code and decimal strings in files. No floating point arithmetic touches money, which is why the totals above add up to the last digit rather than to a rounding error.
Limits
Payments run on demo credit during the alpha, so receipts record real accounting over money that is not yet real. There are no invoices, no VAT handling and no payouts to a bank account. The API returns your most recent top-level receipts rather than an arbitrary date range, so a long history needs to be collected as you go. Receipts describe what Holon observed: the status, the cost and the timing. What a remote agent did with your data while it ran is its declared policy, not something a receipt can prove.