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

# inventory_deltas — Per-Address, Per-Asset Token Flows

> inventory_deltas is an array of per-subject, per-asset value changes — the raw token flows behind the economics summary in TxReport.

`inventory_deltas` contains every asset balance change for every address involved in the transaction. These are the raw token flows that underlie the `economics` summary — where `economics` gives you a curated financial view of the elected actor, `inventory_deltas` gives you the full, unfiltered picture of what moved and where.

Each entry in the array represents a **single directional change** for a single address and a single asset. A two-sided swap between addresses A and B will produce at least four entries: an outflow and an inflow for each party.

## Example Entry

```json theme={null}
{
  "subject": "0xbdb3ba9ffe392549e1f8658dd2630c141fdf47b6",
  "asset_lane": "0x3387b868a29a814a23cde0f9b7899d37165b16ad8d7552ba4e005bd7074c7fec",
  "asset_label": "USDC",
  "direction": "Inflow",
  "quantity": "11044.505802",
  "signed_quantity": "11044505802",
  "usd": { "text": "$11044.50", "available": true },
  "price_source": "coingecko",
  "price_confidence": "High"
}
```

## Fields

<ResponseField name="subject" type="string" required>
  Checksummed Ethereum address whose balance changed. This may be any address involved in the transaction — the signer, the elected actor, a protocol contract, a liquidity pool, or an intermediate router.
</ResponseField>

<ResponseField name="asset_lane" type="string" required>
  Opaque, stable identifier for the asset lane. This value is stable across transactions and safe to use as a grouping or deduplication key — for example, to aggregate all flows of the same token across multiple calls.

  <Warning>
    Treat `asset_lane` as an opaque string. Its internal structure is not part of the public API and may change without a `schema_version` bump. Do not parse or derive meaning from its contents.
  </Warning>
</ResponseField>

<ResponseField name="asset_label" type="string" required>
  Human-readable label for the asset, typically the token symbol (e.g. `"USDC"`, `"WETH"`, `"UNI-V3-LP"`). Suitable for display in tables and tooltips.

  Note that labels are best-effort and sourced from on-chain metadata — they are not guaranteed to be unique across different contracts. Use `asset_lane` as the stable identifier for any logic that needs to distinguish assets.
</ResponseField>

<ResponseField name="direction" type="string" required>
  Direction of the balance change from the `subject`'s perspective. One of:

  | Value     | Meaning                                            |
  | --------- | -------------------------------------------------- |
  | `Inflow`  | The subject's balance of this asset **increased**. |
  | `Outflow` | The subject's balance of this asset **decreased**. |
</ResponseField>

<ResponseField name="quantity" type="string" required>
  Human-formatted token quantity, adjusted for the asset's decimals and expressed as a decimal string. Always positive — use `direction` to determine sign.

  **Example:** `"11044.505802"` (not `-11044.505802` for an outflow)
</ResponseField>

<ResponseField name="signed_quantity" type="string" required>
  Signed integer quantity before decimal adjustment — the raw on-chain unit count. Positive for inflows, negative for outflows. Use this field when you need precise arithmetic without floating-point rounding.

  **Example:** `"11044505802"` for 11044.505802 USDC (6 decimals)
</ResponseField>

<ResponseField name="usd" type="DisplayMoney" required>
  USD value of this delta expressed as a `DisplayMoney` object — `{ text, available, reason? }`. Always check `available` before parsing `text`. Will be unavailable when the asset could not be priced.

  See the [economics](/docs/api-reference/economics) page for the full `DisplayMoney` shape.
</ResponseField>

<ResponseField name="price_source" type="string | null">
  The data source used to price this asset (e.g. `"coingecko"`, `"on_chain_oracle"`, `"uniswap_v3_twap"`). `null` when the asset was not priced or the source is unknown.

  This field is intended for audit trails and debugging — it should not be surfaced in consumer-facing UIs.
</ResponseField>

<ResponseField name="price_confidence" type="string | null">
  Confidence in the price used for this delta — `"High"`, `"Medium"`, or `"Low"`. `null` when the asset was not priced.

  Consider surfacing this when `"Low"` to indicate that a USD figure may not be reliable. Hide it entirely for `"High"` and `"Medium"` in standard UIs.
</ResponseField>

## Client Guidance

### Display formatting

Use `direction` and `quantity` together to render signed display values. Never rely on `signed_quantity` for display — it is a raw integer before decimal adjustment and will confuse users.

```js theme={null}
function formatDelta(delta) {
  const sign = delta.direction === "Inflow" ? "+" : "-";
  return `${sign}${delta.quantity} ${delta.asset_label}`;
}

// → "+11044.505802 USDC"
// → "-8.238920 WETH"
```

### Using asset\_lane as a stable ID

`asset_lane` is the right key for any grouping or deduplication logic. `asset_label` alone is not unique:

```js theme={null}
// ✅ Group by stable lane ID
const byAsset = Object.groupBy(inventory_deltas, d => d.asset_lane);

// ❌ Don't group by label — two different ERC-20s can share a symbol
const byLabel = Object.groupBy(inventory_deltas, d => d.asset_label);
```

### Hiding internal fields

`price_source` and `price_confidence` are diagnostic fields. Keep them out of consumer-facing UIs unless you are building a dedicated analytics or debugging surface:

```js theme={null}
// Strip before passing to a display component
const { price_source, price_confidence, ...displayDelta } = delta;
```

## Common Patterns

### Per-address summary

Group by `subject` to build a wallet-level view of who gained and who lost in the transaction:

```js theme={null}
const perAddress = Object.groupBy(inventory_deltas, d => d.subject);

for (const [address, deltas] of Object.entries(perAddress)) {
  const inflows  = deltas.filter(d => d.direction === "Inflow");
  const outflows = deltas.filter(d => d.direction === "Outflow");
  // render address card with inflows/outflows
}
```

### Per-token flow

Group by `asset_lane` (not `asset_label`) to see the net movement of each token across all addresses:

```js theme={null}
const perAsset = Object.groupBy(inventory_deltas, d => d.asset_lane);
```

### Received-assets list

Filter to the elected actor's inflows to reconstruct what they received — equivalent to `economics.token_in` but machine-parseable:

```js theme={null}
const actor = classification.actor;
const received = inventory_deltas.filter(
  d => d.subject === actor && d.direction === "Inflow"
);
```

### Largest movements first

Sort by USD value descending to surface the most significant flows at a glance. Since `usd.text` is a formatted string, parse the numeric portion first:

```js theme={null}
function parseUsd(dm) {
  if (!dm.available) return 0;
  return parseFloat(dm.text.replace(/[^0-9.\-]/g, "")) || 0;
}

const sorted = [...inventory_deltas].sort(
  (a, b) => parseUsd(b.usd) - parseUsd(a.usd)
);
```

<Tip>
  For the most common use cases — displaying what an address sent and received — prefer `economics.token_in` and `economics.token_out` which are already formatted for display. Reach into `inventory_deltas` when you need per-asset USD values, multi-address breakdowns, or programmatic access to individual flows.
</Tip>