agent.allocation is the invocation-start budget and attribution snapshot, not shared-wallet
holdings or a signing boundary. Construction fails if Circuit cannot build it.
holdings is a closed union narrowed on kind. Every row, whatever its kind, carries network,
asset, tokenId, symbol, signed decimal quantity, priceUsd, entryPriceUsd,
valueUsd, unrealizedPnlUsd and pricedAt, which is set whenever priceUsd is. token adds amountRaw, the exact base units swap and
transfer requests take, and its decimals. perp is Hyperliquid exposure and prediction is a
Polymarket outcome-token bet; each adds its own venue fields at the top level of the row.
asset is the string that network’s operations take: a contract address or mint for transfers and
swaps; on hypercore a token holding’s asset is the token index (0 is Core USDC) while an order’s
asset comes from agent.data (BTC, xyz:GOLD) or spotMarkets.list() (@107);
KRAKEN:XBT matches a Kraken catalog base or quote; a perp or prediction holding’s asset goes
into orders and triggers. tokenId is null unless the holding is an ERC-1155 id. Circuit asset keys
are not exposed.
entryPriceUsd is this session’s own average entry, priceUsd the current price of one whole unit,
and unrealizedPnlUsd the difference across quantity. Each is null when Circuit holds no such
price; null means unknown, never zero. valueUsd is quantity times priceUsd, which for a perp
is signed notional exposure rather than collateral.
The snapshot is immutable for one invocation. Track dependent effects locally; the next trigger
receives committed changes. Amounts and quantities remain exact strings. See
wallets and allocations.
Polymarket enrichment can be null when venue metadata or payout reads fail. Exact share quantities remain present, and errors explains missing facts. Treat unknown redeemability or price as unknown; execution rechecks its own prerequisites.