> ## 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 Compliance and Transaction Triage with ParaLens

> Use ParaLens to classify suspicious Ethereum transactions, detect actor/signer mismatches, and surface economic warnings for compliance review workflows.

When reviewing suspicious or flagged Ethereum transactions, analysts typically face raw hex data, token transfer logs, and opaque internal calls. ParaLens converts a transaction hash into structured evidence — classification, actor attribution, value flows, and engine-detected warnings — so your compliance team can triage faster and with more confidence, without building custom on-chain decoders.

<Note>
  ParaLens analyzes single transactions. Multi-transaction cluster analysis and wallet history are not currently available.
</Note>

## Signals for Compliance Review

The following `TxReport` fields are the most useful indicators of activity warranting further review.

**`classification.actor_matches_signer: false`**
The on-chain economic actor differs from the wallet that signed the transaction. This is normal for contract wallets and aggregators, but it is also a characteristic of proxy contracts, smart account abstraction setups, and MEV bots. Any flagged transaction with a signer/actor mismatch warrants inspection of both the signing address and the contract that executed the economic activity.

**`economics.warnings[]`**
The ParaLens engine surfaces anomalies detected during analysis. A common example is `IntentActorDiffersFromSigner`, which is emitted when the engine detects that the beneficiary of the transaction differs materially from the signer. Review all warnings before closing a triage case.

**Large `inventory_deltas`**
Review `inventory_deltas[]` sorted descending by `usd.value`. Unexpectedly large inflows or outflows relative to the signer's known profile are a primary triage signal.

**`intent_kind: MevBundle` or `FlashFundedArbitrage`**
These intent kinds indicate complex, capital-efficient MEV activity. Flash-funded arbitrage borrows and repays funds within a single block, which can be used to manipulate prices without requiring permanent capital. Flag these for specialist review.

**`classification.intent_kind: "TransactionReverted"`**
A reverted transaction means the on-chain execution failed. Reverted transactions still consume gas and can indicate a failed attack attempt (e.g., a failed sandwich, a failed exploit, or a front-run that was beaten). They appear in the mempool and block history and should not be ignored.

## Triage Workflow

<Steps>
  <Step title="POST the flagged tx hash">
    Submit the transaction hash to the `/analyze` endpoint.

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

  <Step title="Check intent classification">
    Read `classification.intent_kind` and `classification.intent_label` to establish the headline category. Note the `confidence` score — low confidence means the engine could not resolve a clear pattern and the transaction warrants deeper manual review.

    ```typescript theme={null}
    const { intent_kind, intent_label, confidence, status } = report.classification;
    console.log(`Intent : ${intent_label} (${intent_kind})`);
    console.log(`Confidence : ${Math.round(confidence * 100)}%  |  Status : ${status}`);
    ```
  </Step>

  <Step title="Check actor/signer mismatch">
    Compare `attribution.tx_signer` with `classification.actor`. If `actor_matches_signer` is `false`, record both addresses and note the type of intermediary (contract wallet, bot, aggregator) for the case file.
  </Step>

  <Step title="Review economic warnings">
    Inspect `economics.warnings[]`. Each warning carries a machine-readable code and a human-readable message. Treat any warning as a reason to escalate or deepen the review.

    ```typescript theme={null}
    if (report.economics.warnings?.length > 0) {
      console.log("⚠️  Engine warnings:");
      report.economics.warnings.forEach((w: { code: string; message: string }) => {
        console.log(`  [${w.code}] ${w.message}`);
      });
    }
    ```
  </Step>

  <Step title="Review inventory deltas by USD value">
    Sort `inventory_deltas` by `usd.value` descending and inspect the largest movements. Look for disproportionate inflows to the actor relative to their outflows — this is the hallmark of profitable MEV or exploitation.

    ```typescript theme={null}
    const sorted = [...report.inventory_deltas]
      .filter((d) => d.usd?.value != null)
      .sort((a, b) => (b.usd?.value ?? 0) - (a.usd?.value ?? 0));

    sorted.slice(0, 10).forEach((d) => {
      console.log(
        `${d.direction.padEnd(8)} ${d.asset_label.padEnd(12)} ${d.usd?.text ?? "—"}  →  ${d.subject}`
      );
    });
    ```
  </Step>

  <Step title="Review motifs for structural evidence">
    Inspect `motifs[]` for the structural primitives the engine matched. The presence of `ClosedValueFlow`, `FlashLoan`, or `Sandwich` motifs is strong structural evidence of MEV activity. Use motif `confidence` scores to weight the evidence.
  </Step>

  <Step title="Cross-reference on Etherscan">
    Use `tx.etherscan_url` to open the transaction directly in the public block explorer for a secondary source of truth, raw log inspection, and contract verification status.

    ```typescript theme={null}
    console.log("Etherscan:", report.tx?.etherscan_url);
    ```
  </Step>
</Steps>

## Attribution Fields

The `attribution` object identifies the three key parties to any Ethereum transaction.

| Field               | Who it identifies                                                                                                                                                                               | When it matters                                                                           |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `tx_signer`         | The EOA that signed the transaction and paid gas. Always present.                                                                                                                               | The "legal" sender; the address to associate with the gas payment and mempool submission. |
| `authority_subject` | The economic authority — the controlling wallet or entity that directed the operation. For a simple EOA transaction this equals `tx_signer`. For a bot or Safe, this is the controlling wallet. | Use when you need to identify the human or organization behind the activity.              |
| `operating_subject` | The contract or address that executed the economic activity. May be a router, bot contract, or smart wallet.                                                                                    | Use when you need to identify the on-chain executor for cross-transaction correlation.    |

## Batch Triage

The ParaLens API is stateless — each `/analyze` call is fully independent. You can loop over a list of flagged transaction hashes and call the API for each one in parallel. The example below shows a simple batch triage pattern:

```typescript theme={null}
async function triageBatch(txHashes: string[]) {
  const results = await Promise.allSettled(
    txHashes.map(async (hash) => {
      const res = await fetch(
        "https://paralens-production.up.railway.app/analyze",
        {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ chain: "ethereum", tx_hash: hash }),
        }
      );
      if (!res.ok) throw new Error(`HTTP ${res.status} for ${hash}`);
      return res.json();
    })
  );

  return results.map((result, i) => ({
    tx_hash: txHashes[i],
    status: result.status,
    report: result.status === "fulfilled" ? result.value : null,
    error: result.status === "rejected" ? result.reason?.message : null,
  }));
}

const flaggedHashes = [
  "0xAAAA...",
  "0xBBBB...",
  "0xCCCC...",
];

const triageResults = await triageBatch(flaggedHashes);

triageResults.forEach(({ tx_hash, status, report }) => {
  if (status === "fulfilled" && report) {
    const hasWarnings = report.economics.warnings?.length > 0;
    const mismatch = !report.classification.actor_matches_signer;
    const flagged = hasWarnings || mismatch;
    console.log(
      `${tx_hash}  |  ${report.classification.intent_kind.padEnd(24)}  |  ${flagged ? "🚩 REVIEW" : "✅ clear"}`
    );
  } else {
    console.log(`${tx_hash}  |  ERROR`);
  }
});
```