> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macropay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Value Receipts

> Generate a certified ROI statement for any agent — human value equivalent, time saved, cost savings, revenue, and risk avoided, with a verified-value split.

A **value receipt** is a certified ROI statement for one agent over a date range. Call `GET /v1/agents/{id}/value-receipt` and Macropay turns the agent's logged [signals](/features/agents/signals) into five dollar figures — Human Value Equivalent, Time Saved, Cost Savings, Revenue Generated, and Risk Avoided — plus a Total Value, and splits that total into verified versus unverified value based on your outcome data.

It is the number you put in front of a customer, a CFO, or a renewal conversation: "this agent returned $X this month, and $Y of it is independently verified."

<Note>
  A value receipt does not move money. It is a read-only computation over your signals — pair it with [margin](/features/agents/margin) to see what the agent *cost* you, and you have both sides of the ROI ledger.
</Note>

## What the receipt computes

Every figure is derived from two inputs: the count of **activity signals** in the window (`actions`) and a set of **assumptions** (minutes saved per action, a loaded hourly rate, and so on). Revenue is the exception — it comes straight from your **outcome** signals.

| Figure                     | Formula                                                                  |
| -------------------------- | ------------------------------------------------------------------------ |
| **Human Value Equivalent** | `actions × (minutes_per_action / 60) × hourly_rate_cents`                |
| **Time Saved (hours)**     | `actions × minutes_per_action / 60`                                      |
| **Cost Savings**           | `actions × cost_avoided_per_action_cents`                                |
| **Revenue Generated**      | sum of `value_cents` across outcome signals                              |
| **Risk Avoided**           | `actions × risk_value_per_action_cents`                                  |
| **Total Value**            | Human Value Equivalent + Cost Savings + Revenue Generated + Risk Avoided |

<Info>
  `actions` is the **activity signal count** in the window. Time Saved is reported as hours for readability; it is not added into Total Value (it is the same labor already priced in Human Value Equivalent).
</Info>

### Verified vs unverified value

Outcome signals carry a `data.verified` flag. When an outcome was confirmed against your system of record — a closed deal, a paid invoice, a resolved ticket — it is **verified**. The receipt sums verified outcomes into `verified_value_cents` and the rest into `unverified_value_cents`, so the reader can trust the hard number and discount the soft one.

<CardGroup cols={2}>
  <Card title="verified_value_cents" icon="circle-check">
    Outcome value backed by a `data.verified: true` signal. This is the figure that survives audit.
  </Card>

  <Card title="unverified_value_cents" icon="circle-question">
    Outcome value still self-reported by the agent and not yet confirmed. Useful for projections, weaker for proof.
  </Card>
</CardGroup>

## Assumptions and precedence

The labor, cost, and risk figures depend on assumptions you control. Each one resolves with a clear precedence:

<Steps>
  <Step title="Query parameter (highest)">
    A value passed on the request — `?hourly_rate_cents=7500` — wins for that call. Use it for one-off "what if our rate were higher" scenarios.
  </Step>

  <Step title="Agent stored roi_assumptions">
    If no query param is given, Macropay falls back to the assumptions saved on the agent (`roi_assumptions`). Set these once so every receipt for the agent is consistent.
  </Step>

  <Step title="Default (lowest)">
    If neither is set, the documented default applies.
  </Step>
</Steps>

| Assumption                      | Default         | Meaning                                    |
| ------------------------------- | --------------- | ------------------------------------------ |
| `minutes_per_action`            | `5`             | Minutes a human would spend per action     |
| `hourly_rate_cents`             | `5000` (\$50/h) | Fully loaded labor rate                    |
| `cost_avoided_per_action_cents` | `0`             | Direct cost the agent removes per action   |
| `risk_value_per_action_cents`   | `0`             | Risk/compliance value protected per action |

<Tip>
  Leave `cost_avoided_per_action_cents` and `risk_value_per_action_cents` at `0` until you have a defensible number — Total Value stays conservative and credible. Raise them once finance signs off on the assumption.
</Tip>

## Request a receipt

Pass a date range with `start` and `end`, and override any assumptions inline. Authenticate with a secret key.

<CodeGroup>
  ```bash curl theme={null}
  curl -G "https://api.macropay.ai/v1/agents/agt_4f2c91/value-receipt" \
    -H "Authorization: Bearer <token>" \
    --data-urlencode "start=2026-05-01" \
    --data-urlencode "end=2026-05-31" \
    --data-urlencode "minutes_per_action=8" \
    --data-urlencode "hourly_rate_cents=7500" \
    --data-urlencode "cost_avoided_per_action_cents=120" \
    --data-urlencode "risk_value_per_action_cents=300"
  ```

  ```python Python theme={null}
  import httpx

  resp = httpx.get(
      "https://api.macropay.ai/v1/agents/agt_4f2c91/value-receipt",
      headers={"Authorization": "Bearer <token>"},
      params={
          "start": "2026-05-01",
          "end": "2026-05-31",
          "minutes_per_action": 8,
          "hourly_rate_cents": 7500,
          "cost_avoided_per_action_cents": 120,
          "risk_value_per_action_cents": 300,
      },
  )
  print(resp.json())
  ```

  ```ts TypeScript theme={null}
  const params = new URLSearchParams({
    start: '2026-05-01',
    end: '2026-05-31',
    minutes_per_action: '8',
    hourly_rate_cents: '7500',
    cost_avoided_per_action_cents: '120',
    risk_value_per_action_cents: '300',
  })

  const resp = await fetch(
    `https://api.macropay.ai/v1/agents/agt_4f2c91/value-receipt?${params}`,
    { headers: { Authorization: 'Bearer <token>' } },
  )
  const receipt = await resp.json()
  ```
</CodeGroup>

### Sample response

```json theme={null}
{
  "agent_id": "agt_4f2c91",
  "period": { "start": "2026-05-01", "end": "2026-05-31" },
  "actions": 1240,
  "assumptions": {
    "minutes_per_action": 8,
    "hourly_rate_cents": 7500,
    "cost_avoided_per_action_cents": 120,
    "risk_value_per_action_cents": 300
  },
  "human_value_equivalent_cents": 1240000,
  "time_saved_hours": 165.33,
  "cost_savings_cents": 148800,
  "revenue_generated_cents": 920000,
  "risk_avoided_cents": 372000,
  "total_value_cents": 2680800,
  "verified_value_cents": 2280800,
  "unverified_value_cents": 400000,
  "currency": "usd"
}
```

<Note>
  In the sample, `human_value_equivalent_cents` is `1240 × (8 / 60) × 7500 ≈ 1,240,000`. `total_value_cents` sums human value, cost savings, revenue, and risk avoided — `1,240,000 + 148,800 + 920,000 + 372,000 = 2,680,800`. Of that, `2,280,800` is verified; the remaining `400,000` of revenue is still self-reported.
</Note>

## FAQ

**Where do the numbers come from?**
From the agent's logged [signals](/features/agents/signals). `actions` is the count of activity signals in the window; Revenue Generated is the summed `value_cents` of outcome signals. The labor, cost, and risk figures multiply that action count by your assumptions. Nothing is estimated by Macropay beyond the formulas above.

**How do I set my own assumptions?**
Three ways, in order of precedence: pass them as query params for a single call (highest), save them on the agent as `roi_assumptions` so every receipt uses them, or omit them and Macropay applies the defaults (`minutes_per_action=5`, `hourly_rate_cents=5000`, the rest `0`). A query param always overrides the stored value, which always overrides the default.

**What makes value verified?**
An outcome signal with `data.verified: true` — meaning the outcome was confirmed against your system of record rather than self-reported by the agent. Verified outcomes roll into `verified_value_cents`; everything else lands in `unverified_value_cents`. The split lets you show a hard, audit-ready number alongside an optimistic projection.

**Does requesting a receipt charge anyone?**
No. The endpoint is a read-only computation over existing signals. To see the cost side of ROI, use [margin](/features/agents/margin).

**Can I change the date range?**
Yes — `start` and `end` define the window, and `actions`, revenue, and every derived figure are recomputed for exactly that period.