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

# Receipts & Analytics

> Track spend, view receipts, and compute Return on Cognitive Spend (RoCS)

Every tool execution generates a **receipt** — a transaction record with category, cost breakdown, optional value attribution, and the [audit context](/sdk/audit-context) (`memo` + `decisionContext`) the caller attached at call time. Receipts power spend tracking, RoCS computation, and supervisor-agent oversight.

## Authentication

All analytics endpoints require the `X-Agent-ID` header with your wallet address. No x402 payment needed — these are free read endpoints (the `value` tag endpoint is also free).

```bash theme={null}
-H "X-Agent-ID: 0xYourWalletAddress"
```

## Endpoints

| Method  | Path                                       | Description                                                     |
| ------- | ------------------------------------------ | --------------------------------------------------------------- |
| `GET`   | `/v1/analytics/receipts`                   | [List receipts](/api-reference/analytics/receipts) with filters |
| `GET`   | `/v1/analytics/spend/breakdown`            | [Spend by category](/api-reference/analytics/spend-breakdown)   |
| `GET`   | `/v1/analytics/rocs`                       | [Return on Cognitive Spend](/api-reference/analytics/rocs)      |
| `PATCH` | `/v1/analytics/receipts/{receiptId}/value` | [Tag receipt value](/api-reference/analytics/value)             |

## Annotating value after the fact

Business outcomes (a reply, a meeting, a closed deal) usually land days or weeks **after** the tool call that drove them. You don't need to reconcile receipts in the background to bridge that gap:

1. **Keep the id from the call.** Every tool result returns both `receipt_id` (`rcpt_…`) and `request_id`. Either one identifies the receipt.
2. **Tag value when the outcome arrives.** Call [Tag Receipt Value](/api-reference/analytics/value) with the `receipt_id` *or* the `request_id` — the API resolves a `request_id` via `Receipt.job_id` (they are the same value), so no [List Receipts](/api-reference/analytics/receipts) lookup is required.
3. **If you only kept a timestamp range**, page back to the receipt with the `since`/`until` window on [List Receipts](/api-reference/analytics/receipts) — this reaches receipts older than the 100-row page cap. The caller's `memo`/`decisionContext` are echoed into `metadata` as additional match keys.

## Receipt Categories

| Category         | Tools                              | Description              |
| ---------------- | ---------------------------------- | ------------------------ |
| `data`           | research, browser, analyze, enrich | Information gathering    |
| `verification`   | verify\_email                      | Data validation          |
| `communication`  | email, voice, sms                  | Outbound messaging       |
| `commerce`       | commerce\_search, commerce\_buy    | Purchases                |
| `infrastructure` | build                              | Website/app creation     |
| `agent_to_agent` | soul                               | Inter-agent transactions |

## Receipt Statuses

| Status     | Meaning                                         |
| ---------- | ----------------------------------------------- |
| `pending`  | Execution started, payment not yet settled      |
| `settled`  | Payment verified on-chain (has `settlement_tx`) |
| `failed`   | Execution or payment failed                     |
| `disputed` | Under review                                    |

## Return on Cognitive Spend (RoCS)

```
RoCS = total_value / total_spend
```

Only value tags with `status: "confirmed"` count toward `total_value`. Self-reported tags start as `"pending"` and must be validated by the judge service before they affect RoCS.