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

# classification — Transaction Intent Classification

> The classification object in TxReport answers 'what happened' — intent kind, label, proof status, confidence, actor, and matched rule.

The `classification` object is the headline result of ParaLens analysis. It tells you what the transaction did, how certain the engine is, and who the economic actor was. For most integrations, `intent_label` and `confidence` are the only two fields you need to surface to end users — the remaining fields support deeper tooling, layout logic, and audit trails.

## Example

```json theme={null}
{
  "intent_kind": "AggregatedSwap",
  "intent_label": "Swap (via aggregator)",
  "status": "Proven",
  "confidence": "High",
  "actor": "0xbdb3ba9ffe392549e1f8658dd2630c141fdf47b6",
  "actor_matches_signer": false,
  "matched_rule": "aggregated_swap_with_transfers",
  "rule_version": 1,
  "structural_proof": true,
  "fragments": [
    { "kind": "AggregatedSwap", "status": "Proven", "confidence": "High" }
  ]
}
```

## Fields

<ResponseField name="intent_kind" type="string" required>
  Machine-readable intent enum that identifies the transaction's primary intent category. Use this field for conditional logic, layout switching, and icon selection — not for display text.

  See [Intent Kinds](/docs/api-reference/intent-kinds) for the full list of possible values.
</ResponseField>

<ResponseField name="intent_label" type="string" required>
  User-facing label suitable for UI headings, notification copy, and export reports. This string is already formatted for display — use it directly rather than deriving labels from `intent_kind`.

  **Example values:** `"Swap (via aggregator)"`, `"Add Liquidity"`, `"ERC-20 Transfer"`.
</ResponseField>

<ResponseField name="status" type="string" required>
  Proof status for the classification. One of:

  | Value       | Meaning                                                         |
  | ----------- | --------------------------------------------------------------- |
  | `Proven`    | Structural on-chain evidence fully supports the classification. |
  | `Suspected` | Heuristic or partial evidence — treat with additional caution.  |
</ResponseField>

<ResponseField name="confidence" type="string" required>
  Engine confidence in the classification. One of `High`, `Medium`, or `Low`.

  Pair with `status` to render trust badges: a `Proven` + `High` result warrants no caveat; `Suspected` + `Low` should carry a visible disclaimer.
</ResponseField>

<ResponseField name="actor" type="string | null" required>
  Checksummed Ethereum address of the elected economic actor — the address that is the primary financial beneficiary of the transaction. May be `null` when the engine cannot determine a single actor (e.g. multi-beneficiary transactions with no clear primary).
</ResponseField>

<ResponseField name="actor_matches_signer" type="boolean" required>
  `true` when `actor` equals `tx.signer`, meaning the address that signed the transaction is also the economic beneficiary.

  When `false`, the transaction was executed on behalf of the actor — for example, a MEV bot submitting an arbitrage on behalf of a wallet, or a relayer submitting a meta-transaction. In these cases, the `attribution` object provides the full delegation context.

  <Warning>
    When `actor_matches_signer` is `false`, surface a notice in your UI such as *"Executed on behalf of \[actor]"* rather than attributing the economics to the signer.
  </Warning>
</ResponseField>

<ResponseField name="matched_rule" type="string | null" required>
  Slug identifier for the classifier rule that produced this result (e.g. `"aggregated_swap_with_transfers"`). `null` when the classification was produced by a fallback heuristic rather than a named rule.

  Useful for audit logs and debugging classification mismatches.
</ResponseField>

<ResponseField name="rule_version" type="number | null" required>
  Integer version of the matched rule. Incremented when the rule logic changes in a backwards-incompatible way. `null` when `matched_rule` is `null`.
</ResponseField>

<ResponseField name="structural_proof" type="boolean" required>
  `true` when structural on-chain evidence (e.g. event topology, call-trace patterns) directly supports the classification. `false` when the result relies on heuristics or metadata alone.

  Mirrors the `status` field but as a boolean shorthand — `structural_proof: true` corresponds to `status: "Proven"`.
</ResponseField>

<ResponseField name="fragments" type="array" required>
  Sub-intents that compose the top-level intent. For simple transactions this array will contain a single entry. For complex multi-step transactions (e.g. a flash loan wrapping a swap) it will list each constituent intent.

  <Expandable title="fragment fields">
    <ResponseField name="fragments[].kind" type="string" required>
      Machine-readable intent kind for this fragment. Uses the same enum as the top-level `intent_kind`.
    </ResponseField>

    <ResponseField name="fragments[].status" type="string" required>
      Proof status for this specific fragment — `Proven` or `Suspected`.
    </ResponseField>

    <ResponseField name="fragments[].confidence" type="string" required>
      Confidence for this specific fragment — `High`, `Medium`, or `Low`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Usage Guidance

### Building a classification badge

Use the combination of `status` and `confidence` to render a trust indicator:

```
Proven  + High   → green badge, no caveat
Proven  + Medium → green badge, optional tooltip
Suspected + *    → yellow badge, always show caveat
* + Low          → grey badge, "classification uncertain"
```

### Selecting layouts

Use `intent_kind` — not `intent_label` — for conditional rendering. Labels may be localised or updated in minor releases; `intent_kind` is the stable programmatic identifier.

```js theme={null}
switch (classification.intent_kind) {
  case "AggregatedSwap":
  case "DirectSwap":
    return <SwapLayout />;
  case "AddLiquidity":
  case "RemoveLiquidity":
    return <LiquidityLayout />;
  default:
    return <GenericLayout />;
}
```

### Handling delegated transactions

Always check `actor_matches_signer` before displaying economics. When it is `false`, the `economics` object describes the **actor**, not the signer:

```js theme={null}
const displayAddress = classification.actor_matches_signer
  ? tx.signer
  : classification.actor;

const notice = !classification.actor_matches_signer
  ? `Executed on behalf of ${classification.actor}`
  : null;
```