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

# TxReport — Complete API Response Schema Reference

> Complete reference for the TxReport object returned by POST /analyze — top-level shape, section summary, and links to each sub-object.

Every successful call to `POST /analyze` returns a `TxReport`. This page describes the top-level shape of that object and links to the full documentation for each section. Each top-level key represents a distinct analytical lens — from raw chain identity through economic summary and structural proof.

## Top-Level Shape

```json theme={null}
{
  "schema_version": 1,
  "chain": {},
  "tx": {},
  "execution": {},
  "classification": {},
  "economics": {},
  "inventory_deltas": [],
  "position_effects": [],
  "motifs": [],
  "attribution": {},
  "pipeline_stats": {}
}
```

## Fields

<ResponseField name="schema_version" type="number" required>
  TxReport schema version. Currently `1`. This value is bumped on any breaking change to the top-level shape or the semantics of a sub-object. Check this field if you maintain a long-lived integration.
</ResponseField>

<ResponseField name="chain" type="object" required>
  Chain information identifying which network the transaction belongs to.

  <Expandable title="chain fields">
    <ResponseField name="chain.id" type="number" required>
      EIP-155 chain ID (e.g. `1` for Ethereum mainnet, `137` for Polygon).
    </ResponseField>

    <ResponseField name="chain.name" type="string" required>
      Human-readable chain name (e.g. `"ethereum"`, `"polygon"`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tx" type="object" required>
  Transaction identity — the minimal set of fields needed to locate and display the transaction.

  <Expandable title="tx fields">
    <ResponseField name="tx.hash" type="string" required>
      The 0x-prefixed transaction hash as submitted.
    </ResponseField>

    <ResponseField name="tx.block_number" type="number" required>
      Block number in which the transaction was included.
    </ResponseField>

    <ResponseField name="tx.signer" type="string" required>
      Address of the EOA that signed and submitted the transaction.
    </ResponseField>

    <ResponseField name="tx.to" type="string | null" required>
      Recipient or contract address. `null` for contract-creation transactions.
    </ResponseField>

    <ResponseField name="tx.etherscan_url" type="string" required>
      Fully-formed Etherscan (or equivalent block explorer) URL for this transaction.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="execution" type="object" required>
  Execution outcome and gas consumption for the transaction.

  <Expandable title="execution fields">
    <ResponseField name="execution.outcome" type="string" required>
      Human-readable outcome string (e.g. `"Success"`, `"Reverted"`).
    </ResponseField>

    <ResponseField name="execution.reverted" type="boolean" required>
      `true` if the transaction reverted on-chain. When `true`, most economic fields will be zeroed or unavailable.
    </ResponseField>

    <ResponseField name="execution.gas_used" type="number" required>
      Actual gas units consumed by execution.
    </ResponseField>

    <ResponseField name="execution.base_fee_per_gas" type="number" required>
      Base fee per gas unit (in wei) for the block containing this transaction, as defined by EIP-1559.
    </ResponseField>

    <ResponseField name="execution.priority_fee_per_gas" type="number" required>
      Miner/validator tip per gas unit (in wei) paid above the base fee.
    </ResponseField>

    <ResponseField name="execution.gas_cost_native" type="string" required>
      Total gas cost expressed in the chain's native token (e.g. ETH), formatted as a decimal string.
    </ResponseField>

    <ResponseField name="execution.gas_cost_usd" type="DisplayMoney" required>
      Gas cost expressed in USD as a `DisplayMoney` object — `{ text, available, reason? }`. Always check `available` before rendering. See the [economics](/docs/api-reference/economics) page for the full `DisplayMoney` shape.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="classification" type="object" required>
  Intent classification headline: what the transaction did, how certain the engine is, and who the economic actor was. See the full [classification reference](/docs/api-reference/classification).
</ResponseField>

<ResponseField name="economics" type="object" required>
  Economic summary for the elected actor — inflows, outflows, net USD, gas fee, realized PnL, and pricing coverage. See the full [economics reference](/docs/api-reference/economics).
</ResponseField>

<ResponseField name="inventory_deltas" type="array" required>
  Per-subject, per-asset balance changes. Every token movement recorded for every address involved in the transaction. See the full [inventory\_deltas reference](/docs/api-reference/inventory-deltas).
</ResponseField>

<ResponseField name="position_effects" type="array" required>
  DeFi position changes derived from the transaction — liquidity adds/removes, borrows, repayments, and similar protocol-level effects. See the full [position\_effects reference](/docs/api-reference/position-effects).
</ResponseField>

<ResponseField name="motifs" type="array" required>
  Structural motifs detected in the transaction, together with the supporting proof data. Motifs are reusable building blocks (e.g. a single on-chain swap) that compose into higher-level intents. See the full [motifs reference](/docs/api-reference/motifs).
</ResponseField>

<ResponseField name="attribution" type="object" required>
  Signer-to-actor attribution — explains the relationship between the address that signed the transaction and the address that is the economic beneficiary. See the full [attribution reference](/docs/api-reference/attribution).
</ResponseField>

<ResponseField name="pipeline_stats" type="object" required>
  Analysis pipeline counts and timing data intended for advanced integrators and debugging. See the full [pipeline\_stats reference](/docs/api-reference/pipeline-stats).
</ResponseField>

## Reading Order

`TxReport` is designed with a **curated-summary-first** philosophy: the most actionable fields appear at the top, and raw evidence lives deeper in the object. The recommended reading order is:

| Step | Field              | Question answered                                                                                           |
| ---- | ------------------ | ----------------------------------------------------------------------------------------------------------- |
| 1    | `classification`   | **What happened?** — intent kind, label, proof status, and confidence                                       |
| 2    | `economics`        | **What was the money story?** — net value change, token in/out, and fees for the actor                      |
| 3    | `inventory_deltas` | **Which assets moved where?** — drill-down evidence behind the economics summary                            |
| 4    | `motifs`           | **What structural patterns were matched?** — on-chain building blocks with proof                            |
| 5    | `position_effects` | **Which DeFi positions changed?** — protocol-level position changes                                         |
| 6    | `attribution`      | **Who signed vs. who economically acted?** — relevant when a bot or aggregator executed on behalf of a user |
| 7    | `pipeline_stats`   | **Advanced / debug only** — internal analysis counts and timing                                             |

<Note>
  Start with `classification.intent_label` and `economics.net_usd_after_gas` for a two-field summary suitable for any consumer UI. Reach into the lower sections only when your integration needs drill-down detail.
</Note>

## Section Reference

<CardGroup cols={2}>
  <Card title="classification" icon="tag" href="/docs/api-reference/classification">
    Intent kind, label, proof status, confidence, actor, and matched rule.
  </Card>

  <Card title="economics" icon="circle-dollar-to-slot" href="/docs/api-reference/economics">
    Inflows, outflows, net USD, gas fee, realized PnL, and valuation coverage.
  </Card>

  <Card title="inventory_deltas" icon="arrow-right-arrow-left" href="/docs/api-reference/inventory-deltas">
    Per-subject, per-asset token balance changes behind the economics summary.
  </Card>

  <Card title="position_effects" icon="chart-line" href="/docs/api-reference/position-effects">
    DeFi position changes — liquidity, borrows, repayments, and more.
  </Card>

  <Card title="motifs" icon="puzzle-piece" href="/docs/api-reference/motifs">
    Structural motifs and their supporting proof data.
  </Card>

  <Card title="attribution" icon="user-tag" href="/docs/api-reference/attribution">
    Signer-to-actor relationship and delegation context.
  </Card>

  <Card title="pipeline_stats" icon="gauge" href="/docs/api-reference/pipeline-stats">
    Analysis pipeline counts and timing for advanced integrators.
  </Card>
</CardGroup>