> ## Documentation Index
> Fetch the complete documentation index at: https://docs.circuit.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Holdings

> Read the session budget and attributed holdings used to size agent work.

`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](../concepts/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.