# Receipts

Every agent invocation produces an **execution receipt**—a detailed log of each step the agent took during execution. Receipts provide transparency and auditability for agent operations.

{% hint style="info" %}
**Note:** Receipts are currently stored on centralized infrastructure. We plan to migrate to decentralized storage in the future to ensure receipts are 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
* Receipts show **what one node did** to compute that result
* Different nodes may have different receipts (e.g., timing differences) but still agree on the result

### What's in a Receipt

```json
{
  "steps": [
    {
      "name": "request_received",
      "timestamp": "2024-01-15T10:30:00.000Z",
      "function": "fetchUint",
      "args": ["https://api.example.com/price", "data.price", 8]
    },
    {
      "name": "http_request",
      "url": "https://api.example.com/price",
      "method": "GET",
      "duration_ms": 245
    },
    {
      "name": "http_response",
      "status": 200,
      "body_preview": "{\"data\":{\"price\":42000.50}}"
    },
    {
      "name": "value_extracted",
      "selector": "data.price",
      "raw_value": 42000.50,
      "scaled_value": "4200050000000"
    },
    {
      "name": "response_encoded",
      "timestamp": "2024-01-15T10:30:00.250Z"
    }
  ],
  "result": "0x000000000000000000000000000000000000000000000000000003d2a0b76c00"
}
```

### Common Step Types

| Step Name          | Description                             |
| ------------------ | --------------------------------------- |
| `request_received` | Agent received the invocation request   |
| `request_decoded`  | ABI parameters decoded successfully     |
| `http_request`     | External HTTP call made                 |
| `http_response`    | Response received from external service |
| `llm_request`      | LLM inference requested                 |
| `llm_response`     | LLM generated a response                |
| `reasoning`        | LLM's chain-of-thought (if applicable)  |
| `value_extracted`  | Data extracted from response            |
| `response_encoded` | Final result encoded for return         |
| `error`            | An error occurred                       |

## Viewing Receipts in the UI

### From the Web App

1. Visit <https://agents.somnia.network>
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:

* Timeline of execution steps
* External calls made (URLs, responses)
* Data transformations
* Timing information

### From Receipt URL

You can view any receipt directly by navigating to:

```
https://agents.somnia.network/receipts/<request-id>
```

Replace `<request-id>` with your invocation's request ID.

## Fetching Receipts Programmatically

### From Receipt Service

Receipts are stored per-network and can be retrieved by request ID. Use the receipts service endpoint matching the network the request was created on:

| Network | Receipts service base URL                     |
| ------- | --------------------------------------------- |
| Mainnet | `https://receipts.mainnet.agents.somnia.host` |
| Testnet | `https://receipts.testnet.agents.somnia.host` |

```javascript
const requestId = 'abc123...';
const baseUrl = 'https://receipts.mainnet.agents.somnia.host';   // or the testnet URL above

const response = await fetch(`${baseUrl}?requestId=${requestId}`);
const receipt = await response.json();
console.log('Steps:', receipt.steps);
```

## Using Receipts for Debugging

### Tracing Errors

When an agent fails, the receipt shows where:

```json
{
  "steps": [
    { "name": "request_received", "function": "fetchUint" },
    { "name": "http_request", "url": "https://api.example.com/data" },
    {
      "name": "error",
      "message": "HTTP request failed: 404 Not Found",
      "url": "https://api.example.com/data"
    }
  ]
}
```

### Checking LLM Reasoning

For LLM agents, receipts can include the model's reasoning:

```json
{
  "steps": [
    { "name": "llm_request", "prompt": "Classify this text..." },
    {
      "name": "reasoning",
      "content": "The text contains positive sentiment words like 'excellent' and 'amazing'. There are no negative indicators..."
    },
    {
      "name": "llm_response",
      "output": "positive"
    }
  ]
}
```

This is especially useful for understanding how the LLM arrived at its answer.

### Verifying External Data

Check what data was actually fetched:

```json
{
  "steps": [
    {
      "name": "http_response",
      "status": 200,
      "body_preview": "{\"bitcoin\":{\"usd\":42000.50}}"
    },
    {
      "name": "value_extracted",
      "selector": "bitcoin.usd",
      "raw_value": 42000.50
    }
  ]
}
```

## Next Steps

* [Invoking from Solidity](/agents/invoking-agents/from-solidity.md) — Call agents from smart contracts
* [Gas Fees](/agents/invoking-agents/gas-fees.md) — Understand costs


---

# Agent Instructions: 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:

```
GET https://docs.somnia.network/agents/invoking-agents/receipts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.