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

# ParaLens Core Concepts: TxReport, Intents, and Valuation

> Understand the TxReport returned by ParaLens: intent classification, economic actor election, motifs, DisplayMoney, and block-aligned USD valuation.

ParaLens uses a layered pipeline to turn raw trace data into a structured report. This page explains the key concepts you will encounter when reading a TxReport so that you can parse responses correctly, handle edge cases gracefully, and build reliable integrations.

***

## TxReport

The `TxReport` is the versioned JSON object returned by every successful `/analyze` call. It is a self-contained intelligence report for a single Ethereum transaction. The top-level sections are:

| Section            | What it contains                                           |
| ------------------ | ---------------------------------------------------------- |
| `classification`   | Intent kind, label, status, confidence, and actor election |
| `economics`        | Token in/out, net USD value, gas cost, and realized PnL    |
| `inventory_deltas` | Per-subject, per-asset value changes (the raw token flows) |
| `motifs`           | Structural patterns discovered inside the transaction      |
| `attribution`      | Protocol names and contract labels for addresses involved  |
| `position_effects` | DeFi-specific events: borrow, repay, collateral, liquidity |
| `pipeline_stats`   | Timing, asset coverage, and pipeline metadata              |

The `schema_version` field at the top level is an integer that identifies the shape of the report. Always check this in your client before parsing. The current version is **`1`**.

***

## Intent Classification

ParaLens classifies every transaction into one of 25+ `intent_kind` values by matching the transaction's value-flow graph against named structural patterns. Each kind maps to a human-readable `intent_label` for display. The classification also carries a `status` and `confidence` to signal how certain the pipeline is.

| Field        | Values                                                                         |
| ------------ | ------------------------------------------------------------------------------ |
| `status`     | `Proven` — strong structural evidence; `Suspected` — likely but not definitive |
| `confidence` | `High`, `Medium`, `Low`                                                        |

### Example Intent Kinds

| `intent_kind`     | `intent_label`   | Typical scenario                                                    |
| ----------------- | ---------------- | ------------------------------------------------------------------- |
| `Swap`            | Token Swap       | User exchanges one ERC-20 for another via a DEX                     |
| `Arbitrage`       | Arbitrage        | Same asset enters and exits at a profit in one transaction          |
| `Liquidation`     | Liquidation      | Undercollateralised position is closed by a third party             |
| `Bridge`          | Bridge Transfer  | Assets are locked or minted across a cross-chain bridge             |
| `LiquidityAdd`    | Add Liquidity    | LP tokens minted in exchange for a token pair                       |
| `LiquidityRemove` | Remove Liquidity | LP tokens burned to redeem underlying tokens                        |
| `Borrow`          | Borrow           | Collateral posted and a debt asset is drawn from a lending protocol |
| `Repay`           | Repay            | Debt asset returned to a lending protocol                           |
| `NftPurchase`     | NFT Purchase     | ETH or ERC-20 exchanged for an ERC-721/ERC-1155 token               |
| `Transfer`        | Token Transfer   | Plain ERC-20 or native ETH transfer with no protocol interaction    |

***

## Economic Actor Election

The `tx.signer` — the wallet address that signed and submitted a transaction — is **not always** the entity that economically benefits from it. Aggregators, smart wallets, MEV bots, and protocol routers frequently act as intermediaries: the signer may be a keeper contract or a relayer, while the real beneficiary is a different address.

ParaLens elects a single `actor` address in the `classification` section. This is the address that the economics (token in/out, net USD, realized PnL) are computed relative to.

```json theme={null}
{
  "classification": {
    "actor": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "actor_matches_signer": false
  }
}
```

When `actor_matches_signer` is `false`, treat it as a signal to examine the `attribution` section — the actor is likely a smart wallet, a protocol contract, or an MEV searcher's bot. Interpreting economics against the signer address in these cases will be misleading.

***

## Inventory Deltas

Inventory deltas are the per-subject, per-asset value changes that underpin the economic summary. Each delta represents a single asset moving into or out of a single subject's balance during the transaction.

Each delta object contains:

| Field         | Description                                             |
| ------------- | ------------------------------------------------------- |
| `subject`     | The address whose balance changed                       |
| `asset_label` | Human-readable token name (e.g., `USDC`, `WETH`, `ETH`) |
| `direction`   | `Inflow` — asset arrived; `Outflow` — asset departed    |
| `quantity`    | Token amount as a decimal string                        |
| `usd_value`   | `DisplayMoney` shape (see below)                        |

Inventory deltas give you the full picture of value movement — not just the actor's net position, but every address that gained or lost tokens, including protocols, liquidity pools, and fee recipients.

***

## Motifs

Motifs are named structural patterns that the pipeline discovers inside the transaction's value-flow graph. They are the evidence layer beneath the `intent_kind` classification.

Common motifs include:

| Motif             | What it means                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------ |
| `ProtocolSwap`    | A swap routed through a recognised DEX contract                                            |
| `LinearTransfer`  | Value moved in a straight line from A → B with no splitting                                |
| `ClosedValueFlow` | Value that entered an address also left it — no net change (classic arbitrage loop signal) |
| `FlashLoan`       | An asset was borrowed and returned in the same transaction                                 |
| `LiquidityEvent`  | Tokens deposited into or withdrawn from an AMM pool                                        |

Each motif carries a `scope_id` that groups related motifs belonging to the same logical sub-flow. When multiple motifs share a `scope_id`, they describe different facets of the same structural event.

***

<Accordion title="DisplayMoney — always check `available` before reading `text`">
  Many USD-denominated fields in the TxReport use the **DisplayMoney** shape rather than a raw number:

  ```json theme={null}
  {
    "text": "$4,987.34",
    "available": true,
    "reason": null
  }
  ```

  | Field       | Type             | Description                                                                           |
  | ----------- | ---------------- | ------------------------------------------------------------------------------------- |
  | `text`      | `string`         | Formatted USD string, e.g. `"$1,234.56"`. Only valid when `available` is `true`.      |
  | `available` | `boolean`        | `true` if a USD value could be computed; `false` if pricing was unavailable.          |
  | `reason`    | `string \| null` | When `available` is `false`, explains why (e.g., `"asset not priced at this block"`). |

  **Always gate on `available: true` before parsing `text`.** When `available` is `false`, the `text` field may be an empty string, a placeholder, or absent. Failing to check this is the most common source of display bugs in ParaLens integrations.
</Accordion>

***

## Valuation

ParaLens prices all assets at the **block height** of the transaction — not at the current spot price. This ensures that USD values reflect what assets were worth at the moment the transaction executed.

The `pipeline_stats.valuation` field reports:

* How many distinct assets were involved in the transaction
* How many of those assets could be priced at the block

When assets are unpriced (e.g., long-tail tokens, newly deployed contracts, NFTs), the corresponding `DisplayMoney` fields will have `available: false`, and aggregate USD net values may also be unavailable.

***

<Accordion title="Realized PnL — only available for atomic/self-closing flows">
  The `economics.realized_pnl` section reports profit and loss for transactions where value enters and exits in the same atomic context — most commonly on-chain arbitrage.

  ```json theme={null}
  {
    "economics": {
      "realized_pnl": {
        "supported": true,
        "gross_profit_usd": { "text": "$312.44", "available": true },
        "gas_cost_usd": { "text": "$18.72", "available": true },
        "net_profit_usd": { "text": "$293.72", "available": true }
      }
    }
  }
  ```

  For ordinary swaps, deposits, withdrawals, and transfers, `realized_pnl.supported` will be `false` — these transactions do not have a self-closing value loop, so there is no atomically realised gain or loss to report. Multi-transaction FIFO-based PnL is outside the current scope of ParaLens.
</Accordion>

***

## schema\_version

The `schema_version` field is an integer at the top level of every TxReport:

```json theme={null}
{
  "schema_version": 1,
  "classification": { ... },
  ...
}
```

Check `schema_version` in your client before parsing the rest of the response. When the TxReport shape changes in a backwards-incompatible way, `schema_version` will be incremented. The current version is **`1`**.