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

# economics — Actor Economic Summary in a TxReport

> The economics object summarizes value flow for the elected actor — token in/out, net USD, gas fee, realized PnL, valuation coverage, and warnings.

The `economics` object gives the financial summary for the elected economic actor. It combines inflows, outflows, gas cost, pricing coverage, and any realized profit into a single curated object. Rather than asking you to aggregate raw token deltas yourself, `economics` pre-computes the most useful financial views and surfaces any caveats through `warnings` and `DisplayMoney.available`.

## Example

```json theme={null}
{
  "subject": "0xbdb3ba9ffe392549e1f8658dd2630c141fdf47b6",
  "fee_usd": { "text": "$3.14", "available": true },
  "inflow_usd": { "text": "$18533.93", "available": true },
  "net_usd_before_gas": { "text": "$-77.83", "available": true },
  "net_usd_after_gas": { "text": "—", "available": false, "reason": "gas price unavailable" },
  "token_in": "248.358547 DAI, 6789.606592 USDT, 11044.505802 USDC",
  "token_out": "8.238920 WETH",
  "structural_profit_usd": { "text": "$0", "available": true },
  "realized_pnl": { "supported": false, "reason": "requires_multi_transaction_state", "entries": [] },
  "valuation": { "priced_assets": 10, "total_assets": 10, "unpriced_assets": [] },
  "warnings": ["IntentActorDiffersFromSigner"]
}
```

## DisplayMoney Shape

Many fields in `economics` use the `DisplayMoney` type — a small wrapper that couples a formatted value with an explicit availability flag:

```json theme={null}
{ "text": "$3.14", "available": true }
{ "text": "—",     "available": false, "reason": "gas price unavailable" }
```

<ResponseField name="DisplayMoney.text" type="string" required>
  Pre-formatted display string, e.g. `"$3.14"` or `"$-77.83"`. When `available` is `false` this is a placeholder dash (`"—"`) — do not attempt to parse it as a number.
</ResponseField>

<ResponseField name="DisplayMoney.available" type="boolean" required>
  `true` when the value was successfully computed. Always check this before parsing or displaying `text`.
</ResponseField>

<ResponseField name="DisplayMoney.reason" type="string">
  Human-readable explanation of why the value is unavailable. Only present when `available` is `false`. Examples: `"gas price unavailable"`, `"unpriced asset in flow"`.
</ResponseField>

<Warning>
  Always gate on `DisplayMoney.available` before rendering a monetary figure. Displaying the placeholder `"—"` as a dollar amount will confuse users. Show a fallback such as `"N/A"` or a tooltip with the `reason` instead.
</Warning>

## Fields

<ResponseField name="subject" type="string" required>
  Checksummed address of the actor whose economics are summarized. Matches `classification.actor`.
</ResponseField>

<ResponseField name="fee_usd" type="DisplayMoney" required>
  Gas fee paid for the transaction, expressed in USD. This is the absolute gas cost to the network — it is **always negative** for the signer but shown as a positive magnitude here.
</ResponseField>

<ResponseField name="inflow_usd" type="DisplayMoney" required>
  Gross USD value of all assets received by the subject in this transaction. This is **not** profit — it is the raw received value before outflows are subtracted.

  See the [Important Distinction](#important-distinction-inflow-vs-net) callout below.
</ResponseField>

<ResponseField name="net_usd_before_gas" type="DisplayMoney" required>
  Net economic change for the subject before accounting for gas: `inflow_usd − outflow_usd`. A negative value means the subject sent more than they received (e.g. a purchase or a swap with slippage).
</ResponseField>

<ResponseField name="net_usd_after_gas" type="DisplayMoney" required>
  Net change including the gas fee: `net_usd_before_gas − fee_usd`. Will be unavailable (`available: false`) when gas price data cannot be reliably determined at analysis time.
</ResponseField>

<ResponseField name="token_in" type="string" required>
  Human-readable, comma-separated list of assets **received** by the subject, including quantities and symbols. Intended for display — use `inventory_deltas` for machine-parseable per-asset flows.

  **Example:** `"248.358547 DAI, 6789.606592 USDT, 11044.505802 USDC"`
</ResponseField>

<ResponseField name="token_out" type="string" required>
  Human-readable, comma-separated list of assets **sent** by the subject. Same format as `token_in`.

  **Example:** `"8.238920 WETH"`
</ResponseField>

<ResponseField name="structural_profit_usd" type="DisplayMoney" required>
  Profit that is structurally deterministic within this single transaction — for example, the net gain from an atomic arbitrage. Zero for ordinary swaps and transfers where no within-transaction profit is detectable.
</ResponseField>

<ResponseField name="realized_pnl" type="object" required>
  Realized profit-and-loss for the subject, when the engine has enough state to compute it.

  <Expandable title="realized_pnl fields">
    <ResponseField name="realized_pnl.supported" type="boolean" required>
      `true` when realized PnL was successfully computed for this transaction.
    </ResponseField>

    <ResponseField name="realized_pnl.basis" type="string | null">
      Accounting basis used. `"self_closing_atomic_flow"` is the only currently supported basis — it applies to transactions where the position is both opened and closed within the same block. `null` when `supported` is `false`.
    </ResponseField>

    <ResponseField name="realized_pnl.gross_usd" type="DisplayMoney">
      Gross realized PnL before fees (DisplayMoney). Always check `available` before rendering. Present only when `supported` is `true`.
    </ResponseField>

    <ResponseField name="realized_pnl.net_usd" type="DisplayMoney">
      Net realized PnL after fees (DisplayMoney). Always check `available` before rendering. Present only when `supported` is `true`.
    </ResponseField>

    <ResponseField name="realized_pnl.reason" type="string | null">
      Machine-readable reason why PnL is unsupported. Examples: `"requires_multi_transaction_state"`, `"unpriced_asset"`. `null` when `supported` is `true`.
    </ResponseField>

    <ResponseField name="realized_pnl.entries" type="array" required>
      Per-beneficiary PnL entries, each scoped to a single address and asset. Empty when `supported` is `false`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="valuation" type="object" required>
  Pricing coverage metadata — how many assets in this transaction were successfully priced.

  <Expandable title="valuation fields">
    <ResponseField name="valuation.snapshot_id" type="string | null">
      Identifier of the price snapshot used for valuation. Useful for reproducibility audits.
    </ResponseField>

    <ResponseField name="valuation.priced_assets" type="number" required>
      Count of assets for which a USD price was available.
    </ResponseField>

    <ResponseField name="valuation.total_assets" type="number" required>
      Total count of distinct assets encountered in the transaction.
    </ResponseField>

    <ResponseField name="valuation.unpriced_assets" type="array" required>
      List of asset identifiers (lane IDs or labels) for which no price was available. When this array is non-empty, all `DisplayMoney` fields derived from those assets will have `available: false`.
    </ResponseField>

    <ResponseField name="valuation.price_warning" type="string | null">
      Optional free-text warning about pricing quality (e.g. stale price, low liquidity source).
    </ResponseField>

    <ResponseField name="valuation.refusals" type="array">
      List of assets the pricing engine explicitly declined to price (distinct from assets it simply couldn't find). Refusals typically indicate known illiquid or manipulable tokens.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="warnings" type="array" required>
  Array of machine-readable economic anomaly warning codes. An empty array means no anomalies were detected.

  | Warning code                   | Meaning                                                                                          |
  | ------------------------------ | ------------------------------------------------------------------------------------------------ |
  | `IntentActorDiffersFromSigner` | The economic actor is not the transaction signer — economics describe the actor, not the signer. |
  | `PartialValuation`             | One or more assets could not be priced; USD totals are incomplete.                               |
  | `StalePrice`                   | At least one price used is outside the freshness threshold.                                      |
</ResponseField>

## Important Distinction: Inflow vs. Net

<Note>
  **`inflow_usd` is gross received value. `net_usd_before_gas` is the subject's net economic change.**

  For a swap of $10,000 USDC into $9,998 WETH:

  * `inflow_usd` ≈ **\$9,998** — the value of WETH received
  * `net_usd_before_gas` ≈ \*\*$-2** — net change (received $9,998, spent \$10,000)

  Do not display `inflow_usd` as "profit" or "gain" — always use `net_usd_before_gas` or `net_usd_after_gas` for net economic change.
</Note>

## Handling Unavailable Values

```js theme={null}
function displayMoney(dm) {
  if (!dm.available) {
    return dm.reason
      ? `N/A (${dm.reason})`
      : "N/A";
  }
  return dm.text;
}

// Usage
displayMoney(economics.net_usd_after_gas);
// → "N/A (gas price unavailable)"  when unavailable
// → "$-80.97"                       when available
```