economics — Actor Economic Summary in a TxReport

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

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

{ "text": "$3.14", "available": true }
{ "text": "—",     "available": false, "reason": "gas price unavailable" }

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.

boolean

required

true when the value was successfully computed. Always check this before parsing or displaying text.

string

Human-readable explanation of why the value is unavailable. Only present when available is false. Examples: "gas price unavailable", "unpriced asset in flow".

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.

Fields

string

required

Checksummed address of the actor whose economics are summarized. Matches classification.actor.

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.

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 callout below.

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

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.

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"

string

required

Human-readable, comma-separated list of assets sent by the subject. Same format as token_in.Example: "8.238920 WETH"

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.

object

required

Realized profit-and-loss for the subject, when the engine has enough state to compute it.

Show realized_pnl fields

boolean

required

true when realized PnL was successfully computed for this transaction.

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.

DisplayMoney

Gross realized PnL before fees (DisplayMoney). Always check available before rendering. Present only when supported is true.

DisplayMoney

Net realized PnL after fees (DisplayMoney). Always check available before rendering. Present only when supported is true.

string | null

Machine-readable reason why PnL is unsupported. Examples: "requires_multi_transaction_state", "unpriced_asset". null when supported is true.

array

required

Per-beneficiary PnL entries, each scoped to a single address and asset. Empty when supported is false.

object

required

Pricing coverage metadata — how many assets in this transaction were successfully priced.

Show valuation fields

string | null

Identifier of the price snapshot used for valuation. Useful for reproducibility audits.

number

required

Count of assets for which a USD price was available.

number

required

Total count of distinct assets encountered in the transaction.

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.

string | null

Optional free-text warning about pricing quality (e.g. stale price, low liquidity source).

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.

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.

Important Distinction: Inflow vs. Net

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.

Handling Unavailable Values

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

Endpoints

Response Schema

Reference

economics — Actor Economic Summary in a TxReport

Example

DisplayMoney Shape

Fields

Important Distinction: Inflow vs. Net

Handling Unavailable Values

​Example

​DisplayMoney Shape

​Fields

​Important Distinction: Inflow vs. Net

​Handling Unavailable Values

Example

DisplayMoney Shape

Fields

Important Distinction: Inflow vs. Net

Handling Unavailable Values