> ## 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.

# Ethereum MEV and Bot Transaction Analysis with ParaLens

> Analyze MEV, arbitrage, and bot transactions with ParaLens. Extract realized profit, swap motifs, and economic actor attribution for arbitrage research.

ParaLens classifies MEV activity and reconstructs the full economic picture — realized profit, value flow graph, and structural proof — from a single transaction hash. Rather than manually tracing internal calls and decoding flash-loan callbacks, you POST the hash and get back a structured `TxReport` with the arbitrage type, a per-hop motif list, realized PnL, and the bot contract attribution.

## MEV Intent Kinds

ParaLens distinguishes four MEV-specific classifications:

| `intent_kind`          | Description                                                                                                                                                                 |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Arbitrage`            | A general arbitrage flow where value enters and exits across multiple protocols, but the mechanics do not fit a strictly atomic or flash-funded pattern.                    |
| `AtomicArbitrage`      | A fully atomic same-transaction arbitrage: funds leave and return to the same address within a single transaction with no external flash loan. The flow is self-closing.    |
| `FlashFundedArbitrage` | An arbitrage whose capital is sourced from a flash loan (e.g., Aave, Balancer, Uniswap v3). The loan is repaid within the same transaction, and the net profit is retained. |
| `MevBundle`            | A multi-transaction MEV bundle, typically submitted by a searcher via a block builder. The `TxReport` covers the single transaction within the bundle that was analyzed.    |

## Realized PnL

`economics.realized_pnl` is populated for self-closing atomic flows — transactions where funds leave and return to the same subject within the same transaction, making it possible to compute a verifiable profit figure.

```json theme={null}
"realized_pnl": {
  "basis": "self_closing_atomic_flow",
  "gross_usd": { "text": "$1,842.57", "available": true },
  "net_usd":   { "text": "$1,739.12", "available": true }
}
```

| Field       | Meaning                                                                                                           |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| `basis`     | How the PnL was computed. `"self_closing_atomic_flow"` means funds left and returned to the actor in the same tx. |
| `gross_usd` | Total received value before gas and fee deductions.                                                               |
| `net_usd`   | Profit after deducting gas and flash-loan fees. **Use this for the actual profit figure.**                        |

`realized_pnl` is **not available** when:

* The transaction is not self-closing (e.g., a multi-block strategy).
* USD pricing could not be resolved for one or more assets.
* `intent_kind` is not an arbitrage or MEV type.

Always check `realized_pnl.net_usd.available` before rendering.

<Warning>
  `economics.inflow_usd` is the gross received value — it is **not** profit. Use `realized_pnl.net_usd` for the actual profit figure when it is available.
</Warning>

## Structural Proof via Motifs

`motifs[]` contains the atomic structural primitives that the engine matched when classifying the transaction. For MEV transactions, the most relevant motif kinds are:

| Motif kind        | What it represents                                                              |
| ----------------- | ------------------------------------------------------------------------------- |
| `ProtocolSwap`    | A single swap hop on a DEX (Uniswap, Curve, Balancer, etc.)                     |
| `ClosedValueFlow` | A value cycle that returns to its origin — the core signal for atomic arbitrage |
| `FlashLoan`       | A flash-loan borrow/repay pair                                                  |

Group motifs by `scope_id` to reconstruct each logical sub-flow within a complex transaction, then filter by `kind` to count swap hops or confirm the closed-flow signature:

```typescript theme={null}
type Motif = {
  id: string;
  kind: string;
  status: string;
  confidence: number;
  scope_id: string;
  actor: string;
};

function analyzeMotifs(motifs: Motif[]) {
  // Group by scope
  const byScope = motifs.reduce<Record<string, Motif[]>>((acc, m) => {
    (acc[m.scope_id] ??= []).push(m);
    return acc;
  }, {});

  // Count swap hops
  const swapHops = motifs.filter((m) => m.kind === "ProtocolSwap").length;

  // Detect closed value flow (atomic arb signature)
  const hasClosedFlow = motifs.some((m) => m.kind === "ClosedValueFlow");

  // Detect flash loan usage
  const hasFlashLoan = motifs.some((m) => m.kind === "FlashLoan");

  return { byScope, swapHops, hasClosedFlow, hasFlashLoan };
}

const analysis = analyzeMotifs(report.motifs);
console.log(`Swap hops     : ${analysis.swapHops}`);
console.log(`Closed flow   : ${analysis.hasClosedFlow}`);
console.log(`Flash loan    : ${analysis.hasFlashLoan}`);
```

## Actor Attribution

MEV bots frequently have `classification.actor_matches_signer: false`. The three attribution fields clarify the ownership chain:

| Field                           | Who it identifies                                                                                                             |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `attribution.tx_signer`         | The EOA that signed the transaction and paid gas. For bot transactions this is often a hot wallet controlled by the searcher. |
| `attribution.authority_subject` | The economic authority — typically the EOA or Safe that funded and controls the bot contract.                                 |
| `attribution.operating_subject` | The contract doing the work — the MEV bot or executor contract that executed the swaps.                                       |

When researching a bot, `operating_subject` gives you the contract to trace across multiple transactions; `authority_subject` gives you the controlling wallet.

## Pipeline Stats

`pipeline_stats` exposes internal engine metrics that reflect transaction complexity. High values indicate dense, multi-hop MEV transactions:

| Field                | What it measures                                                   |
| -------------------- | ------------------------------------------------------------------ |
| `tvfg_nodes`         | Number of nodes in the Token Value Flow Graph (addresses + assets) |
| `tvfg_edges`         | Number of edges (individual value transfers)                       |
| `scopes`             | Number of logical sub-flows the engine identified                  |
| `economic_movements` | Total number of economic asset movements                           |

A simple two-hop arbitrage might have `tvfg_nodes: 8, tvfg_edges: 6`. A complex sandwich attack or multi-pool arbitrage might show `tvfg_nodes: 30+, tvfg_edges: 50+`.

## Example: Extracting Realized Profit and Motif Count

### cURL

```bash theme={null}
curl -X POST https://paralens-production.up.railway.app/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "ethereum",
    "tx_hash": "0xYOUR_ARB_TX_HASH"
  }'
```

### TypeScript

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

  if (!response.ok) {
    throw new Error(`ParaLens error: ${response.status}`);
  }

  const report = await response.json();
  const { classification, economics, motifs, pipeline_stats } = report;

  // Intent
  console.log("Intent    :", classification.intent_kind);
  console.log("Label     :", classification.intent_label);

  // Realized PnL (only for self-closing atomic flows)
  const pnl = economics.realized_pnl;
  if (pnl?.net_usd?.available) {
    console.log("Gross PnL :", pnl.gross_usd.text);
    console.log("Net PnL   :", pnl.net_usd.text);
  } else {
    console.log("Realized PnL: not available for this transaction");
  }

  // Motif summary
  const swapCount = motifs.filter((m: { kind: string }) => m.kind === "ProtocolSwap").length;
  const hasClosedFlow = motifs.some((m: { kind: string }) => m.kind === "ClosedValueFlow");
  console.log(`Swap hops : ${swapCount}`);
  console.log(`Closed flow confirmed: ${hasClosedFlow}`);

  // Complexity
  console.log("TVFG nodes:", pipeline_stats?.tvfg_nodes);
  console.log("TVFG edges:", pipeline_stats?.tvfg_edges);

  // Actor attribution
  console.log("Signer    :", report.attribution.tx_signer);
  console.log("Bot contract:", report.attribution.operating_subject);
  console.log("Controller:", report.attribution.authority_subject);
}

analyzeArbTx("0xYOUR_ARB_TX_HASH");
```