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.

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.

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

{
  "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

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:

{
  "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:

{
  "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:

{
  "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 — Call agents from smart contracts

• Gas Fees — Understand costs