ParaLens Core Concepts: TxReport, Intents, and 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.

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

DisplayMoney — always check `available` before reading `text`

Many USD-denominated fields in the TxReport use the DisplayMoney shape rather than a raw number:

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

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.

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.

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

schema_version

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

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

Get Started

Use Cases

Integration Guides

Help

ParaLens Core Concepts: TxReport, Intents, and Valuation

TxReport

Intent Classification

Example Intent Kinds

Economic Actor Election

Inventory Deltas

Motifs

Valuation

schema_version

​TxReport

​Intent Classification

​Example Intent Kinds

​Economic Actor Election

​Inventory Deltas

​Motifs

​Valuation

​schema_version

TxReport

Intent Classification

Example Intent Kinds

Economic Actor Election

Inventory Deltas

Motifs

Valuation

schema_version