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

# Feed Ethereum Transaction Intelligence to AI Agents

> Use ParaLens to convert raw Ethereum tx hashes into structured TxReport JSON that LLMs and AI agents can parse, reason over, and summarize.

LLMs and AI agents struggle with raw on-chain data. EVM bytecode, ABI-encoded calldata, token transfer event logs, and internal call traces are dense, low-signal, and expensive to fit in a context window. ParaLens pre-processes the trace and returns a structured `TxReport` that is designed to be consumed by downstream AI systems — labeled intents, formatted USD values, actor attribution, and human-readable token flow summaries that a model can parse and reason over without any domain-specific prompt engineering.

## Why Structured Data Matters for AI

Raw Ethereum transaction data presents several problems for LLMs:

* **Bytecode and calldata** are hex-encoded and require ABI decoding before they carry any semantic content.
* **Event logs** are tightly packed and reference opaque addresses with no human-readable context.
* **Internal traces** can be hundreds of nested calls deep — far beyond what a model can reason over efficiently.
* **USD values** are absent from on-chain data entirely; price resolution requires off-chain oracle data.

`TxReport` solves all of these. By the time data reaches your agent, it is a clean JSON object with a headline intent (`"AtomicArbitrage"`), formatted USD values (`"$1,739.12"`), named token symbols (`"WETH"`, `"USDC"`), and a compact motif list that summarizes the structural proof. A model can reason meaningfully over this in a single context window.

## Recommended Fields for LLM Context

Not all fields in `TxReport` are equally useful for AI tasks. Focus the model's context on these high-signal groups:

| Group              | Fields                                                                               | Why it matters                                                                                              |
| ------------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `classification`   | `intent_kind`, `intent_label`, `confidence`, `actor`, `actor_matches_signer`         | The headline: what happened, how confident the engine is, and who did it.                                   |
| `economics`        | `token_in`, `token_out`, `net_usd_before_gas`, `fee_usd`, `realized_pnl`, `warnings` | The money story: what went in, what came out, net result, gas cost, and any anomalies.                      |
| `inventory_deltas` | `subject`, `asset_label`, `direction`, `quantity`, `usd`                             | The full asset movement list — useful for complex flows where `token_in`/`token_out` alone is insufficient. |
| `motifs`           | `kind`, `confidence`, `scope_id`                                                     | Structural proof — lets the model reference specific evidence when explaining the transaction.              |

<Tip>
  Strip `pipeline_stats`, `price_source`, and `price_confidence` from the context you pass to the LLM — these are low-signal for most AI tasks and consume tokens without adding reasoning value.
</Tip>

## Minimal LLM Context Snippet

Extract only the fields that matter before passing the report to a model. This keeps prompts focused and token-efficient.

```typescript theme={null}
type TxReport = {
  classification: Record<string, unknown>;
  economics: Record<string, unknown>;
  inventory_deltas: unknown[];
  motifs: unknown[];
  attribution: Record<string, unknown>;
  pipeline_stats?: Record<string, unknown>;
};

function buildLlmContext(report: TxReport) {
  const { classification, economics, inventory_deltas, motifs, attribution } = report;

  return {
    // What happened
    intent: {
      kind: classification.intent_kind,
      label: classification.intent_label,
      confidence: classification.confidence,
      status: classification.status,
    },

    // Who did it
    attribution: {
      signer: attribution.tx_signer,
      actor: classification.actor,
      actor_matches_signer: classification.actor_matches_signer,
      authority: attribution.authority_subject,
      operating_contract: attribution.operating_subject,
    },

    // The money story
    economics: {
      token_in: economics.token_in,
      token_out: economics.token_out,
      net_usd_before_gas: economics.net_usd_before_gas,
      fee_usd: economics.fee_usd,
      realized_pnl: economics.realized_pnl ?? null,
      warnings: economics.warnings ?? [],
    },

    // Asset movements (top 10 by USD value)
    top_flows: (inventory_deltas as Array<{ usd?: { value?: number } }>)
      .filter((d) => d.usd?.value != null)
      .sort((a, b) => (b.usd?.value ?? 0) - (a.usd?.value ?? 0))
      .slice(0, 10),

    // Structural proof
    motifs: (motifs as Array<{ kind: string; confidence: number; scope_id: string }>)
      .map(({ kind, confidence, scope_id }) => ({ kind, confidence, scope_id })),
  };
}
```

## Tool / Function Calling

Wrap the `/analyze` call as a named tool so your AI agent can request transaction analysis on demand. The JSON schema below is compatible with both OpenAI function calling and Anthropic tool use.

### Tool Definition

```json theme={null}
{
  "name": "analyze_ethereum_transaction",
  "description": "Analyze an Ethereum transaction hash using ParaLens. Returns a structured TxReport with intent classification, actor attribution, token flows, economic summary, and motif evidence.",
  "parameters": {
    "type": "object",
    "properties": {
      "tx_hash": {
        "type": "string",
        "description": "The 0x-prefixed Ethereum transaction hash to analyze."
      },
      "chain": {
        "type": "string",
        "enum": ["ethereum"],
        "default": "ethereum",
        "description": "The blockchain network. Currently only 'ethereum' is supported."
      }
    },
    "required": ["tx_hash"]
  }
}
```

### Tool Handler (TypeScript)

```typescript theme={null}
async function analyzeEthereumTransaction({
  tx_hash,
  chain = "ethereum",
}: {
  tx_hash: string;
  chain?: string;
}) {
  const res = await fetch(
    "https://paralens-production.up.railway.app/analyze",
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ chain, tx_hash }),
    }
  );

  if (!res.ok) {
    throw new Error(
      `ParaLens returned ${res.status}: ${await res.text()}`
    );
  }

  const report = await res.json();
  // Return the focused context rather than the full report
  return buildLlmContext(report);
}
```

## Example Prompt Pattern

Use the following template when asking a model to summarize or reason over a `TxReport`. The three-part structure — summary, anomaly detection, economic outcome — keeps responses focused and auditable.

```text theme={null}
You are a blockchain analyst assistant. You will be given a structured Ethereum
transaction report produced by the ParaLens analysis engine.

Transaction report:
<txreport>
{TxReport JSON}
</txreport>

Answer the following questions:
1. Summarize what happened in this transaction in one clear sentence.
2. Identify any unusual or suspicious activity. If none, say "No anomalies detected."
3. State the net economic outcome for the economic actor, including any realized
   profit or loss if available.

Be concise. Reference specific fields from the report to support your statements.
```

Replace `{TxReport JSON}` with the output of `JSON.stringify(buildLlmContext(report), null, 2)`.

### Example Agent Loop (OpenAI)

```typescript theme={null}
import OpenAI from "openai";

const client = new OpenAI();

const tools: OpenAI.Chat.ChatCompletionTool[] = [
  {
    type: "function",
    function: {
      name: "analyze_ethereum_transaction",
      description:
        "Analyze an Ethereum transaction hash and return a structured report with intent, actor, economics, and motifs.",
      parameters: {
        type: "object",
        properties: {
          tx_hash: {
            type: "string",
            description: "0x-prefixed Ethereum transaction hash",
          },
        },
        required: ["tx_hash"],
      },
    },
  },
];

async function runAgent(userMessage: string) {
  const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
    { role: "user", content: userMessage },
  ];

  while (true) {
    const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages,
      tools,
      tool_choice: "auto",
    });

    const choice = response.choices[0];

    if (choice.finish_reason === "tool_calls" && choice.message.tool_calls) {
      messages.push(choice.message);

      for (const call of choice.message.tool_calls) {
        const args = JSON.parse(call.function.arguments);
        const result = await analyzeEthereumTransaction(args);
        messages.push({
          role: "tool",
          tool_call_id: call.id,
          content: JSON.stringify(result),
        });
      }
    } else {
      // Final text response
      console.log(choice.message.content);
      break;
    }
  }
}

runAgent(
  "What happened in transaction 0xYOUR_TX_HASH? Was it profitable?"
);
```