> For the complete documentation index, see [llms.txt](https://docs.somnia.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.somnia.network/agents/invoking-agents/receipts.md). # Receipts Every agent invocation produces an **execution receipt** — a per-validator log of what happened during execution. Receipts provide transparency and auditability for agent operations. {% hint style="info" %} **Note:** Receipts are currently stored on centralized infrastructure (a public Google Cloud Storage bucket). We plan to migrate to decentralized storage in the future to make receipts tamper-proof and permanently available. {% endhint %} ## Understanding Receipts ### Consensus vs. Receipts It's important to understand the distinction: * **Result**: The final output of the agent is what validators reach **consensus** on. All nodes must agree on this value for it to be accepted. * **Receipt**: The execution steps are **subjective** and may vary slightly between nodes. Receipts are for transparency and debugging, not consensus. This means: * You can trust the **result** completely — it's been verified by multiple validators. * Each receipt shows **what one node did** to compute that result. * Different nodes may have different receipts (timing, network paths) but still agree on the final result. ### One request → one receipt per subcommittee member A single agent request is processed by every member of its subcommittee (default size **3**, configurable via `createAdvancedRequest`). Each member produces its own receipt, so a default request yields **3 receipts**. The receipt service exposes them as a manifest keyed by `(contractAddress, requestId)`. ## Viewing Receipts in the UI ### From the Web App 1. Visit the Agent Explorer for the network you used — [https://agents.somnia.network](https://agents.somnia.network/) (mainnet) or [https://agents.testnet.somnia.network](https://agents.testnet.somnia.network/) (testnet). 2. Invoke an agent. 3. After execution completes, click **View Receipt**. 4. Explore each step of the execution. The UI displays receipts in a readable format, showing: * Per-validator execution timelines * External calls made (URLs, responses) * Data transformations * Timing information ### From Monitoring Browse recent invocations or search by request ID at: ``` https://agents.somnia.network/monitoring ``` Useful when you don't have the receipt URL handy or want to scan recent activity. ### From Receipt URL If you already know the request ID, navigate directly to: ``` https://agents.somnia.network/receipts/ ``` Replace `` with the numeric request ID returned by `createRequest`. ## Fetching Receipts Programmatically Fetching is a **two-step flow**: 1. Hit the receipts service with the platform `contractAddress` and `requestId` — you get back a manifest of public Google Cloud Storage URLs. 2. Fetch each URL directly to read the per-validator receipt JSON. | Network | Receipts service base URL | Platform contract | | ------- | --------------------------------------------- | -------------------------------------------- | | Mainnet | `https://receipts.mainnet.agents.somnia.host` | `0x5E5205CF39E766118C01636bED000A54D93163E6` | | Testnet | `https://receipts.testnet.agents.somnia.host` | `0x037Bb9C718F3f7fe5eCBDB0b600D607b52706776` | ```javascript const baseUrl = 'https://receipts.testnet.agents.somnia.host'; const platform = '0x037Bb9C718F3f7fe5eCBDB0b600D607b52706776'; const requestId = ''; // returned by platform.createRequest // Step 1 — manifest const manifest = await (await fetch( `${baseUrl}/agent-receipts?contractAddress=${platform}&requestId=${requestId}` )).json(); // → { contractAddress, requestId, receipts: [, ...], count } // Step 2 — per-validator receipts const receipts = await Promise.all( manifest.receipts.map(url => fetch(url).then(r => r.json())) ); console.log(`${receipts.length} validator receipts for request ${requestId}`); ``` Both query parameters are required. Omitting `contractAddress` returns: ```json HTTP 400 { "error": "Missing contractAddress query parameter" } ``` ### Quick triage with `type=minimal` For lightweight triage — "did this resolve, did the subcommittee agree, what was the error?" — the receipts service also exposes a `type=minimal` mode that returns all per-validator receipt JSON **inline in a single call**, with no second-step GCS fetch needed. ``` GET {baseUrl}/agent-receipts?contractAddress=&requestId=&type=minimal ``` The minimal response: * Inlines every validator's receipt JSON in `receipts[]` (objects, not GCS URLs). * Caps long string fields (HTML page text, model output, raw responses) at 1024 characters with a `` marker. * Adds derived `consensusType`, `requestDetails`, and `count` at the top level for convenience. Use it for triage and dashboards. If a field you need was truncated, fall back to the default (URL manifest) mode and fetch the receipt's GCS URL directly for the full content. ## Receipt Structure ### Top-level fields A single per-validator receipt looks like this: ```json { "requestId": "", "agentId": "", "contractAddress": "", "agentRunnerAddress": "", "consensusType": 0, "requestDetails": { "requester": "", "callbackAddress": "", "callbackSelector": "0x........", "threshold": 2, "subcommitteeSize": 3, "timeoutSeconds": 300 }, "status": "success", "startedAt": "2026-01-15T10:30:00.000Z", "completedAt": "2026-01-15T10:30:09.800Z", "elapsedMs": 9800, "agentImageUri": "https://storage.googleapis.com/somnia-agents-artifacts/agents//.tar", "request": "0x...", "response": { "result": "0x..." }, "agentReceipt": { "steps": [ /* see below */ ], "llmUsage": { "promptTokens": 0, "completionTokens": 0, "totalTokens": 0, "requests": 0, "streamingRequests": 0 }, "bandwidthUsage": { "bytesIn": 0, "bytesOut": 0, "requests": 0 }, "request": "0x...", "result": "0x..." } } ``` | Field | Purpose | | ----------------------------------------------- | ----------------------------------------------------- | | `status` | `success`, `failed`, or `timeout` | | `elapsedMs` | End-to-end duration on this validator | | `agentRunnerAddress` | Which validator produced this receipt | | `agentImageUri` | Pinned artifact bundle the agent ran from (auditable) | | `requestDetails.subcommitteeSize` / `threshold` | Consensus config in force for this request | | `consensusType` | `0` = Majority, `1` = Threshold | | `agentReceipt.steps` | Per-agent execution stages (see below) | | `agentReceipt.llmUsage` | Token counts for cost analysis | | `agentReceipt.bandwidthUsage` | Outbound HTTP volume | Failed requests follow the same envelope but add a top-level `errorMessage` and omit `agentReceipt` and `response`. Always check `status` before reading `agentReceipt`. ### Step names by agent Step names live under `agentReceipt.steps` and **vary by agent type**: | Agent | Step sequence | | ----------------- | ------------------------------------------------------------------------------------------------------------ | | JSON API Request | `request_received → request_decoded → handler_started → handler_completed → response_encoded` | | LLM Inference | `request_received → request_decoded → handler_started → llm_response → handler_completed → response_encoded` | | LLM Parse Website | `request → fetch → convert → extract` | Each step entry includes `name`, `started_at`, `status`, and an `inputs` object (and `output` where applicable). LLM-backed agents may also include auto-injected `reasoning`, `answerable`, and `confidence_score` (0–100) fields in the structured-extraction step. For LLM Inference requests where chain-of-thought was enabled (via the `chainOfThought` argument), the `llm_response` step also surfaces the model's `thinking` output. ## Using Receipts for Debugging ### Tracing failures When a request fails or times out, check `status` and the top-level `errorMessage`. For successes that returned an unexpected result, walk `agentReceipt.steps` — each step's `status` and any embedded output show exactly where execution diverged. For HTTP-based agents (JSON API Request, Parse Website), `bandwidthUsage.requests` is a quick sanity check that an outbound call happened at all. ### Checking LLM reasoning For LLM agents, the `agentReceipt.steps` entry covering the model call carries the inputs and the structured output. When the request opted into chain-of-thought (`chainOfThought = true`), the `thinking` field on the `llm_response` step surfaces the model's intermediate reasoning. The auto-injected `confidence_score` is useful for understanding low-confidence answers. ### Verifying external data (JSON API Request) The `handler_completed` step records the upstream response payload and the value extracted via the selector path — useful for confirming that the JSON shape on the API hasn't changed underneath you. ### Verifying scraped content (LLM Parse Website) Parse Website's `fetch` step records the URL(s) loaded; the `convert` step records the markdown handed to the model; the `extract` step records the structured-output result. If extraction quality is low, the `convert` output usually shows why (collapsed structure, missing sections, dynamic content not rendered). ### Monitoring cost Both `llmUsage` and `bandwidthUsage` are aggregated per validator on every receipt. Summing across requests gives a reliable per-agent cost profile (especially for LLM Inference and Parse Website, where token usage drives the bulk of work). ## Next Steps * [Gas Fees](/agents/invoking-agents/gas-fees.md) — Understand costs --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.somnia.network/agents/invoking-agents/receipts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.